diff options
| author | G. Branden Robinson <g.branden.robinson@gmail.com> | 2023-09-10 13:14:36 -0500 |
|---|---|---|
| committer | G. Branden Robinson <g.branden.robinson@gmail.com> | 2023-09-10 13:51:00 -0500 |
| commit | c32841039bd62b05d72e614a81b9a4c06266b14d (patch) | |
| tree | 2ba75470fdd89b6cd391e81c9c3ab57b71963f2b | |
| parent | 147237b1dd76f73d6c4e18c18960b8257523c3ce (diff) | |
groff_www(7): Revise.
Content:
* Drop stale advice; this page no longer uses these macros itself (and
has not since groff 1.22.4 or earlier) because that reduces its
portability as a man page. "doc/webpage.ms" is a better exemplar.
* Characterize grohtml(1) as being in "beta", not "alpha" state. (In my
opinion, if we can't defend a claim of beta quality after 20+ years,
we should withdraw it.)
* Fix numerous errors in macro syoposes, such as arguments being out of
order in `IMG`.
* Drop displayed examples. They illustrated only the obvious.
* Drop documentation of `FTP` macro, which seems entirely pointless.
(It is aliased to `URL` in the implementation.)
Style:
* Respell "-Txxx" formatter options as "-T xxx".
* Spell macro names without leading dot in summary table and synopses.
A user of this macro package is expected to know basic call syntax.
* Properly use roman and italic styles in synopses instead of bold for
everything.
* Tune indentation amount used for tagged paragraph sequence.
* Recast for clarity.
* Tighten.
Markup:
* Use two empty requests where vertical space is expected.
* Annotate some problems and unclear points.
In reviewing this document, I find myself questioning the design of this
package and a fair amount of its chosen mission. I think we would do
better to integrate specific features (like hyperlinks) into each
package rather than heaping a hodgepodge of HTML features on top of,
theoretically, any macro package that manages page location traps. This
auxiliary package is over 20 years old and that mission does not appear
to have been taken up. It seems to have been written with ms(7) in mind
with little thought given to any other "full-service" package. (Some
effort was made at promoting it as an extension to man(7), but that idea
seems to have been abandoned about 15 years ago, for which we can be
grateful.)
The inconsistency between the argument lists of `IMG` and `PIMG` is
shockingly bad, and a good example of excessive conservatism (or
inertia) in interface design.
The macros are documented in an ad hoc order with no explicit grouping.
The list-related macros (ULS...LI) lack synopses altogether, a strange
defect in a document that not only explained but provided code displays
for blindingly obvious example applications.
The pseudo-Unix-command-line syntax of *roff macro calls with "option"
arguments beginning with `-` is a terrible practice. *roff is not the
Unix shell. There are no file descriptors, no redirection, and no
piping. Research suggests that blame for this analogical aping can be
laid at mm(7)'s doorstep.
A macro interface with a sequence of some optional arguments followed by
some mandatory ones followed by more optional ones is repugnant because
it is difficult to learn. It also makes argument processing within
macro definitions more tedious and therefore more prone to error,
because the programmer gets fatigued and overlooks meat and potatoes
issues like syntactical and semantic validation. Lack of validation
then frustrates the user, because they get diagnostic messages they
don't understand, or, worse, incorrect output with no diagnosis of error
at all. All mandatory arguments should come first. That anyone thinks
they shouldn't, or that it helps anyone to have them do so, is another
Unix command-line hangover. And these days, a geriatric one at that.
Decades ago we learned that such a practice makes it harder to compose
Unix command lines (by stuffing arguments into shell variables, for
example), which is one reason the '--' "end of options" convention
arose, as with with GNU getopt()'s automatic resequencing of argv[].
| -rw-r--r-- | tmac/groff_www.7.man | 813 |
1 files changed, 340 insertions, 473 deletions
diff --git a/tmac/groff_www.7.man b/tmac/groff_www.7.man index ba89811..f176a5a 100644 --- a/tmac/groff_www.7.man +++ b/tmac/groff_www.7.man @@ -75,64 +75,56 @@ file when the formatter (usually .MR groff @MAN1EXT@ ) is called with either of the options -.B \-Thtml +.RB \[lq] \-T\~html \[rq] or -.BR \-Txhtml . -. -To see hyperlinks in action, -format this man page using one of those options. -. +.RB \[lq] \-T\~xhtml \[rq]. . -.P -This document is a basic guide; -the HTML output driver -.RI ( \%grohtml ) -remains in an alpha state. -. -It has been included with the distribution to encourage testing. -. -. -.P -Here is a summary of the functions found in this macro set. +The HTML output driver +.MR grohtml 1 +is in a beta state; +.I groff +distributes these macros to encourage its testing. . . .P .TS tab(@); -l l. -\&.JOBNAME@split output into multiple files -\&.HX@automatic heading level cut off -\&.BCL@specify colours on a web page -\&.BGIMG@specify background image -\&.URL@create a URL using two parameters -\&.FTP@create an FTP reference -\&.MTO@create an HTML email address -\&.TAG@generate an HTML name -\&.IMG@include an image file -\&.PIMG@include PNG image -\&.MPIMG@place PNG on the margin and wrap text around it -\&.HnS@begin heading -\&.HnE@end heading -\&.LK@emit automatically collected links. -\&.HR@produce a horizontal rule -\&.NHR@suppress automatic generation of rules. -\&.HTL@only generate HTML title -\&.HEAD@add data to <head> block -\&.ULS@unorder list begin -\&.ULE@unorder list end -\&.OLS@ordered list begin -\&.OLE@ordered list end -\&.DLS@definition list begin -\&.DLE@definition list end -\&.LI@insert a list item -\&.DC@generate a drop capital -\&.HTML@pass an HTML raw request to the device driver -\&.CDS@code example begin -\&.CDE@code example end -\&.ALN@place links on left of main text. -\&.LNS@start a new two-column table with links in the left. -\&.LNE@end the two-column table. -\&.LINKSTYLE@initialize default URL attributes. +L L +Lb L. +Macro@Meaning +_ +JOBNAME@split output into multiple files +HX@automatic heading level cut-off +BCL@specify colours on a web page +BGIMG@specify background image +URL@create a URL using two parameters +MTO@create an HTML email address +TAG@generate an HTML name +IMG@include an image file +PIMG@include PNG image +MPIMG@place PNG on the margin and wrap text around it +HnS@begin heading +HnE@end heading +LK@emit automatically collected links +HR@produce a horizontal rule +NHR@suppress automatic generation of rules +HTL@record document title as HTML metadata only +HEAD@add data to <head> block +ULS@unordered list begin +ULE@unordered list end +OLS@ordered list begin +OLE@ordered list end +DLS@definition list begin +DLE@definition list end +LI@insert a list item +DC@generate a drop capital +HTML@transmit raw HTML to output driver +CDS@code example begin +CDE@code example end +ALN@place links on left of main text +LNS@start two-column table with links on the left +LNE@end two-column table started with \fB.LNS\fP +LINKSTYLE@initialize default URL attributes .TE . . @@ -140,541 +132,388 @@ l l. .SH Macros .\" ==================================================================== . -.TP -.B .JOBNAME filename +.TP 9n \" "HTML" + 2n + hand-tuned for PDF +.BI JOBNAME\~ file-name-stem Split output into multiple HTML files. . -A file is split whenever a \&.SH or \&.NH\ 1 is encountered. +In +.I ms +documents, +a file is split whenever an +.B .SH +or +.RB \[lq] ".NH\~1" \[rq] +call is encountered. . -Its argument is the file stem name for future output files. +Its argument is the file name stem used for output files. . This option is equivalent to .IR \%grohtml 's .B \-j option. . +. .TP -.B .HX n -Specify the cut off depth when generating links from section headings. +.BI HX\~ n +Set section heading level above which +.I \%grohtml +is not to automatically generate links to +.I n. . -For example, a parameter of\~2 would cause +For example, +when used with the +.MR groff_ms @MAN7EXT@ +package, +.RB \[lq] ".HX\~2" \[rq] +causes .I \%grohtml to generate a list of links for -.B .NH\ 1 +.I ms +macro calls +.RB \[lq] ".NH\~1" \[rq] and -.B .NH\ 2 +.RB \[lq] ".NH\~2" \[rq] but not for -.BR .NH\ 3 . -. -Whereas -. -. -.RS -.IP -.EX -\&.HX 0 -.EE -.RE -. -. -.IP -tells -.I \%grohtml -that no heading links should be created at all. +.RB \[lq] ".NH\~3" \[rq], +whereas +.RB \[lq] ".HX\~0" \[rq] +generates no hyperlinks to section headings. . -Another method for turning automatic headings off is by issuing the -command-line switch -.B \-P\-l -to -.IR groff . +Giving +.I groff +the option +.RB \[lq] "\-P\~\-l" \[rq] +disables automatic heading linkage. . . .TP -.BI .BCL\~ "foreground background active not-visited visited" -This macro takes five parameters: -foreground, -background, +.BI BCL\~ "foreground background active not-visited visited" +Configure colours used for +page foreground, +page background, active hypertext link, -hypertext link not yet visited, -and visited hypertext link colour. +hypertext links not yet visited, +and visited hypertext links. +. . .TP -.B .BGIMG imagefile -the only parameter to this macro is the background image file. +.BI BGIMG\~ file +Set the background image +to +.I file. +. . .TP -.B .URL url [description] [after] -generates a URL using either one, -two, -or three arguments. +.BI URL\~ url\~\c +.RI [ link-text \~[ post ]] +Generate a hyperlink to +.I url +with optional +.I link-text +followed immediately by non-linked text +.I post. . -The first parameter is the actual URL, the second is the name of the -link, and the third is optional stuff to be printed immediately -afterwards. . +.IP If -.B description -and -.B after -are absent then the -.B URL -becomes the anchor text. +.I link-text +is absent, +.I url +is formatted as the link text. . -Hyphenation is disabled while printing the actual URL; -explicit breakpoints should be inserted with the +Hyphenation is disabled while formatting a URL; +insert explicit break points with the .B \[rs]: escape sequence. . -Here is how to encode -.UR http://\:foo\:.org/ -foo -.UE : -.RS -.IP -.B .URL http://\[rs]:foo\[rs]:.org/ "foo" : -.RE -. -.IP -If this is processed by a device other than -.B \-Thtml -or -.B \-Txhtml -it appears as: -.RS -.IP -foo \[la]\f[CR]http://\:foo\:.org\f[]\[ra]: -.RE -. -.IP -The URL macro can be of any type; -for example, we can reference -.UR pic\:.html -Eric Raymond's -.I pic -guide -.UE -by: -.RS -.IP -.B .URL pic\[rs]:.html \[dq]Eric Raymond\[aq]s pic guide\[dq] -.RE . .TP -.B .MTO address [description] [after] -Generate an email HTML reference. +.BI MTO\~ address\~\c +.RI [ link-text \~[ post ]] +Generate an email hyperlink to +.I address +with optional +.I link-text +followed immediately by non-linked text +.I post. . -The first argument is mandatory as the email address. -. -The optional second argument is the text you see in your browser. -. -If an empty argument is given, -.B address -is used instead. -. -An optional third argument is stuff printed immediately afterwards. -. -Hyphenation is disabled while printing the actual email address. -. -For example, -.MT joe@\:user\:.org -Joe User -.ME -can be achieved by the following macro: -.RS -.IP -.B .MTO joe@user.org \[dq]Joe User\[dq] -.RE . .IP -All URLs currently are treated as consuming no textual -space in -.IR groff . -. -This could be considered as a bug since it causes some problems. -. -To circumvent this, -.B www.tmac -inserts a zero-width character which expands to a harmless space (only -if run with -.B \-Thtml -or -.BR \-Txhtml ). -. -.TP -.B .FTP url [description] [after] -indicates that data can be obtained via FTP. -. -The first argument is the URL and the second is the browser text. -. -A third argument, similar to the macros above, is intended for stuff -printed immediately afterwards. -. -The second and the third parameter are optional. -. -Hyphenation is disabled while printing the actual URL. +If +.I link-text +is absent, +.I address +is formatted as the link text. . -As an example, here is the location of the -.UR ftp://\:ftp\:.gnu\:.org/ -GNU FTP server -.UE . +Hyphenation is disabled while formatting a URL; +insert explicit break points with the +.B \[rs]: +escape sequence. . -The macro example above can be specified as: -.RS -.IP -.B .FTP ftp://\[rs]:ftp\[rs]:.gnu\[rs]:.org/ \[dq]GNU FTP server\[dq] . -.RE . .TP -.B .TAG name -Generates an HTML name tag from its argument. -. -This can then be referenced using the -.UR #URL -URL -.UE -macro. -. -As you can see, you must precede the tag name with -.B # -since it is a local reference. -. -This link was achieved via placing a TAG in the URL description above; -the source looks like this: -. -. -.RS -.IP -.EX -\&.TP -\&.B URL -generates -\&.TAG URL -a URL using either two or three arguments. -\&.\|.\|. -.EE -.RE +.BI TAG\~ name +Generate an anchor +.I name +marking its location in the document as a target for hyperlinks. . . .TP -.B .IMG [\-R|\-L|\-C] filename [width] [height] -Include a picture into the document. -. -The first argument is the horizontal location: right, left, or center -.RB ( \-R , -.BR \-L , +.BI IMG\~ file-name\~\c +.RB [ \-C | \-L | \-R ]\~\c +.RI [ width \~[ height ]] +Insert graphical image +.I file-name. +. +The optional second argument aligns the image to the center +.RB ( \-C ;\~default), +left +.RB ( \-L ), or -.BR \-C ). +right +.RB ( \-R ). . -Alignment is centered by default -.RB ( \-C ). +The optional +.I width +defaults to 100 units +(in the context of the HTML renderer) +and the optional +.I height +to the same measurement as +.I width . . -The second argument is the filename. -. -The optional third and fourth arguments are the width and height. -. -If the width is absent it defaults to 1\~inch. -. -If the height is absent it defaults to the width. -. -This maps onto an HTML img tag. -. -If you are including a PNG image then it is advisable to use the -.B PIMG -macro. . .TP -.B .PIMG [\-R|\-L|\-C] filename [width [height]] -Include an image in PNG format. -. -This macro takes exactly the same parameters as the -.B IMG -macro; it has the advantage of working with PostScript and HTML devices -also since it can automatically convert the image into the EPS format, -using the following programs of the -.B netpbm -package: -.BR pngtopnm , -.BR pnmcrop , +.BR PIMG\~ [ \-C | \-L | \-R ]\~\c +.IR file-name\~ [ width \~[ height ]] +Insert graphical image +.I file-name, +assumed to be in PNG format. +. +Compared to +.BR IMG , +this macro has the advantage of working with both PostScript and HTML +devices since it converts +.I file-name +into EPS format using +.MR pngtopnm 1 , +.MR pnmcrop 1 , and -.BR pnmtops . +.MR pnmtops 1 . . +.I height +and +.I width +may be given as percentages +(of the line length +.B \[rs]n[.l] +and page length +.BR \[rs]n[.p] , +respectively). +. +. +.IP If the document isn't processed with -.B \-Thtml +.RB \[lq] \-T\~html \[rq] or -.B \-Txhtml -it is necessary to use the +.RB \[lq] \-T\~xhtml \[rq], +you must use +.MR groff @MAN1EXT@ 's .B \-U -option of -.IR groff . -. -.TP -.B .MPIMG [\-R|\-L] [\-G gap] filename [width [height]] -Place a PNG image on the margin and wrap text around it. -. -The first parameters are optional. +option. +.\" XXX: stale? Does this predate the `psbb` request? . -The alignment: left or right -.RB ( \-L -or -.BR \-R ) -specifies the margin where the picture is placed at. . -The default alignment is left -.RB ( \-L ). +.TP +.BR MPIMG\~ [ \-L | \-R ]\~[ \-G\~\c +.IR gap ]\~\c +.IR file-name\~ [ width \~[ height ]] +As +.BR PIMG , +but place the image at a margin and wrap text around it. +. +The image is aligned the to the left +.RB ( \-L , +default) +or right +.RB ( \-R ) +margin. . -Optionally, .BI \-G \~gap -can be used to arrange a gap between the picture and the text that -wraps around it. -. -The default gap width is zero. -. -.br -The first non-optional argument is the filename. -. -The optional following arguments are the width and height. -. -If the width is absent it defaults to 1\~inch. -. -If the height is absent it defaults to the width. -. -Example: -. -. -.RS -.IP -.EX -\&.MPIMG \-L \-G 2c foo.png 3c 1.5c -.EE -.RE -. -. -.IP -The height and width may also be given as percentages. -. -The PostScript device calculates the width from the -.B .l -register and the height from the -.B .p -register. -. -For example: +imposes horizontal space of +.I gap +pixels between the picture and the text that wraps around it. . -. -.RS -.IP -.EX -\&.MPIMG \-L \-G 2c foo.png 15% -.EE -.RE +The default +.I gap +is zero. . . .TP -.BI .HnS\~ n -Begin heading. -. -The numeric heading level -.I n -is specified by the first parameter. -. -Use this macro if your headings contain URL, FTP or MTO macros. -. -Example: -. -. -.RS -.IP -.EX -\&.HnS 1 -\&.HR -GNU Troff -\&.URL https://\[rs]:www\[rs]:.gnu\[rs]:.org/\[rs]:software/\[rs]:groff/ -\&\[rs][em]a -\&.URL http://www\[rs]:.gnu\[rs]:.org/ GNU -\&project. -\&.HR -\&.HnE -.EE -.RE -. -. -.IP -In this case you might wish to disable automatic links to headings. -. -This can be done via -.B \-P\-l -from the command line. -.\" or by using a call to \[lq].HX 0\[rq]. +.BI HnS\~ n +Begin heading at level +.I n. . . .TP -.B .HnE -End heading. +.B HnE +End heading text. . . .TP -.B .LK -Force +.B LK +Direct .I \%grohtml -to place the automatically generated links at this position. +to emit the list of automatically generated hyperlinks at this location. . . .TP -.B .HR -Generate a full-width horizontal rule for -.B \-Thtml -and -.BR \-Txhtml . +.B HR +Generate a full-width horizontal rule when used with +.RB \[lq] \-T\~html \[rq] +or +.RB \[lq] \-T\~xhtml \[rq]. . -No effect for all other devices. . .TP -.B .NHR -Suppress generation of the top and bottom rules which +.B NHR +Suppress the horizontal rules at the document's top and bottom that .I \%grohtml emits by default. . +. .TP -.B .HTL +.B HTL Generate an HTML title only. . -This differs from the +This differs from +.MR groff_ms @MAN7EXT@ 's .B TL -macro of the -.B ms -macro package which generates both an HTML title and an <H1> heading. +macro, +which generates both an HTML title and an <H1> heading. . -Use it to provide an HTML title as search engine fodder but a graphic -title in the document. +Use it to provide an HTML title as document metadata but not as +formatted text. +. +The title ends when vertical space +.RB ( .sp ) +or a break +.RB ( .br ) +is seen. . -The macro terminates when a space or break is seen (.sp, \&.br). . .TP -.B .HEAD -Add arbitrary HTML data to the <head> block. +.B HEAD +Add arbitrary data to the HTML <head> element. . Ignored if not processed with -.B \-Thtml +.RB \[lq] \-T\~html \[rq] or -.BR \-Txhtml . -. -Example: -. -. -.RS -.IP -.EX -\&.HEAD \[dq]<link \[rs] - rel=\[dq]\[dq]icon\[dq]\[dq] \[rs] - type=\[dq]\[dq]image/png\[dq]\[dq] \[rs] - href=\[dq]\[dq]http://foo.org//bar.png\[dq]\[dq]/>\[dq] -.EE -.RE +.RB \[lq] \-T\~xhtml \[rq]. . . .TP -.B .HTML +.B HTML All text after this macro is treated as raw HTML. . -If the document is processed without -.B \-Thtml +Ignored if not processed with +.RB \[lq] \-T\~html \[rq] or -.B \-Txhtml -then the macro is ignored. -. -Internally, this macro is used as a building block for other -higher-level macros. -. -.IP -For example, the -.B BGIMG -macro is defined as -. -. -.RS -.IP -.EX -\&.de BGIMG -\&.\& HTML <body background=\[rs]\[rs]$1> -\&.. -.EE -.RE +.RB \[lq] \-T\~xhtml \[rq]. . . .TP -.B .DC l text [color] -Produce a drop capital. +.BI DC\~ "L text"\~\c +.RI [ color ] +Format a \[lq]drop cap\[rq]\[em]a large character +.I L +(usually a capital letter) +at a larger size and with a lower text baseline +than the following +.I text, +such that the cap-heights of +.I L +and +.I text +align, +in the specified +.I color +(default: black). . -The first parameter is the letter to be dropped and enlarged, the second -parameter -.B text -is the adjoining text whose height the first letter should not exceed. . -The optional third parameter is the color of the dropped letter. +.TP +.B CDS +Begin code display; +a monospaced font is selected and filling is disabled. . -It defaults to black. . .TP -.B ".CDS" -Start displaying a code section in constant width font. +.B CDE +End code display. . -.TP -.B ".CDE" -End code display . .TP -.B ".ALN [color] [percentage]" -Place section heading links automatically to the left of the main text. +.BR ALN \~\c +.RI [ color\~ [ width-percentage ]] +Enable a \[lq]navigation pane\[rq] containing links to section headings, +aligned to the left of running text, +and configure its rendering parameters. . -The color argument is optional and if present indicates which HTML -background color is to be used under the links. +Columnation is achieved with an HTML table. . -The optional percentage indicates the amount of width to devote to -displaying the links. +.I color +indicates an HTML background color to be used in the navigation column; +the default is +.BR #eeeeee . . -The default values are #eeeeee and 30 for color and percentage width, -respectively. +.I width-percentage +allocates the given percentage of the the navigation pane's table +column; +the default is +.BR 30 . . -This macro should only be called once at the beginning of the document. +Call this macro at most once, +at the beginning of the document. . -After calling this macro each section heading emits an HTML table -consisting of the links in the left and the section text on the right. . .TP -.B ".LNS" -Start a new two-column table with links in the left column. -. -This can be called if the document has text before the first \&.SH and -if \&.ALN is used. +.B LNS +Begin text indexed by the navigation pane configured by +.BR ALN . . -Typically this is called just before the first paragraph and after the -main title as it indicates that text after this point should be -positioned to the right of the left-hand navigational links. . .TP -.B ".LNE" -End a two-column table. +.B LNE +End text indexed by navigation pane started by +.BR LNS . . -This should be called at the end of the document if \&.ALN was used. . .TP -.B ".LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]" -Initialize default URL attributes to be used if this macro set is not -used with the HTML device. -. -The macro set initializes itself with the following call -. -. -.RS -.IP -.EX -\&.LINKSTYLE blue CR \e[la] \e[ra] -.EE -.RE -. -. -.IP -but these values will be superseded by a user call to LINKSTYLE. +.BI LINKSTYLE\~ color\~\c +.RI [ font-style\~ [ "open-glyph close-glyph" ]] +Configure rendering of formatted hyperlink targets for devices other +than +.B html +and +.BR xhtml ; +render +targets in +.I color +(default: +blue) \" XXX: whose default? the browser's? +using the typeface +.I font-style +(default: +.BR CR ) +bracketed with +.I open-glyph +and +.I close-glyph +(defaults: +.B \[rs][la] +and +.BR \[rs][ra] , +respectively). . . .\" ==================================================================== @@ -686,11 +525,10 @@ By default generates links to all section headings and places these at the top of the HTML document. . -(See -.UR #LK -LINKS -.UE -for details of how to switch this off or alter the position). +Configure this behavior with +.B HX +and/or +.BR LK . . . .\" ==================================================================== @@ -710,6 +548,35 @@ distribution should be explored. . . +.P +All URLs currently are treated as consuming no textual +space in +.IR groff . +. +This could be considered as a bug since it causes some problems. +. +To circumvent this, +.I www.tmac +inserts a zero-width character which expands to a harmless space +(only +if run with +.B \-Thtml +or +.BR \-Txhtml ). +. +. +.P +Some of the macros, +like +.BR ALN , +.BR LNS , +and +.BR LNE , +are integrated only with the +.MR groff_ms @MAN7EXT@ +package. +. +. .\" ==================================================================== .SH Files .\" ==================================================================== |
