tnew docs - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 37052ddc266b4708c0629bc976b975091a195b3d
(DIR) parent dc4f9bcdd0b85f67813752a86c2c68526b559bf3
(HTM) Author: rsc <devnull@localhost>
Date: Sun, 19 Mar 2006 06:11:23 +0000
new docs
Diffstat:
A man/man1/htmlroff.1 | 119 +++++++++++++++++++++++++++++++
A man/man7/htmlroff.7 | 342 +++++++++++++++++++++++++++++++
A man/man7/mhtml.7 | 105 +++++++++++++++++++++++++++++++
3 files changed, 566 insertions(+), 0 deletions(-)
---
(DIR) diff --git a/man/man1/htmlroff.1 b/man/man1/htmlroff.1
t@@ -0,0 +1,119 @@
+.TH HTMLROFF 1
+.SH NAME
+htmlroff \- HTML formatting and typesetting
+.SH SYNOPSIS
+.B htmlroff
+[
+.B -iuv
+]
+[
+.B -m
+.I name
+]
+[
+.B -r
+.I aN
+]
+[
+.I file
+\&...
+]
+.SH DESCRIPTION
+.I Htmlroff
+accepts
+.IR troff (1)
+input in the named
+.I files
+and formats it as HTML for viewing in a web browser.
+.PP
+If no
+.I file
+argument is given,
+.I htmlroff
+reads the standard input.
+An argument consisting of a single minus
+.RB ( - )
+is taken to be
+a file name corresponding to the standard input.
+The options are:
+.TP
+.B -i
+Read standard input after the input files are exhausted.
+.TP
+.BI -m name
+Process the macro file
+.BI \*9/tmac/tmac. name
+before the input
+.IR files .
+.TP
+.BI -r aN
+Set register
+.I a
+(one character name) to
+.IR N .
+.TP
+.B -u
+Generate UTF output.
+By default,
+.I htmlroff
+converts Unicode runes into the corresponding
+HTML entity sequences
+.RB ( α ,
+.BR ,
+and so on).
+.I Htmlroff
+invokes
+.IR tcs (1)
+for the conversion.
+.TP
+.B -v
+Generate debugging output and warnings about suspicious input.
+.PD
+.PP
+Most
+.I troff
+input files, especially those using the
+.IR ms (7)
+macros, can be used unaltered.
+In general, the macro file
+.B tmac.html
+should be processed after processing other standard macro files,
+as in
+.B htmlroff
+.B -ms
+.BR -mhtml .
+.PP
+.IR Htmlroff (7)
+describes the changes to the input language.
+.PP
+.IR Mhtml (7)
+describes the new macros.
+.SH EXAMPLES
+Format the Plan 9 web page:
+.IP
+.EX
+cd /usr/web/plan9
+htmlroff -mhtml index.tr >index.html
+.EE
+.PP
+Format a paper:
+.IP
+.EX
+cd /sys/doc
+pic auth.ms | tbl | eqn | htmlroff -ms -mhtml >auth.html
+.EE
+.SH FILES
+.TP
+.B \*9/troff/font/devutf/utfmap
+Mapping from
+.I troff
+two-character names like
+.B \e(*a
+to Unicode characters like α.
+.SH SOURCE
+.B \*9/src/cmd/htmlroff
+.SH "SEE ALSO
+.IR tcs (1),
+.IR troff (1),
+.IR htmlroff (7),
+.IR mhtml (7)
(DIR) diff --git a/man/man7/htmlroff.7 b/man/man7/htmlroff.7
t@@ -0,0 +1,342 @@
+.TH HTMLROFF 7
+.SH NAME
+htmlroff \- HTML formatting and typesetting
+.SH DESCRIPTION
+.I Htmlroff (1)
+accepts
+.I troff
+input with a few extensions and changes.
+This manual describes the changes to the input language,
+assuming a working knowledge of
+.I troff
+itself.
+.SS Name lengths
+.PP
+Request, macro, string, and number names can be longer
+than two letters, as in:
+.IP
+.EX
+\&.html c <center>
+\&.de footnote
+Footnote here.
+\&..
+\&.footnote
+\&.ds string "hello
+\&\e*[string]
+\&.nr number 1
+\&\en[number]
+.EE
+.SS HTML output
+.PP
+Two new requests:
+.IP
+.EX
+\&.html \fIid\fP \fR[ \fI<html>\fP ]\fL
+\&.ihtml \fIid\fP \fR[ \fI<ihtml>\fP ]\fL
+.EE
+.LP
+.B .html
+and
+.B .ihtml
+insert HTML into the output.
+The requests are only for opening new HTML tags.
+To close previously-opened tags, repeat the request
+with the same
+.IR id .
+For example, the input:
+.IP
+.EX
+\&.html t <table><tr>
+\&.html td <td>Cell 1
+\&.html td <td>Cell 2
+\&.html td
+\&.html t
+.EX
+.LP
+produces this output:
+.IP
+.EX
+<table><tr><td>Cell 1</td><td>Cell 2</td></tr></table>
+.EE
+.LP
+The
+.B .html
+request is intended for block-level HTML constructs (those that can contain
+.BR <p> )
+and maintains the HTML tag stack automatically.
+Intermediate tags need not be explicitly closed:
+removing the final
+.B \&.html t
+line in the example above would produce the same output.
+The special
+.I id
+.L -
+closes the HTML tags immediately after printing them.
+.PP
+The
+.B .ihtml
+request is similar to
+.B .html
+but is intended for inline HTML constructs such as
+.B <b>
+or
+.B <i>
+(those that can be contained
+within
+.BR <p> ).
+Unlike
+.BR .html ,
+.B .ihtml
+treats the open HTML tags as a set rather than a stack:
+each must be explicitly closed.
+Although it treats the tags as a set,
+.B .ihtml
+treats nesting properly in the output,
+closing and reopening tags as necessary.
+For example, the input:
+.IP
+.EX
+\&.ihtml style <b>
+\&.ihtml link <a href="link.html">
+Bold
+\&.ihtml style <i>
+and italic, still linked.
+\&.ihtml link <a>
+Unlinked.
+\&.ihtml style
+.EE
+.LP
+produces this output:
+.IP
+.EX
+<b><a href="link.html">Bold</a></b>
+<i><a href="link.html">and italic, still linked.</i></a>
+<i>Unlinked.</i>
+.EE
+.PP
+Outside of
+.B .html
+and
+.B .ihtml
+requests, the characters
+.L < ,
+.L > ,
+and
+.L &
+are treated as normal characters, not HTML markers,
+and are translated to
+.L < ,
+.L > ,
+and
+.L &
+on output.
+To embed the raw HTML markers, use
+.L \e< ,
+.L \e> ,
+and
+.L \e@
+.RI [ sic ].
+.SS Font changes
+.PP
+.I Htmlroff
+interprets the usual
+.BR \ef ,
+.BR .ft ,
+.BR \es ,
+and
+.B .ps
+requests to change the font and point size.
+After applying each such change to its internal registers,
+.I htmlroff
+invokes the
+.B .font
+macro to emit corresponding HTML.
+The default definition of
+.B .font
+is:
+.IP
+.EX
+\&.de font
+\&.ihtml f1
+\&.ihtml f
+\&.ihtml f <span style=\"font-size=\\n(.spt\">
+\&.if \\n(.f==2 .ihtml f1 <i>
+\&.if \\n(.f==3 .ihtml f1 <b>
+\&.if \\n(.f==4 .ihtml f1 <b><i>
+\&.if \\n(.f==5 .ihtml f1 <tt>
+\&.if \\n(.f==6 .ihtml f1 <tt><i>
+\&..
+.EE
+.LP
+Input files can redefine
+.B .font
+like any other request or macro.
+.SS Paragraphs
+.I Htmlroff
+implements line height, text adjustment, and margins by
+wrapping all output text in
+.B <p style="...">
+tags.
+This behavior can be disabled by setting the
+.B .paragraph
+number register to zero.
+Setting the
+.B .margin
+register to zero
+eliminates only the margin annotations.
+.SS Subscripts and superscripts
+.PP
+.I Htmlroff
+interprets the
+.BR \eu ,
+.BR \ed ,
+and
+.BR \ev
+requests to move vertically during output.
+It emits output vertically offset up the page inside
+.B <sup>
+tags and output vertically offset down the page
+inside
+.B <sub>
+tags.
+This heuristic handles simple equations formatted by
+.IR eqn (1).
+.SS Conditional input
+.PP
+To make it easier to write input files that can be formatted by both
+.I troff
+and
+.IR htmlroff ,
+.I htmlroff
+adds a new condition
+.B h
+which evaluates true in
+.B .if
+and
+.B .ie
+requests.
+The
+.B t
+condition continues to evaluate true, to accomodate
+input files trying to distinguish between
+.I troff
+and
+.IR nroff .
+To write a conditional matching
+.I troff
+alone, use
+.RB ` ".if !h .if t" '.
+.PP
+.I Htmlroff 's
+handling of conditional input does not match
+.IR troff 's
+exactly.
+For example,
+.IP
+.EX
+\&.if 0 \e{\e
+\&.de xx
+\&..
+\&.\e}
+.EE
+.LP
+redefines the
+.B xx
+macro in
+.I troff
+but not in
+.IR htmlroff .
+Do not write files depending on this behavior, as this bug may be fixed
+in the future.
+.I Htmlroff
+also mishandles
+.B \e}
+in some cases. To work around them, use
+.B .\e}
+on a line by itself, as in the last example.
+.SS Diversions
+.PP
+Diversions in
+.I htmlroff
+use the alignment in effect at the time of the
+diversion
+when output.
+In particular,
+.IP
+.EX
+\&.di xx
+Line here.
+\&.di
+\&.nf
+\&.ce
+\&.xx
+.EE
+.LP
+produces a centered line in
+.I troff
+but not in
+.IR htmlroff .
+The solution is to center inside the diversion, as in
+.IP
+.EX
+\&.di xx
+\&.if h .ce 999
+Line here
+\&.di
+.EE
+.SS Input pipes
+.PP
+.I Htmlroff
+adds a new request
+.B .inputpipe
+.I stop
+.I cmd
+that redirects
+.I htmlroff 's
+input into a pipe to the
+given
+.I cmd .
+The redirection stops on encountering the line
+.IR stop ,
+optionally followed by white space and extra text.
+This is a dangerous and clusmy request, as
+.I htmlroff
+stops interpreting its input during the redirection, so
+.I stop
+must be found in the input itself, not in a macro that
+the input might appear to call.
+Although clusmy,
+.B .inputpipe
+allows input files to invoke
+.I troff
+to handle complicated input.
+For example,
+.B tmac.html
+redefines the
+.B PS
+macro that marks the beginning of a
+.IR pic (1)
+picture:
+.IP
+.EX
+\&.nr png -1 1
+\&.de PS
+\&.ds pngbase "\e\e*[basename]
+\&.if '\e\e*[pngbase]'' .ds pngbase \e\en(.B
+\&.ds pngfile \e\e*[pngbase]\e\en+[png].png
+\&.html - <center><img src="\e\e*[pngfile]"></center>
+\&.inputpipe .PE troff2png >\e\e*[pngfile]
+\&..
+.EE
+.LP
+This macro invokes the shell script
+.I troff2png
+to run troff and convert the Postscript
+output to a PNG image file.
+Before starting the program, the macro creates
+a new file name for the image and prints
+HTML referring to it.
+The new
+.B .B
+register holds the final path element
+(the base name) of the current input file.
(DIR) diff --git a/man/man7/mhtml.7 b/man/man7/mhtml.7
t@@ -0,0 +1,105 @@
+.TH MHTML 7
+.SH NAME
+mhtml \- macros for formatting HTML
+.SH SYNOPSIS
+.B pic
+.B |
+.B tbl
+.B |
+.B eqn
+.B |
+.B htmlroff
+[
+.B -man
+|
+.B -ms
+]
+.B -mhtml
+.I file
+\&...
+.SH DESCRIPTION
+This package of
+.IR htmlroff (1)
+macro definitions provides convenient macros for formatting HTML.
+It is usually used along with
+.I troff (1)
+macro packages such as
+.IR man (7)
+and
+.IR ms (7).
+.I Mhtml
+replaces some macros defined in the other packages,
+so it should be listed after them on the
+.I htmlroff
+command line.
+.PP
+The following macros are defined:
+.TP
+.B .HTML \fItitle
+Print an HTML header marking the output as
+HTML 4.01 loose transitional encoded in UTF.
+If given, the
+.I title
+is printed inside
+.B <title>
+tags.
+This macro opens the
+.B <html>
+tag, opens and closes the
+.B <head>
+section, and opens
+.B <body> .
+It invokes the
+.B .HEAD
+macro inside the
+.B <head>
+section.
+To add arbitrary lines to the header,
+append to
+.B .HEAD
+before invoking
+.BR .HTML .
+.TP
+.B .FS\fR, \fP.FE
+Accumulate footnotes and print them at the end of the
+document under a \fBNotes\fP heading.
+These replace the macros in
+.IR ms (7).
+To emit the notes accumulated so far, invoke
+.BR .NOTES .
+.TP
+.B .PS\fR, \fP.PE
+Replace input bracketed
+.B .PS
+and
+.B .PE
+with a PNG image corresponding to the output of
+running
+.I troff(1)
+on the input.
+.TP
+.B .TS\fR, \fP.TE
+Identical to
+.B .PS
+and
+.BR .PE .
+.TP
+.B .B1 \fImargin\fP \fIwidth\fR, \fL.B2
+Format the input between
+.B .B1
+and
+.B .B2
+inside a box, with
+.I margin
+(default 10)
+pixels between the box and the text.
+The box is set to be
+.I width
+(default 60)
+percent of the current output width.
+.SH FILES
+.B \*9/tmac/tmac.html
+.SH SEE ALSO
+.IR htmlroff (1),
+.IR htmlroff (7),
+.IR ms (7)