mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-12 11:10:07 +00:00
new docs
This commit is contained in:
rsc
parent
dc4f9bcdd0
commit
37052ddc26
3 changed files with 566 additions and 0 deletions
119
man/man1/htmlroff.1
Normal file
119
man/man1/htmlroff.1
Normal file
|
|
@ -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)
|
||||||
342
man/man7/htmlroff.7
Normal file
342
man/man7/htmlroff.7
Normal file
|
|
@ -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.
|
||||||
105
man/man7/mhtml.7
Normal file
105
man/man7/mhtml.7
Normal file
|
|
@ -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)
|
||||||
Loading…
Reference in a new issue