03/09: doc: Allow code snippets in the cookbook to link to the manual.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit db1d445357ad7a8221683f44ff7c66e8e408206c
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Sat Oct 17 14:32:53 2020 +0200

    doc: Allow code snippets in the cookbook to link to the manual.
    
    Until now, only code snippets in the manual itself would contain links
    to identifier definitions.  Now snippets in the cookbook also link to
    definitions in the manual.
    
    * doc/build.scm (html-manual): Add #:mono-node-indexes and 
#:multi-node-indexes
    and pass it to 'syntax-highlighted-html'.
    (pdf+html-manual): Likewise, and pass it to 'html-manual'.
    <top level>: Factorize 'version' and 'source'.  Define 'guix-manual',
    'mono-node-indexes', and 'split-node-indexes'.  Pass #:mono-node-indexes
    and #:split-node-indexes to 'pdf+html-manual'.
---
 doc/build.scm | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/doc/build.scm b/doc/build.scm
index 980d11c..cc107ec 100644
--- a/doc/build.scm
+++ b/doc/build.scm
@@ -42,6 +42,7 @@
              (gnu packages tex)
              (ice-9 match)
              (srfi srfi-19)
+             (srfi srfi-26)
              (srfi srfi-71))
 
 (define file-append*
@@ -595,6 +596,8 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo 
--html')."
 (define* (html-manual source #:key (languages %languages)
                       (version "0.0")
                       (manual %manual)
+                      (mono-node-indexes (map list languages))
+                      (split-node-indexes (map list languages))
                       (date 1)
                       (options %makeinfo-html-options))
   "Return the HTML manuals built from SOURCE for all LANGUAGES, with the given
@@ -683,6 +686,8 @@ makeinfo OPTIONS."
   (let* ((name   (string-append manual "-html-manual"))
          (manual (computed-file name build)))
     (syntax-highlighted-html manual
+                             #:mono-node-indexes mono-node-indexes
+                             #:split-node-indexes split-node-indexes
                              #:name (string-append name "-highlighted"))))
 
 (define* (pdf-manual source #:key (languages %languages)
@@ -1029,6 +1034,8 @@ languages:\n"
                           #:key (languages %languages)
                           (version "0.0")
                           (date (time-second (current-time time-utc)))
+                          (mono-node-indexes (map list %languages))
+                          (split-node-indexes (map list %languages))
                           (manual %manual))
   "Return the union of the HTML and PDF manuals, as well as the indexes."
   (directory-union (string-append manual "-manual")
@@ -1039,7 +1046,12 @@ languages:\n"
                                 #:version version
                                 #:manual manual))
                         (list html-manual-indexes
-                              html-manual pdf-manual))
+                              (lambda (source . args)
+                                (apply html-manual source
+                                       #:mono-node-indexes mono-node-indexes
+                                       #:split-node-indexes split-node-indexes
+                                       args))
+                              pdf-manual))
                    #:copy? #t))
 
 (define (latest-commit+date directory)
@@ -1056,19 +1068,52 @@ commit date (an integer)."
 (let* ((root (canonicalize-path
               (string-append (current-source-directory) "/..")))
        (commit date (latest-commit+date root))
+       (version (or (getenv "GUIX_MANUAL_VERSION")
+                    (string-take commit 7)))
        (select? (let ((vcs? (git-predicate root)))
                   (lambda (file stat)
                     (and (vcs? file stat)
                          ;; Filter out this file.
-                         (not (string=? (basename file) "build.scm")))))))
+                         (not (string=? (basename file) "build.scm"))))))
+       (source (local-file root "guix" #:recursive? #t
+                           #:select? select?)))
+
+  (define guix-manual
+    (html-manual source
+                 #:manual "guix"
+                 #:version version
+                 #:date date))
+
+  (define mono-node-indexes
+    ;; Alist of indexes for GUIX-MANUAL, where each key is a language code and
+    ;; each value is a file-like object containing the identifier index.
+    (html-identifier-indexes guix-manual ""
+                             #:base-url (if (string=? %manual "guix")
+                                            (const "")
+                                            (cut string-append "/manual/" <>))
+                             #:languages %languages))
+
+  (define split-node-indexes
+    ;; Likewise for the split-node variant of GUIX-MANUAL.
+    (html-identifier-indexes guix-manual "/html_node"
+                             #:base-url (if (string=? %manual "guix")
+                                            (const "")
+                                            (cut string-append "/manual/" <>
+                                                 "/html_node"))
+                             #:languages %languages))
+
   (format (current-error-port)
           "building manual from work tree around commit ~a, ~a~%"
           commit
           (let* ((time (make-time time-utc 0 date))
                  (date (time-utc->date time)))
             (date->string date "~e ~B ~Y")))
-  (pdf+html-manual (local-file root "guix" #:recursive? #t
-                               #:select? select?)
-                   #:version (or (getenv "GUIX_MANUAL_VERSION")
-                                 (string-take commit 7))
+
+  (pdf+html-manual source
+                   ;; Always use the identifier index of GUIX-MANUAL.  That
+                   ;; way, "guix-cookbook" can contain link to definitions
+                   ;; that appear in GUIX-MANUAL.
+                   #:mono-node-indexes mono-node-indexes
+                   #:split-node-indexes split-node-indexes
+                   #:version version
                    #:date date))