+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)

commit 37052ddc266b4708c0629bc976b975091a195b3d from: rsc date: Sun Mar 19 06:11:23 2006 UTC new docs commit - dc4f9bcdd0b85f67813752a86c2c68526b559bf3 commit + 37052ddc266b4708c0629bc976b975091a195b3d blob - /dev/null blob + 4dff65c84cd53699c0747872358c4a6667f512f9 (mode 644) --- /dev/null +++ man/man1/htmlroff.1 @@ -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) blob - /dev/null blob + 2e93a2d7721557d884b29f8faba30602bdb65787 (mode 644) --- /dev/null +++ man/man7/htmlroff.7 @@ -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 +\&.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\fP ]\fL +\&.ihtml \fIid\fP \fR[ \fI\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 +\&.html td

Cell 1 +\&.html td

Cell 2 +\&.html td +\&.html t +.EX +.LP +produces this output: +.IP +.EX +

Cell 1

Cell 2

+.EE +.LP +The +.B .html +request is intended for block-level HTML constructs (those that can contain +.BR

) +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 +or +.B +(those that can be contained +within +.BR

). +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 +\&.ihtml link +Bold +\&.ihtml style +and italic, still linked. +\&.ihtml link +Unlinked. +\&.ihtml style +.EE +.LP +produces this output: +.IP +.EX +Bold +and italic, still linked. +Unlinked. +.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 +\&.if \\n(.f==2 .ihtml f1 +\&.if \\n(.f==3 .ihtml f1 +\&.if \\n(.f==4 .ihtml f1 +\&.if \\n(.f==5 .ihtml f1 +\&.if \\n(.f==6 .ihtml f1 +\&.. +.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

+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 ^{+tags and output vertically offset down the page +inside +.B _{+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 -}}

+\&.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. blob - /dev/null blob + 666eaad9908506da553e4380791a575e3e005919 (mode 644) --- /dev/null +++ man/man7/mhtml.7 @@ -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 +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)