doc: Use versioned manual URLs.

* doc/build.scm (stylized-html): Move to versioned manual URL.
(html-manual): Use versioned manual URL.
* doc/htmlxref.cnf (GUIX): Add /1.4.0.

Change-Id: I82048a9548894e335e7c2427a739733304a7961a
Co-authored-by: Ludovic Courtès <ludo@gnu.org>
Fixes: #5681

doc/build.scm

@@ -1,5 +1,5 @@
 ;;; GNU Guix --- Functional package management for GNU
-;;; Copyright © 2019-2022 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2019-2025 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2020 Björn Höfling <bjoern.hoefling@bjoernhoefling.de>
 ;;; Copyright © 2022 Maxim Cournoyer <maxim.cournoyer@gmail.com>
 ;;;
@@ -34,6 +34,7 @@
              (guix profiles)
              (guix utils)
              (git)
+             (gnu packages)
              (gnu packages base)
              (gnu packages compression)
              (gnu packages gawk)
@@ -52,8 +53,116 @@
 (define file-append*
   (@@ (guix self) file-append*))
 
-(define translated-texi-manuals
+(define (translated-texi-manuals source)
-  (@@ (guix self) translate-texi-manuals))
+  "Return the translated texinfo manuals built from SOURCE."
+  (define po4a
+    (specification->package "po4a"))
+
+  (define gettext-minimal
+    (specification->package "gettext-minimal"))
+
+  (define documentation
+    (file-append* source "doc"))
+
+  (define documentation-po
+    (file-append* source "po/doc"))
+
+  (define build
+    (with-imported-modules '((guix build utils) (guix build po))
+      #~(begin
+          (use-modules (guix build utils) (guix build po)
+                       (ice-9 match) (ice-9 regex) (ice-9 textual-ports)
+                       (ice-9 vlist) (ice-9 threads)
+                       (srfi srfi-1))
+
+          (define (translate-tmp-texi po source output)
+            "Translate Texinfo file SOURCE using messages from PO, and write
+the result to OUTPUT."
+            (invoke #+(file-append po4a "/bin/po4a-translate")
+              "-M" "UTF-8" "-L" "UTF-8" "-k" "0" "-f" "texinfo"
+              "-m" source "-p" po "-l" output))
+
+          (define (canonicalize-whitespace str)
+            ;; Change whitespace (newlines, etc.) in STR to #\space.
+            (string-map (lambda (chr)
+                          (if (char-set-contains? char-set:whitespace chr)
+                              #\space
+                              chr))
+                        str))
+
+          (define* (translate-texi prefix po lang
+                                   #:key (extras '()))
+            "Translate the manual for one language LANG using the PO file.
+PREFIX must be the prefix of the manual, 'guix' or 'guix-cookbook'.  EXTRAS is
+a list of extra files, such as '(\"contributing\")."
+            (for-each (lambda (file)
+                        (translate-tmp-texi po (string-append file ".texi")
+                                            (string-append file "." lang
+                                                           ".texi.tmp")))
+                      (cons prefix extras))
+
+            (for-each (lambda (file)
+                        (let* ((texi (string-append file "." lang ".texi"))
+                               (tmp  (string-append texi ".tmp")))
+                          (copy-file tmp texi)
+                          (translate-cross-references texi po)))
+                      (cons prefix extras)))
+
+          (define (available-translations directory domain)
+            ;; Return the list of available translations under DIRECTORY for
+            ;; DOMAIN, a gettext domain such as "guix-manual".  The result is
+            ;; a list of language/PO file pairs.
+            (filter-map (lambda (po)
+                          (let ((base (basename po)))
+                            (and (string-prefix? (string-append domain ".")
+                                                 base)
+                                 (match (string-split base #\.)
+                                   ((_ ... lang "po")
+                                    (cons lang po))))))
+                        (find-files directory
+                                    "\\.[a-z]{2}(_[A-Z]{2})?\\.po$")))
+
+          (define parallel-jobs
+            ;; Limit thread creation by 'n-par-for-each', mostly to put an
+            ;; upper bound on memory usage.
+            (min (parallel-job-count) 4))
+
+          (mkdir #$output)
+          (copy-recursively #$documentation "."
+                            #:log (%make-void-port "w"))
+
+          (for-each
+            (lambda (file)
+              (copy-file file (basename file)))
+            (find-files #$documentation-po ".*.po$"))
+
+          (setenv "GUIX_LOCPATH"
+                  #+(file-append glibc-utf8-locales "/lib/locale"))
+          (setenv "PATH" #+(file-append gettext-minimal "/bin"))
+          (setenv "LC_ALL" "en_US.UTF-8")
+          (setlocale LC_ALL "en_US.UTF-8")
+
+          (n-par-for-each parallel-jobs
+                          (match-lambda
+                            ((language . po)
+                             (translate-texi "guix" po language
+                                             #:extras '("contributing"))))
+                          (available-translations "." "guix-manual"))
+
+          (n-par-for-each parallel-jobs
+                          (match-lambda
+                            ((language . po)
+                             (translate-texi "guix-cookbook" po language)))
+                          (available-translations "." "guix-cookbook"))
+
+          (for-each (lambda (file)
+                      (install-file file #$output))
+                    (append
+                     (find-files "." "contributing\\..*\\.texi$")
+                     (find-files "." "guix\\..*\\.texi$")
+                     (find-files "." "guix-cookbook\\..*\\.texi$"))))))
+
+  (computed-file "guix-translated-texinfo" build))
 
 (define info-manual
   (@@ (guix self) info-manual))
@@ -78,6 +187,10 @@
       %cookbook-languages
       %manual-languages))
 
+(define %latest-guix-version
+  ;; Latest released version.
+  "1.4.0")
+
 (define (texinfo-manual-images source)
   "Return a directory containing all the images used by the user manual, taken
 from SOURCE, the root of the source tree."
@@ -184,11 +297,16 @@ as well as images, OS examples, and translations."
 (define %web-site-url
   ;; URL of the web site home page.
   (or (getenv "GUIX_WEB_SITE_URL")
-      "/software/guix/"))
+      "/"))
+
+(define %manual-css-url
+  ;; URL of the main CSS file.
+  (in-vicinity %web-site-url
+               "themes/initial/css/manual.css"))
 
 (define %makeinfo-html-options
   ;; Options passed to 'makeinfo --html'.
-  '("--css-ref=https://www.gnu.org/software/gnulib/manual.css"
+  `(,(string-append "--css-ref=" %manual-css-url)
     "-c" "EXTRA_HEAD=<meta name=\"viewport\" \
 content=\"width=device-width, initial-scale=1\" />"))
 
@@ -284,6 +402,9 @@ actual file name."
                      (loop rest))
                     ((('strong _ ...) _ ...)
                      #t)
+                    ((('span ('@ ('class "category")) ;raw Texinfo 6.8
+                             (? string-or-entity?) ...) rest ...)
+                     #t)
                     ((('span ('@ ('class "symbol-definition-category"))
                              (? string-or-entity?) ...) rest ...)
                      #t)
@@ -507,10 +628,16 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
 
                   ;; Replace the ugly <strong> used for @deffn etc., which
                   ;; translate to <dt>, with more stylable markup.
-                  (('dt (@ ('id id)) category ... ('strong thing))
+                  (('dt ('@ ('id id))             ;raw Texinfo 6.8
+                        ('span ('@ ('class "category")) category ...)
+                        ('span ('strong thing)
+                               anchor))
                    (highlight-definition id category thing '()))
-                  (('dt (@ ('id id)) category ... ('strong thing)
+                  (('dt (@ ('id id))
-                        (? space?) ('em args ...))
+                        ('span ('@ ('class "category")) category ...)
+                        ('span ('strong thing)
+                               (? space?) ('em args ...)
+                               anchor))
                    (highlight-definition id category thing args))
 
                   ((tag ('@ attributes ...) body ...)
@@ -613,9 +740,10 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
 
 (define* (stylized-html source input
                         #:key
+                        (latest-version %latest-guix-version)
                         (languages %languages)
                         (manual %manual)
-                        (manual-css-url "/static/base/css/manual.css"))
+                        (manual-css-url %manual-css-url))
   "Process all the HTML files in INPUT; add them MANUAL-CSS-URL as a <style>
 link, and add a menu to choose among LANGUAGES.  Use the Guix PO files found
 in SOURCE."
@@ -661,6 +789,14 @@ in SOURCE."
 	                 (href ,url))
                       ,label)))
 
+            (define menu-item-separator
+              ;; Thin horizontal line to separate drop-down menu items.
+              `(img (@ (class "hline")
+                       (src ,(in-vicinity
+                              #$%web-site-url
+                              "themes/initial/img/h-separator.png"))
+                       (alt ""))))
+
             (define* (navigation-bar menus #:key split-node?)
               ;; Return the navigation bar showing all of MENUS.
               `(header (@ (class "navbar"))
@@ -707,7 +843,43 @@ in SOURCE."
                                   "https://translate.fedoraproject.org/projects/guix/documentation-cookbook/"
                                   "https://translate.fedoraproject.org/projects/guix/documentation-manual/")))))
 
-            (define (stylized-html sxml file)
+            (define (version-menu-items language split-node?)
+              ;; Return the menu items to select the version of the manual of
+              ;; the type of medium (PDF, split-node, etc.).
+              (define language-extension
+                (if (string=? language "en")
+                    ""
+                    (string-append "." language)))
+
+              (define pdf-link
+                (string-append (if split-node? "../" "")
+                               #$manual language-extension ".pdf"))
+
+              (define version-links
+                (list (menu-item #$latest-version
+                                 (string-append
+                                  "/manual/" #$latest-version
+                                  "/" language
+                                  (if split-node? "/html_node" "")))
+                      (menu-item "development"
+                                 (string-append
+                                  "/manual/devel/" language
+                                  (if split-node? "/html_node" "")))
+                      menu-item-separator))
+
+              (append (if (string=? #$manual "guix")
+                          version-links
+                          '())
+                      (list (if split-node?
+                                (menu-item "single page"
+                                           (string-append "../" #$manual
+                                                          language-extension
+                                                          ".html"))
+                                (menu-item "multiple pages"
+                                           "html_node"))
+                            (menu-item "PDF" pdf-link))))
+
+            (define (stylized-html sxml file language)
               ;; Return SXML, which was read from FILE, with additional
               ;; styling.
               (define split-node?
@@ -730,9 +902,16 @@ in SOURCE."
                             ;; TODO: Add "Contribute" menu, to report
                             ;; errors, etc.
                             (list (menu-dropdown
+                                   #:label "Version"
+                                   #:items
+                                   (version-menu-items language
+                                                       split-node?))
+                                  (menu-dropdown
                                    #:label
                                    `(img (@ (alt "Language")
-                                            (src "/static/base/img/language-picker.svg")))
+                                            (src #$(in-vicinity
+                                                    %web-site-url
+                                                    "themes/initial/img/language-picker.svg"))))
                                    #:items
                                    (language-menu-items file)))
                             #:split-node? split-node?)
@@ -744,13 +923,13 @@ in SOURCE."
                   ((? string? str)
                    str))))
 
-            (define (process-html file)
+            (define (process-html file language)
               ;; Parse FILE and add links to translations.  Install the result
               ;; to #$output.
               (format (current-error-port) "processing ~a...~%" file)
               (let* ((shtml        (parameterize ((%strict-tokenizer? #t))
                                      (call-with-input-file file html->shtml)))
-                     (processed    (stylized-html shtml file))
+                     (processed    (stylized-html shtml file language))
                      (base         (string-drop file (string-length #$input)))
                      (target       (string-append #$output base)))
                 (mkdir-p (dirname target))
@@ -758,6 +937,15 @@ in SOURCE."
                   (lambda (port)
                     (write-shtml-as-html processed port)))))
 
+            (define (input-file-language file)
+              ;; Return the language code of FILE, an input file, as a string
+              ;; like "sv" or "zh-cn".
+              (match (string-tokenize (string-drop file
+                                                   (string-length #$input))
+                                      (char-set-complement
+                                       (char-set #\/)))
+                ((language _ ...) language)))
+
             ;; Install a UTF-8 locale so we can process UTF-8 files.
             (setenv "GUIX_LOCPATH"
                     #+(file-append glibc-utf8-locales "/lib/locale"))
@@ -768,7 +956,8 @@ in SOURCE."
             (n-par-for-each (parallel-job-count)
                             (lambda (file)
                               (if (string-suffix? ".html" file)
-                                  (process-html file)
+                                  (let ((language (input-file-language file)))
+                                    (process-html file language))
                                   ;; Copy FILE as is to #$output.
                                   (let* ((base   (string-drop file (string-length #$input)))
                                          (target (string-append #$output base)))
@@ -835,7 +1024,8 @@ makeinfo OPTIONS."
                       (let* ((texi (language->texi-file-name language))
                              (opts `("--html"
                                      "-c" ,(string-append "TOP_NODE_UP_URL=/manual/"
-                                                         language)
+                                                          #$%latest-guix-version
+                                                          "/" language)
                                      #$@options
                                      ,texi)))
                         (format #t "building HTML manual for language '~a'...~%"
@@ -903,11 +1093,11 @@ makeinfo OPTIONS."
                      sed
                      tar
                      texinfo
-                     texlive-base
+                     texlive-scheme-basic
                      texlive-bin        ;for GUIX_TEXMF
                      texlive-epsf
-                     texlive-fonts-ec
+                     texlive-ec
-                     texlive-tex-texinfo)))))
+                     texlive-texinfo)))))
 
   (define build
     (with-imported-modules '((guix build utils))
@@ -1293,6 +1483,7 @@ commit date (an integer)."
                          (setenv "PATH"
                                  (string-append #+tar "/bin:"
                                                 #+xz "/bin:"
+                                                #+zstd "/bin:"
                                                 #+texinfo "/bin"))
                          (invoke "tar" "xf" #$(package-source guile))
                          (mkdir-p (string-append #$output "/en/html_node"))
@@ -1356,7 +1547,9 @@ by 'html-identifier-indexes'."
 
 
 (let* ((root (canonicalize-path
-              (string-append (current-source-directory) "/..")))
+              (string-append (or (current-source-directory)
+                                 (string-append (getcwd) "/doc"))
+                             "/..")))
        (commit date (latest-commit+date root))
        (version (or (getenv "GUIX_MANUAL_VERSION")
                     (string-take commit 7)))
@@ -1403,7 +1596,8 @@ by 'html-identifier-indexes'."
     (merge-index-alists guix-split-node-indexes guile-split-node-indexes))
 
   (format (current-error-port)
-          "building manual from work tree around commit ~a, ~a~%"
+          "building manual from work tree (~a) around commit ~a, ~a~%"
+          root
           commit
           (let* ((time (make-time time-utc 0 date))
                  (date (time-utc->date time)))

doc/contributing.texi

@@ -1514,7 +1514,7 @@ that we can send the rest of the patches to.
 
 @example
 $ git send-email outgoing/0000-cover-letter.patch -a \
-      --to=guix-patches@@debbugs.gnu.org \
+      --to=guix-patches@@gnu.org \
       $(etc/teams.scm cc-members ...)
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example

doc/guix.texi

@@ -22,7 +22,7 @@
 @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
 
 @copying
-Copyright @copyright{} 2012-2022 Ludovic Courtès@*
+Copyright @copyright{} 2012-2022, 2025 Ludovic Courtès@*
 Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
 Copyright @copyright{} 2013 Nikita Karetnikov@*
 Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
@@ -642,7 +642,7 @@ to join!  @xref{Contributing}, for information about how you can help.
 
 @quotation Note
 We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
+@uref{https://guix.gnu.org/install.sh,
 shell installer script} to install Guix on top of a running GNU/Linux system,
 thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
 with the installation of the package manager, which can be done on top of a
@@ -691,14 +691,14 @@ GNU@tie{}tar and Xz.
 @c Note duplicated from the ``Installation'' node.
 @quotation Note
 We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
+@uref{https://guix.gnu.org/install.sh,
 shell installer script}.  The script automates the download, installation, and
 initial configuration steps described below.  It should be run as the root
 user.  As root, you can thus run this:
 
 @example
 cd /tmp
-wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+wget -O guix-install.sh https://guix.gnu.org/install.sh
 chmod +x guix-install.sh
 ./guix-install.sh
 @end example

doc/htmlxref.cnf

@@ -1,7 +1,7 @@
 # htmlxref.cnf - reference file for free Texinfo manuals on the web.
 # Modified by Ludovic Courtès <ludo@gnu.org> for the GNU Guix manual.
 
-htmlxrefversion=2022-12-18.15; # UTC
+htmlxrefversion=2026-01-19.09; # UTC
 
 # Copyright 2010-2020, 2022 Free Software Foundation, Inc.
 # 
@@ -415,7 +415,7 @@ guile-rpc	mono	${GS}/guile-rpc/manual/guile-rpc.html
 guile-rpc	node	${GS}/guile-rpc/manual/html_node/
 
 GUIX_ROOT = https://guix.gnu.org
-GUIX = ${GUIX_ROOT}/manual
+GUIX = ${GUIX_ROOT}/manual/1.4.0
  guix.de	mono	${GUIX}/de/guix.de.html
  guix.de	node	${GUIX}/de/html_node/
  guix.es	mono	${GUIX}/es/guix.es.html