[groff] 14/14: [man pages]: Ship compilations in UTF-8 text, PDF.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 52eeb52073806d09e24e35b38ba586d0b4d1f6e1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jan 25 00:00:19 2022 +1100

    [man pages]: Ship compilations in UTF-8 text, PDF.
    
    Localization support and the resolution of Savannah #61266 have made it
    practical to batch-render all of groff's man pages as a single giant
    document.  Provide PDF and UTF-8 text (with ECMA-48 escape sequences,
    but not the italic attribute or OSC 8 sequences).
    
    Reasons for this addition include: {1} it is now possible, whereas I
    don't believe it was in any previous groff release; {2} many people
    still don't realize how much more pleasant reading typeset man pages can
    be (while a subjective assessment, I'm not alone[1]); {3} providing
    these forms permits full-text searching of groff's entire man page
    corpus via the PDF viewer or a pager like "less -R", the latter without
    sacrificing the style variations of the text that aid the reader to
    comprehend the material; {4} sentimentally, it honors the 50th
    anniversary of the first Unix manual (dated 3 November 1971)
    <https://www.bell-labs.com/usr/dmr/www/1stEdman.html>.
    
    * doc/doc.am (PROCESSEDDOCFILES): Add
      'doc/groff-man-pages.{pdf,utf8.txt}'.
    
      (GROFF_MAN_PAGES{1,2,3}): Add new macro storing names of all man pages
      generated in the build tree.  Motivate the reason for 3 variables in a
      comment (it's due to groff locale switching).
    
      (GROFF_MAN_PAGES_ALL): Add convenience macro for use in dependency
      lists required by...
    
      ('doc/groff-man-pages.{pdf,utf8.txt}'): ...these targets.  Generate
      pages with the lint dial turned all the way up.
    
    Fixes <https://savannah.gnu.org/bugs/?61900>.
    
    [1] "The manual was intended to be typeset; some detail is sacrificed on
    terminals." (man(1), _Unix Time-Sharing System Programmer's Manual_,
    Eighth Edition, Volume 1, February 1985)
    
    Also bump copyright range.  Today's commit to the file should do it for
    2022; for 2021, see below.  It wasn't _all_ mindless churn, I promise.
    
    $ COLUMNS=72 git diff --stat 'HEAD@{2020-12-31}' 'HEAD@{2021-12-31}' \
     -- doc/doc.am
     doc/doc.am | 316 +++++++++++++++++++++++++++++++----------------------
     1 file changed, 188 insertions(+), 128 deletions(-)
---
 ChangeLog  | 38 +++++++++++++++++++++++++
 doc/doc.am | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 131 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index 122bb765..910c0d0f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,41 @@
+2022-01-24  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man pages]: Ship compilations in UTF-8 text and PDF.
+
+       Localization support and the resolution of Savannah #61266 have
+       made it practical to batch-render all of groff's man pages as a
+       single giant document.  Provide PDF and UTF-8 text (with ECMA-48
+       escape sequences, but not the italic attribute or OSC 8
+       sequences).
+
+       Reasons for this addition include: {1} it is now possible,
+       whereas I don't believe it was in any previous groff release;
+       {2} many people still don't realize how much more pleasant
+       reading typeset man pages can be (while a subjective assessment,
+       I'm not alone[1]); {3} providing these forms permits full-text
+       searching of groff's entire man page corpus via the PDF viewer
+       or a pager like "less -R", the latter without sacrificing the
+       style variations of the text that aid the reader to comprehend
+       the material; {4} sentimentally, it honors the 50th anniversary
+       of the first Unix manual (dated 3 November 1971)
+       <https://www.bell-labs.com/usr/dmr/www/1stEdman.html>.
+
+       * doc/doc.am (PROCESSEDDOCFILES): Add
+       'doc/groff-man-pages.{pdf,utf8.txt}'.
+       (GROFF_MAN_PAGES{1,2,3}): Add new macro storing names of all man
+       pages generated in the build tree.  Motivate the reason for 3
+       variables in a comment (it's due to groff locale switching).
+       (GROFF_MAN_PAGES_ALL): Add convenience macro for use in
+       dependency lists required by...
+       ('doc/groff-man-pages.{pdf,utf8.txt}'): ...these targets.
+       Generate pages with the lint dial turned all the way up.
+
+       Fixes <https://savannah.gnu.org/bugs/?61900>.
+
+       [1] "The manual was intended to be typeset; some detail is
+       sacrificed on terminals." (man(1), _Unix Time-Sharing System
+       Programmer's Manual_, Eighth Edition, Volume 1, February 1985)
+
 2022-01-24  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [man]: Commit c64fd60dff was not quite cooked.  The localized
diff --git a/doc/doc.am b/doc/doc.am
index 359c85f7..13431f5f 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -1,4 +1,4 @@
-# Copyright (C) 2002-2020 Free Software Foundation, Inc.
+# Copyright (C) 2002-2022 Free Software Foundation, Inc.
 # Original Makefile.sub written by Werner Lemberg <wl@gnu.org>.
 # Adapted to Automake by Bertrand Garrigues
 #   (bertrand.garrigues@laposte.net).
@@ -63,6 +63,8 @@ GENERATEDDOCFILES = \
   doc/meref.me
 # Files generated in the build tree
 PROCESSEDDOCFILES = \
+  doc/groff-man-pages.pdf \
+  doc/groff-man-pages.utf8.txt \
   doc/meref.ps \
   doc/meintro.ps \
   doc/meintro_fr.ps \
@@ -142,6 +144,96 @@ EXTRA_DIST += \
   doc/gnu.xpm \
   doc/txi-en.tex
 
+# Introduce variables to house the groff man pages.  We break the list
+# of page sources into multiple chunks because we have to load Swedish
+# localization before formatting groff_mmse.7 and then reload English
+# localization afterward.  This also serves as a test of groff locale
+# switching; being lazy and shunting groff_mmse.7 off to the end of the
+# document would not achieve this goal (and not loading Swedish
+# localization at all to format it would be gauche).
+GROFF_MAN_PAGES1 = \
+  src/utils/addftinfo/addftinfo.1 \
+  src/utils/afmtodit/afmtodit.1 \
+  contrib/chem/chem.1 \
+  src/preproc/eqn/eqn.1 \
+  contrib/eqn2graph/eqn2graph.1 \
+  contrib/gdiffmk/gdiffmk.1 \
+  contrib/glilypond/glilypond.1 \
+  contrib/gperl/gperl.1 \
+  contrib/gpinyin/gpinyin.1 \
+  contrib/grap2graph/grap2graph.1 \
+  src/preproc/grn/grn.1 \
+  src/devices/grodvi/grodvi.1 \
+  src/roff/groff/groff.1 \
+  src/utils/grog/grog.1 \
+  src/devices/grohtml/grohtml.1 \
+  src/devices/grolbp/grolbp.1 \
+  src/devices/grolj4/grolj4.1 \
+  src/devices/gropdf/gropdf.1 \
+  src/devices/grops/grops.1 \
+  src/devices/grotty/grotty.1 \
+  src/devices/xditview/gxditview.1 \
+  src/utils/hpftodit/hpftodit.1 \
+  src/utils/indxbib/indxbib.1 \
+  src/utils/lkbib/lkbib.1 \
+  src/utils/lookbib/lookbib.1 \
+  contrib/mm/mmroff.1 \
+  src/preproc/eqn/neqn.1 \
+  src/roff/nroff/nroff.1 \
+  src/devices/gropdf/pdfmom.1 \
+  contrib/pdfmark/pdfroff.1 \
+  src/utils/pfbtops/pfbtops.1 \
+  src/preproc/pic/pic.1 \
+  contrib/pic2graph/pic2graph.1 \
+  src/preproc/preconv/preconv.1 \
+  src/preproc/refer/refer.1 \
+  src/preproc/soelim/soelim.1 \
+  src/preproc/tbl/tbl.1 \
+  src/utils/tfmtodit/tfmtodit.1 \
+  src/roff/troff/troff.1 \
+  src/utils/xtotroff/xtotroff.1 \
+  contrib/groff_filenames/groff_filenames.5 \
+  man/groff_font.5 \
+  man/groff_out.5 \
+  man/groff_tmac.5 \
+  src/devices/grolj4/lj4_font.5 \
+  man/ditroff.7 \
+  man/groff.7 \
+  man/groff_char.7 \
+  man/groff_diff.7 \
+  contrib/hdtbl/groff_hdtbl.7 \
+  tmac/groff_man.7 \
+  tmac/groff_man_style.7 \
+  tmac/groff_mdoc.7 \
+  tmac/groff_me.7 \
+  contrib/mm/groff_mm.7
+
+GROFF_MAN_PAGES2 = \
+  contrib/mm/groff_mmse.7
+
+GROFF_MAN_PAGES3 = \
+  contrib/mom/groff_mom.7 \
+  tmac/groff_ms.7 \
+  contrib/rfc1345/groff_rfc1345.7 \
+  tmac/groff_trace.7 \
+  tmac/groff_www.7 \
+  man/roff.7
+
+GROFF_MAN_PAGES_ALL = $(GROFF_MAN_PAGES1) $(GROFF_MAN_PAGES2) \
+  $(GROFF_MAN_PAGES3)
+
+doc/groff-man-pages.pdf: $(GROFF_MAN_PAGES_ALL)
+       $(GROFF_V)$(DOC_GROFF) -Tpdf -P-e -mandoc -rU0 \
+         -rCHECKSTYLE=3 $(GROFF_MAN_PAGES1) \
+         $(tmac_srcdir)/sv.tmac $(GROFF_MAN_PAGES2) \
+         $(tmac_srcdir)/en.tmac $(GROFF_MAN_PAGES3) > $@
+
+doc/groff-man-pages.utf8.txt: $(GROFF_MAN_PAGES_ALL)
+       $(GROFF_V)$(DOC_GROFF) -Tutf8 -mandoc -rC1 -rU1 \
+         -rCHECKSTYLE=3 $(GROFF_MAN_PAGES1) \
+         $(tmac_srcdir)/sv.tmac $(GROFF_MAN_PAGES2) \
+         $(tmac_srcdir)/en.tmac $(GROFF_MAN_PAGES3) > $@
+
 doc/meintro.me: $(doc_srcdir)/meintro.me.in
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
        && $(DOC_SED) $< >$@