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