Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 731 insertions, 0 deletions

diff --git a/src/devices/grohtml/grohtml.1.man b/src/devices/grohtml/grohtml.1.man
new file mode 100644
index 0000000..2243b47
--- /dev/null
+++ b/src/devices/grohtml/grohtml.1.man
@@ -0,0 +1,731 @@
+.TH grohtml @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+grohtml, post\-grohtml, pre\-grohtml \-
+.I groff
+output driver for HTML
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1999-2022 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_grohtml_1_man_C \n[.cp]
+.cp 0
+.
+.\" Define fallback for groff 1.23's MR macro if the system lacks it.
+.nr do-fallback 0
+.if !\n(.f           .nr do-fallback 1 \" mandoc
+.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
+.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
+.if \n[do-fallback]  \{\
+.  de MR
+.    ie \\n(.$=1 \
+.      I \%\\$1
+.    el \
+.      IR \%\\$1 (\\$2)\\$3
+.  .
+.\}
+.rr do-fallback
+.
+.
+.\" ====================================================================
+.SH Synopsis
+.\" ====================================================================
+.
+.SY pre\-grohtml
+.RB [ \-epV ]
+.RB [ \-a
+.IR anti-aliasing-text-bits ]
+.RB [ \-D
+.IR image-directory ]
+.RB [ \-F
+.IR font-directory ]
+.RB [ \-g
+.IR anti-aliasing-graphic-bits ]
+.RB [ \-i
+.IR resolution ]
+.RB [ \-I
+.IR image-stem ]
+.RB [ \-o
+.IR image-vertical-offset ]
+.RB [ \-x
+.IR  html-dialect ]
+.I troff-command
+.I troff-argument
+\&.\|.\|.
+.YS
+.
+.
+.SY pre\-grohtml
+.B \-\-help
+.YS
+.
+.
+.SY pre\-grohtml
+.B \-v
+.
+.SY pre\-grohtml
+.B \-\-version
+.YS
+.
+.
+.SY post\-grohtml
+.RB [ \-bCGhlnrVy ]
+.RB [ \-F
+.IR font-directory ]
+.RB [ \-j
+.IR output-stem ]
+.RB [ \-s
+.IR base-point-size ]
+.RB [ \-S
+.IR heading-level ]
+.RB [ \-x
+.IR html-dialect ]
+.RI [ file\~ .\|.\|.]
+.YS
+.
+.
+.SY post\-grohtml
+.B \-\-help
+.YS
+.
+.
+.SY post\-grohtml
+.B \-v
+.
+.SY post\-grohtml
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+The GNU
+.I roff
+system's HTML support consists of a preprocessor,
+.IR \%pre\-grohtml ,
+and an output driver,
+.IR \%post\-grohtml ;
+together,
+they translate
+.MR roff @MAN7EXT@
+documents to HTML.
+.
+Because a preprocessor is (uniquely) required for this output driver,
+users should invoke
+.I \%grohtml
+via the
+.MR groff @MAN1EXT@
+command with the
+.B \-Thtml
+or
+.B \-Txhtml
+options.
+.
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR \%grohtml .
+.
+If no operands are given,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+.I \%grohtml
+reads the standard input stream.
+.
+Output is written to the standard output stream.
+.
+.
+.P
+.I \%grohtml
+invokes
+.I groff
+twice.
+.
+In the first pass,
+the preprocessor
+.I \%pre\-grohtml
+renders
+pictures,
+equations,
+and tables as images in PostScript format using the
+.B ps
+output device.
+.
+In the second pass,
+the output driver
+.I \%post\-grohtml
+translates the output of
+.MR @g@troff @MAN1EXT@
+to HTML.
+.
+.
+.P
+.I \%grohtml
+writes output encoded in \%UTF-8 and has built-in HTML entities for all
+non-composite Unicode characters.
+.
+In spite of this,
+.I groff
+may issue warnings about unknown special characters if they can't be
+found during the first pass.
+.
+Such warnings can be safely ignored unless the special characters
+appear inside a table or equation.
+.
+.
+.\" ====================================================================
+.SS Typefaces
+.\" ====================================================================
+.
+.I \%grohtml
+supports the standard four styles:
+.B R
+(roman),
+.B I
+.RI ( italic ),
+.B B
+.RB ( bold ),
+and
+.B BI
+(\f[BI]bold-italic\f[]).
+.
+Fonts are grouped into families
+.B T
+and
+.B C
+having members in each style.
+.
+.
+.RS
+.TP
+.B TR
+Times roman
+.
+.TQ
+.B TI
+Times italic
+.
+.TQ
+.B TB
+Times bold
+.
+.TQ
+.B TBI
+Times bold-italic
+.
+.TQ
+.B CR
+Courier roman
+.
+.TQ
+.B CI
+Courier italic
+.
+.TQ
+.B CB
+Courier bold
+.
+.TQ
+.B CBI
+Courier bold-italic
+.RE
+.
+.
+.P
+A special font,
+.BR S ,
+is also provided to accommodate
+.I roff
+documents that expect it to always be available.
+.
+.
+.\" ====================================================================
+.SS "Font description files"
+.\" ====================================================================
+.
+The font description files used with
+.I \%grohtml
+expose the same glyph repertoire in their
+.B charset
+sections.
+.
+See
+.MR groff_font @MAN5EXT@ .
+.
+.
+.\" ====================================================================
+.SS Dependencies
+.\" ====================================================================
+.
+.I \%pre\-grohtml
+generates an image whenever an
+.I @g@eqn
+equation,
+.I @g@tbl
+table,
+or
+.I @g@pic
+picture is encountered in the input.
+.
+.I \%grohtml
+therefore may run several commands as part of its operation.
+.
+These include the \%Netpbm tools
+.IR \%pnmcrop ,
+.IR \%pnmcut ,
+and
+.IR \%pnmtopng ;
+\%Ghostscript
+.RI ( gs );
+and the \%PSUtils tool
+.IR \%psselect .
+.
+.
+.\" ====================================================================
+.SH Options
+.\" ====================================================================
+.
+.B \-\-help
+displays a usage message,
+while
+.B \-v
+and
+.B \-\-version
+show version information;
+all exit afterward.
+.
+.
+.TP
+.BI \-a \~anti-aliasing-text-bits
+Number of bits of antialiasing information to be used by text when
+generating PNG images.
+.
+The default
+.RB is\~ 4
+but
+.BR 0 ,
+.BR 1 ,
+and
+.B 2
+are also valid.
+.
+Your system's version of
+.I gs
+must support the
+.B \%\-dTextAlphaBits
+option in order to exploit antialiasing.
+.\" XXX: How antiquated are the ones that don't?  Get rid of this?
+.
+A value
+.RB of\~ 0
+stops
+.I \%grohtml
+from issuing antialiasing commands to
+.IR gs .
+.
+.
+.TP
+.B \-b
+Initialize the background color to white.
+.
+.
+.TP
+.B \-C
+Suppress output of \[lq]CreationDate:\[rq] HTML comment.
+.
+.
+.TP
+.BI \-D \~image-directory
+Instruct
+.I \%grohtml
+to place all image files into directory
+.IR image-directory .
+.
+.
+.TP
+.B \-e
+Direct
+.I @g@eqn
+to produce MathML.
+.
+.
+.IP
+This option should not be manually specified;
+it is synthesized by
+.I groff
+depending on whether it was given the
+.B \-Thtml
+or
+.B \-Txhtml
+option.
+.
+.
+.TP
+.BI \-F \~font-directory
+Prepend directory
+.RI font-directory /dev name
+to the search path for font and device description files;
+.I name
+is the name of the device,
+usually
+.BR html .
+.
+.
+.TP
+.BI \-g \~anti-aliasing-graphic-bits
+Number of bits of antialiasing information to be used by graphics when
+generating PNG images.
+.
+The default
+.RB is\~ 4
+but
+.BR 0 ,
+.BR 1 ,
+and
+.B 2
+are also valid.
+.
+Your system's version of
+.I gs
+must support the
+.B \%\-dGraphicAlphaBits
+option in order to exploit antialiasing.
+.\" XXX: How antiquated are the ones that don't?  Get rid of this?
+.
+A value
+.RB of\~ 0
+stops
+.I \%grohtml
+from issuing antialiasing commands to
+.IR gs .
+.
+.
+.TP
+.B \-G
+Suppress output of \[lq]Creator:\[rq] HTML comment.
+.
+.
+.TP
+.B \-h
+Generate section headings by using HTML
+.B B
+elements and increasing the font size,
+rather than HTML
+.B H
+elements.
+.
+.
+.TP
+.BI \-i \~resolution
+Set the image resolution in pixels per inch;
+the default
+.RB is\~ 100 .
+.
+.
+.TP
+.BI \-I \~image-stem
+Determine the image file name stem.
+.
+If omitted,
+.I \%grohtml
+uses
+.IR \%grohtml\- XXXXX
+(where
+.I XXXXX
+is the process ID).
+.
+A dash is appended to the stem to separate it from the following image
+number.
+.
+.
+.TP
+.BI \-j \~output-stem
+Instruct
+.I \%grohtml
+to split the HTML output into multiple files.
+.
+Output is written to a new file at each section heading
+(but see option
+.B \-S
+below)
+named
+.IR output-stem\- n .html .
+.
+.
+.TP
+.B \-l
+Turn off the production of automatic section links at the top of the
+document.
+.
+.
+.TP
+.B \-n
+Generate simple heading anchors whenever a section/number heading is
+found.
+.
+Without the option the anchor value is the textual heading.
+.
+This can cause problems when a heading contains a \[lq]?\[rq] on older
+versions of some browsers.
+.
+This feature is automatically enabled if a heading contains an image.
+.
+.
+.TP
+.BI \-o \~image-vertical-offset
+Specify the vertical offset of images in points.
+.
+.
+.TP
+.B \-p
+Display page rendering progress to the standard error stream.
+.
+.I \%grohtml
+displays a page number only when an image is required.
+.
+.
+.TP
+.B \-r
+Turn off the automatic header and footer line
+(HTML rule).
+.
+.
+.TP
+.BI \-s \~base-type-size
+Set the document's base type size in points.
+.
+When this size is used in the source,
+it corresponds to the HTML base type size.
+.
+Every increase of two points in the source will produce a
+.RB \[lq] big \[rq]
+element,
+and conversely when a decrease of two points is seen,
+a
+.RB \[lq] small \[rq]
+element is emitted.
+.
+.
+.TP
+.BI \-S \~heading-level
+When splitting HTML output
+(see option
+.B \-j
+above),
+split at each nested heading level defined by
+.IR heading-level ,
+or higher).
+.
+The default is
+.BR 1 .
+.
+.
+.TP
+.B \-V
+Create an XHTML or HTML validator button at the bottom of each page of
+the document.
+.
+.
+.TP
+.BI \-x \~html-dialect
+Select HTML dialect.
+.
+Currently,
+.I html-dialect
+should be either the
+.RB digit\~ 4
+or the
+.RB letter\~ x ,
+which indicates whether
+.I \%grohtml
+should generate HTML\~4 or XHTML,
+respectively.
+.
+.
+.IP
+This option should not be manually specified;
+it is synthesized by
+.I groff
+depending on whether it was given the
+.B \-Thtml
+or
+.B \-Txhtml
+option.
+.
+.
+.TP
+.B \-y
+Produce a right-aligned
+.I groff
+signature at the end of the document
+(only if
+.B \-V
+is also specified).
+.
+.
+.\" ====================================================================
+.SH Environment
+.\" ====================================================================
+.
+.TP
+.I GROFF_FONT_PATH
+lists directories in which to search for
+.IR devhtml ,
+.IR grohtml 's
+directory of device and font description files.
+.
+See
+.MR @g@troff @MAN1EXT@
+and
+.MR groff_font @MAN5EXT@ .
+.
+.
+.TP
+.I SOURCE_DATE_EPOCH
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the output creation timestamp in place of the current time.
+.
+The time is converted to human-readable form using
+.MR ctime 3
+and recorded in an HTML comment.
+.
+.
+.TP
+.I TZ
+The time zone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.MR tzset 3 .
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I @FONTDIR@/\:\%devhtml/\:DESC
+describes the
+.B html
+output device.
+.
+.
+.TP
+.IR @FONTDIR@/\:\%devhtml/ F
+describes the font known
+.RI as\~ F
+on device
+.BR html .
+.
+.
+.TP
+.I @MACRODIR@/\:html\:.tmac
+defines font mappings,
+special characters,
+and colors for use with the
+.B html
+output device.
+.
+It is automatically loaded by
+.I \%troffrc
+when either of the
+.B html
+or
+.B xhtml
+output devices is selected.
+.
+.
+.TP
+.I @MACRODIR@/\:html\-end\:.tmac
+finalizes setup of the
+.B html
+output device.
+.
+It is automatically loaded by
+.I \%troffrc\-end
+when either of the
+.B html
+or
+.B xhtml
+output devices is selected.
+.
+.
+.P
+.I \%grohtml
+uses temporary files.
+.
+See
+.MR groff @MAN1EXT@
+for details about where such files are created.
+.
+.
+.\" ====================================================================
+.SH Bugs
+.\" ====================================================================
+.
+.I \%grohtml
+is still beta code.
+.
+.
+.PP
+.I \%grohtml
+does not truly support hyphenation,
+but you can fool it into hyphenating long input lines,
+which can appear in HTML output with a hyphenated word followed by a
+space but no line break.
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.\" IR afmtodit (@MAN1EXT@),
+.MR groff @MAN1EXT@ ,
+.MR @g@troff @MAN1EXT@ ,
+.\" IR psbb (1), \" XXX: what is this?
+.\" IR groff_out (@MAN5EXT@),
+.\" IR groff_char (@MAN7EXT@),
+.MR groff_font @MAN5EXT@
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_grohtml_1_man_C]
+.do rr *groff_grohtml_1_man_C
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72: