ryan77627/guix
1
0
Fork 0
mirror of https://git.in.rschanz.org/ryan77627/guix.git synced 2025-01-11 21:59:08 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source 
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'.
This commit is contained in:
Ludovic Courtès 2020-10-17 14:32:53 +02:00
parent 0f7d0743ed
commit db1d445357
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
1 changed files with 51 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
doc/build.scm
View file

@ -42,6 +42,7 @@
(gnu packages tex) (gnu packages tex)
(ice-9 match) (ice-9 match)
(srfi srfi-19) (srfi srfi-19)
(srfi srfi-26)
(srfi srfi-71)) (srfi srfi-71))
(define file-append* (define file-append*
@ -595,6 +596,8 @@ (define multi-node-anchors
(define* (html-manual source #:key (languages %languages) (define* (html-manual source #:key (languages %languages)
(version "0.0") (version "0.0")
(manual %manual) (manual %manual)
(mono-node-indexes (map list languages))
(split-node-indexes (map list languages))
(date 1) (date 1)
(options %makeinfo-html-options)) (options %makeinfo-html-options))
"Return the HTML manuals built from SOURCE for all LANGUAGES, with the given "Return the HTML manuals built from SOURCE for all LANGUAGES, with the given
@ -683,6 +686,8 @@ (define (language->texi-file-name language)
(let* ((name (string-append manual "-html-manual")) (let* ((name (string-append manual "-html-manual"))
(manual (computed-file name build))) (manual (computed-file name build)))
(syntax-highlighted-html manual (syntax-highlighted-html manual
#:mono-node-indexes mono-node-indexes
#:split-node-indexes split-node-indexes
#:name (string-append name "-highlighted")))) #:name (string-append name "-highlighted"))))
(define* (pdf-manual source #:key (languages %languages) (define* (pdf-manual source #:key (languages %languages)
@ -1029,6 +1034,8 @@ (define* (pdf+html-manual source
#:key (languages %languages) #:key (languages %languages)
(version "0.0") (version "0.0")
(date (time-second (current-time time-utc))) (date (time-second (current-time time-utc)))
(mono-node-indexes (map list %languages))
(split-node-indexes (map list %languages))
(manual %manual)) (manual %manual))
"Return the union of the HTML and PDF manuals, as well as the indexes." "Return the union of the HTML and PDF manuals, as well as the indexes."
(directory-union (string-append manual "-manual") (directory-union (string-append manual "-manual")
@ -1039,7 +1046,12 @@ (define* (pdf+html-manual source
#:version version #:version version
#:manual manual)) #:manual manual))
(list html-manual-indexes (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)) #:copy? #t))
(define (latest-commit+date directory) (define (latest-commit+date directory)
@ -1056,19 +1068,52 @@ (define (latest-commit+date directory)
(let* ((root (canonicalize-path (let* ((root (canonicalize-path
(string-append (current-source-directory) "/.."))) (string-append (current-source-directory) "/..")))
(commit date (latest-commit+date root)) (commit date (latest-commit+date root))
(version (or (getenv "GUIX_MANUAL_VERSION")
(string-take commit 7)))
(select? (let ((vcs? (git-predicate root))) (select? (let ((vcs? (git-predicate root)))
(lambda (file stat) (lambda (file stat)
(and (vcs? file stat) (and (vcs? file stat)
;; Filter out this file. ;; 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) (format (current-error-port)
"building manual from work tree around commit ~a, ~a~%" "building manual from work tree around commit ~a, ~a~%"
commit commit
(let* ((time (make-time time-utc 0 date)) (let* ((time (make-time time-utc 0 date))
(date (time-utc->date time))) (date (time-utc->date time)))
(date->string date "~e ~B ~Y"))) (date->string date "~e ~B ~Y")))
(pdf+html-manual (local-file root "guix" #:recursive? #t
#:select? select?) (pdf+html-manual source
#:version (or (getenv "GUIX_MANUAL_VERSION") ;; Always use the identifier index of GUIX-MANUAL. That
(string-take commit 7)) ;; 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)) #:date date))