GraphicsMagick: Documentation generator improvements.

changeset 5ad72c2bb8ff in /hg/GraphicsMagick
details: http://hg.GraphicsMagick.org/hg/GraphicsMagick?cmd=changeset;node=5ad72c2bb8ff
summary: Documentation generator improvements.

diffstat:

 ChangeLog                              |     4 +
 VisualMagick/installer/inc/version.isx |     4 +-
 doc/GNUmakefile                        |    62 +-
 doc/gmdoc2html                         |     7 +-
 doc/gmdocselect                        |     4 +-
 doc/imdoc2man                          |    19 +-
 doc/imdocselect                        |     2 -
 doc/options.imdoc                      |     4 +-
 doc/version.imdoc                      |     4 +-
 magick/version.h                       |     4 +-
 utilities/gm.1                         |  2959 ++++++++++++++++---------------
 www/Changelog.html                     |     9 +
 www/GraphicsMagick.html                |     4 +-
 www/convert.html                       |     2 +-
 www/gm.html                            |    12 +-
 www/mogrify.html                       |     2 +-
 www/version.html                       |     4 +-
 17 files changed, 1618 insertions(+), 1488 deletions(-)

diffs (truncated from 8335 to 500 lines):

diff -r 764d46677eca -r 5ad72c2bb8ff ChangeLog
--- a/ChangeLog	Fri Dec 31 11:08:22 2021 -0600
+++ b/ChangeLog	Fri Dec 31 15:20:41 2021 -0600
@@ -1,10 +1,14 @@
 2021-12-31  Bob Friesenhahn  <[email protected]>
 
+        * doc/{gmdoc2html, gmdocselect, imdoc2man, imdocselect}: Fixes to
+        work better with both GNU sed and Solaris/Illumos sed.
+
         * doc/GNUmakefile: Use GNU make rules to produce the full imdoc
         list for man, html, and tex, rather than relying on a shell
         wildcard expression, since the order produced by the shell
         wildcard expression is indeterminate.
 
+
 2021-12-30  Bob Friesenhahn  <[email protected]>
 
         * www/index.rst: Document that
diff -r 764d46677eca -r 5ad72c2bb8ff VisualMagick/installer/inc/version.isx
--- a/VisualMagick/installer/inc/version.isx	Fri Dec 31 11:08:22 2021 -0600
+++ b/VisualMagick/installer/inc/version.isx	Fri Dec 31 15:20:41 2021 -0600
@@ -10,5 +10,5 @@
 
 #define public MagickPackageName "GraphicsMagick"
 #define public MagickPackageVersion "1.4"
-#define public MagickPackageVersionAddendum ".020211230"
-#define public MagickPackageReleaseDate "snapshot-20211230"
+#define public MagickPackageVersionAddendum ".020211231"
+#define public MagickPackageReleaseDate "snapshot-20211231"
diff -r 764d46677eca -r 5ad72c2bb8ff doc/GNUmakefile
--- a/doc/GNUmakefile	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/GNUmakefile	Fri Dec 31 15:20:41 2021 -0600
@@ -42,7 +42,7 @@
 DOCINCLUDE        = ./imdocinclude
 
 # You might need to change this to /usr/bin/sed
-SED = /bin/sed
+SED ?= /bin/sed
 export SED
 
 HTML_TARGETS = \
@@ -82,19 +82,16 @@
 	if test -d expanded; then rmdir expanded; fi
 
 gm.1: targets-man $(GMSUBDIR)/man.imdoc $(DOC2MAN)
-	-rm -f $@ [email protected]
-	$(DOC2MAN) gm $(GMSUBDIR)/man.imdoc > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOC2MAN) gm $(GMSUBDIR)/man.imdoc > [email protected] && mv [email protected] $@
 
 gm.html: targets-html $(GMSUBDIR)/html.imdoc $(DOC2HTML)
-	-rm -f $@ [email protected]
-	$(DOC2HTML) gm $(GMSUBDIR)/man.imdoc > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOC2HTML) gm $(GMSUBDIR)/man.imdoc > [email protected] && mv [email protected] $@
 
 gm.tex: targets-tex $(GMSUBDIR)/tex.imdoc $(DOC2TEX)
-	-rm -f $@ [email protected]
-	$(DOC2TEX) < $(GMSUBDIR)/man.imdoc > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOC2TEX) < $(GMSUBDIR)/man.imdoc > [email protected] && mv [email protected] $@
 
 brief_options.imdoc:	options.imdoc
 	$(DOCSELECTBRIEF) options.imdoc brief_options.imdoc
@@ -109,19 +106,16 @@
 	mkdir -p $(GMSUBDIR)
 
 $(GMSUBDIR)/man.imdoc: targets-man $(GMSUBDIR)
-	-rm -f $@ [email protected]
-	cat $(addsuffix /man.imdoc, $(UTILSUBWILDCARD)) > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	cat $(addsuffix /man.imdoc, $(UTILSUBWILDCARD)) > [email protected] && mv [email protected] $@
 
 $(GMSUBDIR)/html.imdoc: targets-html $(GMSUBDIR)
-	-rm -f $@ [email protected]
-	cat $(addsuffix /html.imdoc, $(UTILSUBWILDCARD)) > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	cat $(addsuffix /html.imdoc, $(UTILSUBWILDCARD)) > [email protected] && mv [email protected] $@
 
 $(GMSUBDIR)/tex.imdoc: targets-tex $(GMSUBDIR)
-	-rm -f $@ [email protected]
-	cat $(addsuffix /tex.imdoc, $(UTILSUBWILDCARD)) > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	cat $(addsuffix /tex.imdoc, $(UTILSUBWILDCARD)) > [email protected] && mv [email protected] $@
 
 #
 # Invoke per-utility targets
@@ -179,24 +173,20 @@
 
 $(UTILSUBDIR)/Expanded.imdoc: $(UTILITY).imdoc brief_options.imdoc config_files.imdoc copyright.imdoc environment.imdoc $(DOCINCLUDE)
 	@if test ! -d $(UTILSUBDIR); then mkdir -p $(UTILSUBDIR); fi
-	-rm -f $@ [email protected]
-	$(DOCINCLUDE) $< > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOCINCLUDE) $< > [email protected] && mv [email protected] $@
 
 $(UTILSUBDIR)/man.imdoc: $(UTILSUBDIR)/Expanded.imdoc $(DOCSELECTCOMBINED)
-	-rm -f $@ [email protected]
-	$(DOCSELECTCOMBINED) $(UTILITY) man $< > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOCSELECTCOMBINED) $(UTILITY) man $< > [email protected] && mv [email protected] $@
 
 $(UTILSUBDIR)/html.imdoc: $(UTILSUBDIR)/Expanded.imdoc $(DOCSELECTSEPARATE)
-	-rm -f $@ [email protected]
-	$(DOCSELECTSEPARATE) $(UTILITY) html $< > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOCSELECTSEPARATE) $(UTILITY) html $< > [email protected] && mv [email protected] $@
 
 $(UTILSUBDIR)/tex.imdoc: $(UTILSUBDIR)/Expanded.imdoc $(DOCSELECTCOMBINED)
-	-rm -f $@ [email protected]
-	$(DOCSELECTCOMBINED) $(UTILITY) tex $< > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOCSELECTCOMBINED) $(UTILITY) tex $< > [email protected] && mv [email protected] $@
 
 #$(UTILBASE).1:  $(UTILSUBDIR)/man.imdoc $(DOC2MAN)
 #	-rm -f $@ [email protected]
@@ -204,14 +194,12 @@
 #	mv [email protected] $@
 
 $(UTILBASE).html:  $(UTILSUBDIR)/html.imdoc $(DOC2HTML)
-	-rm -f $@ [email protected]
-	$(DOC2HTML) $(UTILITY) $< > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOC2HTML) $(UTILITY) $< > [email protected] && mv [email protected] $@
 
 $(UTILBASE).tex:  $(UTILSUBDIR)/tex.imdoc $(DOC2TEX)
-	-rm -f $@ [email protected]
-	$(DOC2TEX) < $< > [email protected] && \
-	mv [email protected] $@
+	@-rm -f $@ [email protected]
+	$(DOC2TEX) < $< > [email protected] && mv [email protected] $@
 
 $(INSTALLWWW)/$(UTILITY).html: $(UTILBASE).html
 	cp -p $< $@
diff -r 764d46677eca -r 5ad72c2bb8ff doc/gmdoc2html
--- a/doc/gmdoc2html	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/gmdoc2html	Fri Dec 31 15:20:41 2021 -0600
@@ -2,12 +2,7 @@
 
 # gmdoc2html utility utility.imdoc > utility.html
 
-# FIXME: There is an output difference between System V sed and GNU
-# sed in paragraph delimiters:
-# -
-# +\'
-#
-# Pre-formatted text is losing all blank lines.
+# FIXME: Pre-formatted text is losing all blank lines.
 
 # <!-- ---------------------------------------------------------------- -->
 # <!-- Options.xml: "options" subsection of convert, composite, et al.  -->
diff -r 764d46677eca -r 5ad72c2bb8ff doc/gmdocselect
--- a/doc/gmdocselect	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/gmdocselect	Fri Dec 31 15:20:41 2021 -0600
@@ -35,15 +35,13 @@
        s/.*/!DELETE!/
        n
        b skipim
- 
+
      : select
        d
        " $3 | \
               \
               \
 ${SED} "
-     : begin
-
        /<imdoc>/d
        /<\/imdoc>/d
        /!DELETE!/d
diff -r 764d46677eca -r 5ad72c2bb8ff doc/imdoc2man
--- a/doc/imdoc2man	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/imdoc2man	Fri Dec 31 15:20:41 2021 -0600
@@ -1,17 +1,13 @@
 #!/bin/sh
 
 # imdoc2man utility utility.imdoc > utility.1
-
-# FIXME: There is an output difference between System V sed and GNU
-# sed in paragraph delimiters:
-#
-# -<p>
-# +     <p>
+# See https://www.gnu.org/software/groff/manual/html_node/man.html#man
+# See https://www.oreilly.com/library/view/unix-text-processing/9780810462915/Chapter14.html
+# See https://cmd.inp.nsk.su/old/cmd2/manuals/unix/UNIX_Unleashed/ch08.htm
 
 echo ".TH $1 1 \"`date '+%Y/%m/%d'`\" \"GraphicsMagick\""
 
 ${SED}  "
-   : begin
      /<imdoc>/d
      /<\/imdoc>/d
      /<include file=/d
@@ -69,8 +65,9 @@
      /<utils/d
      /<\/utils>/d
      /<!--/d
-     s/<pre>//
-     s/<\/pre>//
+     s/<pre>/\\
+.nf/
+     s/<\/pre>/.fi/
      /<tab>/d
      /<\/tab>/d
 
@@ -100,7 +97,7 @@
      s/<\/s>/\\\\fP/g
      s/<tt>//g
      s/<\/tt>//g
-     s/^\\'/\\\\'/g
+     s/^'/\\\\'/g
 
      " $2
-
+#      s/^'/\\\\'/g
diff -r 764d46677eca -r 5ad72c2bb8ff doc/imdocselect
--- a/doc/imdocselect	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/imdocselect	Fri Dec 31 15:20:41 2021 -0600
@@ -23,8 +23,6 @@
               \
               \
 ${SED} "
-     : begin
-
        /<imdoc>/d
        /<\/imdoc>/d
        /<im>/d
diff -r 764d46677eca -r 5ad72c2bb8ff doc/options.imdoc
--- a/doc/options.imdoc	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/options.imdoc	Fri Dec 31 15:20:41 2021 -0600
@@ -130,7 +130,7 @@
 <!-- ------------ -asc-cdl ------------------------------------------- -->
 
 <utils apps=convert,mogrify>
-<dopt> -asc-cdl <spec></opt>
+<dopt>-asc-cdl <spec></opt>
 
 <abs>apply ASC CDL color transform</abs>
 
@@ -1931,7 +1931,7 @@
 
 <pp><pre>
      -draw 'text 100,100 "%m:%f %wx%h"'
-</pre></pp>
+</pp>
 
 <pp>
 annotates the image with <tt>MIFF:bird.miff 512x480</tt> for an image titled
diff -r 764d46677eca -r 5ad72c2bb8ff doc/version.imdoc
--- a/doc/version.imdoc	Fri Dec 31 11:08:22 2021 -0600
+++ b/doc/version.imdoc	Fri Dec 31 15:20:41 2021 -0600
@@ -55,7 +55,7 @@
 
 <p>To display the version information:</p>
 
-<pre>
+<pp><pre>
   GraphicsMagick 1.3.37 2021-12-12 Q16 http://www.GraphicsMagick.org/
   Copyright (C) 2002-2021 GraphicsMagick Group.
   Additional copyrights and licenses apply to this software.
@@ -102,7 +102,7 @@
     LDFLAGS  = ...
     LIBS     = ...
 
-</pre>
+</pre></pp>
 
 </sect>
 <back>
diff -r 764d46677eca -r 5ad72c2bb8ff magick/version.h
--- a/magick/version.h	Fri Dec 31 11:08:22 2021 -0600
+++ b/magick/version.h	Fri Dec 31 15:20:41 2021 -0600
@@ -38,8 +38,8 @@
 #define MagickLibVersion  0x262300
 #define MagickLibVersionText  "1.4"
 #define MagickLibVersionNumber 26,23,0
-#define MagickChangeDate   "20211230"
-#define MagickReleaseDate  "snapshot-20211230"
+#define MagickChangeDate   "20211231"
+#define MagickReleaseDate  "snapshot-20211231"
 
 /*
   The MagickLibInterfaceNewest and MagickLibInterfaceOldest defines
diff -r 764d46677eca -r 5ad72c2bb8ff utilities/gm.1
--- a/utilities/gm.1	Fri Dec 31 11:08:22 2021 -0600
+++ b/utilities/gm.1	Fri Dec 31 15:20:41 2021 -0600
@@ -1,68 +1,68 @@
-.TH gm 1 "2021/12/30" "GraphicsMagick"
+.TH gm 1 "2021/12/31" "GraphicsMagick"
 .TP
 .in 15
 .in 15
 .in 20
 .SH NAME
-\'
+
 gm - command-line utility to create, edit, compare, convert, or display images
-\'
+
 .SH SYNOPSIS
-\'
+
 \fBgm animate\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fIfile\fP \fB[ [\fP
 \fIoptions ...\fP \fB]\fP \fIfile ...\fP \fB]\fP
-\'
+
 \fBgm batch\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fB[\fP \fIscript\fP \fB]\fP
-\'
+
 \fBgm benchmark\fP \fB[\fP \fIoptions ...\fP \fB]\fP subcommand
-\'
+
 \fBgm compare\fP \fB[\fP \fIoptions\fP \fB... ]\fP \fIreference-image\fP
 \fB[\fP \fIoptions\fP \fB... ]\fP \fIcompare-image\fP
 \fB[\fP \fIoptions\fP \fB... ]\fP
-\'
+
 \fBgm composite\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fIchange-image base-image\fP
 \fB[\fP \fImask-image\fP \fB]\fP \fIoutput-image\fP
-\'
+
 \fBgm conjure\fP \fB[\fP \fIoptions\fP \fB]\fP \fIscript.msl\fP
 \fB[ [\fP \fIoptions\fP \fB]\fP \fIscript.msl\fP \fB]\fP
-\'
+
 \fBgm convert\fP \fB[ [\fP \fIoptions ...\fP \fB] [\fP \fIinput-file ...\fP
 \fB] [\fP \fIoptions ...\fP \fB] ]\fP \fIoutput-file\fP 
-\'
+
 \fBgm display\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fIfile ...\fP
 \fB[ [\fP\fIoptions ...\fP \fB]\fP\fIfile ...\fP \fB]\fP
-\'
+
 \fBgm identify\fP \fIfile\fP \fB[\fP \fIfile ...\fP \fB]\fP
-\'
+
 \fBgm import\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fIfile\fP
-\'
+
 \fBgm mogrify\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fIfile ...\fP
-\'
+
 \fBgm montage\fP \fB[\fP \fIoptions ...\fP \fB]\fP \fIfile\fP \fB[ [\fP
 \fIoptions ...\fP \fB]\fP \fIfile ...\fP \fB]\fP \fIoutput-file\fP
-\'
+
 \fBgm time\fP subcommand
-\'
+
 \fBgm version\fP
 .SH DESCRIPTION
-\'
+
 GraphicsMagick's \fBgm\fP provides a suite of utilities for creating,
 comparing, converting, editing, and displaying images.  All of the
 utilities are provided as sub-commands of a single \fBgm\fP
 executable.  The \fBgm\fP executable returns the exit code 0 to
 indicate success, or 1 to indicate failure:
-\'
+
 \fBanimate\fP
 displays an animation (e.g. a GIF file) on any workstation display
 running an \fIX\fP server.
-\'
+
 \fBbatch\fP
 executes an arbitary number of the utility commands
 (e.g. \fBconvert\fP) in the form of a simple linear batch script in
 order to improve execution efficiency, and/or to allow use as a
 subordinate co-process under the control of an arbitrary script or
 program.
-\'
+
 \fBbenchmark\fP
 executes one of the other utility commands (e.g. \fBconvert\fP) for a
 specified number of iterations, or execution time, and reports
@@ -70,63 +70,63 @@
 utilization. \fBBenchmark\fP provides various operating modes
 including executing the command with a varying number of threads, and
 alternate reporting formats such as comma-separated value (CSV).
-\'
+
 \fBcompare\fP
 compares two images and reports difference statistics according to
 specified metrics and/or outputs an image with a visual representation
 of the differences.  It may also be used to test if images are similar
 within a particular range and specified metric, returning a truth
 value to the executing environment.
-\'
+
 \fBcomposite\fP
 composites images (blends or merges images together) to create new images.
-\'
+
 \fBconjure\fP
 interprets and executes scripts in
 the Magick Scripting Language (MSL).
-\'
+
 \fBconvert\fP
 converts an input file using one image format to an output file with
 the same or differing image format while applying an arbitrary number
 of image transformations.
-\'
+
 \fBdisplay\fP
 is a machine architecture independent image processing and display
 facility. It can display an image on any workstation display running
 an \fIX\fP server.
-\'
+
 \fBidentify\fP
 describes the format and characteristics of one or more image
 files. It will also report if an image is incomplete or corrupt.
-\'
+
 \fBimport\fP
 reads an image from any visible window on an \fIX\fP server and
 outputs it as an image file. You can capture a single window, the
 entire screen, or any rectangular portion of the screen.
-\'
+
 \fBmogrify\fP
 transforms an image or a sequence of images. These transforms include
 \fBimage scaling\fP, \fBimage rotation\fP, \fBcolor reduction\fP,
 and others. The transmogrified image \fBoverwrites\fP the original
 image.
-\'
+
 \fBmontage\fP
 creates a composite by combining several separate images. The images
 are tiled on the composite image with the name of the image optionally
 appearing just below the individual tile.
-\'
+
 \fBtime\fP
 executes a subcommand and reports the user, system, and total
 execution time consumed.
-\'
+
 \fBversion\fP
 reports the GraphicsMagick release version, maximum sample-depth,
 copyright notice, supported features, and the options used while
 building the software.
-\'
+
 The \fBGraphicsMagick\fP utilities recognize the following image formats:
-\'
-\'
+
+
 \fBName\fP  \fBMode\fP \fBDescription\fP
  o  3FR       r-- Hasselblad Photo RAW
  o  8BIM      rw- Photoshop resource format
@@ -324,21 +324,21 @@
               r   Read
               w   Write
               +   Multi-image
-\'
-\'
+
+
 \fISupport for some of these formats require additional programs or libraries.
 See README
 in the source package for where to find optional additional software\fP.
-\'
+
 Note, a format delineated with + means that if more than one
 image is specified, frames are combined into a single multi-image
 file. Use \fB+adjoin\fP if you want a single image produced for each
 frame.
-\'
+
 Your installation might not support all of the formats in the list.
 To get an accurate listing of the formats supported by your particular
 configuration, run "gm convert -list format".
-\'
+
 Raw images are expected to have one byte per pixel unless \fBgm\fP is
 compiled in 16-bit quantum mode or in 32-bit quantum mode. Here, the
 raw data is expected to be stored two or four bytes per pixel,
@@ -347,7 +347,7 @@
 version" without any options, and looking for "Q:16" in the first line
 of output.
 .SH FILES AND FORMATS
-\'
+