=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.45 retrieving revision 1.50 diff -u -p -r1.45 -r1.50 --- mandoc/mandoc.1 2009/10/26 15:44:51 1.45 +++ mandoc/mandoc.1 2010/01/29 14:39:38 1.50 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.45 2009/10/26 15:44:51 kristaps Exp $ +.\" $Id: mandoc.1,v 1.50 2010/01/29 14:39:38 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 26 2009 $ +.Dd $Mdocdate: January 29 2010 $ .Dt MANDOC 1 .Os . @@ -96,55 +96,14 @@ or .Xr man 7 text from stdin, implying .Fl m Ns Ar andoc , -and prints 78-column backspace-encoded output to stdout as if +and produces .Fl T Ns Ar ascii -were provided. +output. . .Pp .Ex -std mandoc . . -.Ss Punctuation and Spacing -If punctuation is set apart from words, such as in the phrase -.Dq to be \&, or not to be , -it's processed by -.Nm -according to the following rules: opening punctuation -.Po -.Sq \&( , -.Sq \&[ , -and -.Sq \&{ -.Pc -is not followed by a space; closing punctuation -.Po -.Sq \&. , -.Sq \&, , -.Sq \&; , -.Sq \&: , -.Sq \&? , -.Sq \&! , -.Sq \&) , -.Sq \&] -and -.Sq \&} -.Pc -is not preceded by whitespace. -. -.Pp -If the input is -.Xr mdoc 7 , -these rules are also applied to macro arguments when appropriate. -. -.Pp -White-space, in non-literal (normal) mode, is stripped from input and -replaced on output by a single space. Thus, if you wish to preserve multiple -spaces, they must be space-escaped or used in a literal display mode, e.g., -.Sq \&Bd \-literal -in -.Xr mdoc 7 . -. -. .Ss Input Formats The .Nm @@ -195,16 +154,23 @@ The .Nm utility accepts the following .Fl T -arguments: +arguments (see +.Sx OUTPUT ) : . .Bl -tag -width Ds .It Fl T Ns Ar ascii Produce 7-bit ASCII output, backspace-encoded for bold and underline -styles. This is the default. +styles. This is the default. See +.Sx ASCII Output . . .It Fl T Ns Ar html -Produce strict HTML-4.01 output, with a sane default style. +Produce strict HTML-4.01 output, with a sane default style. See +.Sx HTML Output . . +.It Fl T Ns Ar xhtml +Produce strict XHTML-1.0 output, with a sane default style. See +.Sx XHTML Output . +. .It Fl T Ns Ar tree Produce an indented parse tree. . @@ -255,10 +221,11 @@ Don't halt when encountering parse errors. Useful wit over a large set of manuals passed on the command line. .El . +. .Ss Output Options For the time being, only .Fl T Ns Ar html -is the only mode with output options: +accepts output options: .Bl -tag -width Ds .It Fl O Ns Ar style=style.css The file @@ -268,7 +235,7 @@ relative URI. .It Fl O Ns Ar includes=fmt The string .Ar fmt , -for example, +for example, .Ar ../src/%I.html , is used as a template for linked header files (usually via the .Sq \&In @@ -279,7 +246,7 @@ hyperlink. .It Fl O Ns Ar man=fmt The string .Ar fmt , -for example, +for example, .Ar ../html%S/%N.%S.html , is used as a template for linked manuals (usually via the .Sq \&Xr @@ -292,6 +259,110 @@ If no section is included, section 1 is assumed. The present a hyperlink. .El . +. +.Sh OUTPUT +This section documents output details of +.Nm . +In general, output conforms to the traditional manual style of a header, +a body composed of sections and sub-sections, and a footer. +.Pp +The text style of output characters (non-macro characters, punctuation, +and white-space) is dictated by context. +.Pp +White-space is generally stripped from input. This can be changed with +character escapes (specified in +.Xr mandoc_char 7 ) +or literal modes (specified in +.Xr mdoc 7 +and +.Xr man 7 ) . +.Pp +If non-macro punctuation is set apart from words, such as in the phrase +.Dq to be \&, or not to be , +it's processed by +.Nm , +regardless of output format, according to the following rules: opening +punctuation +.Po +.Sq \&( , +.Sq \&[ , +and +.Sq \&{ +.Pc +is not followed by a space; closing punctuation +.Po +.Sq \&. , +.Sq \&, , +.Sq \&; , +.Sq \&: , +.Sq \&? , +.Sq \&! , +.Sq \&) , +.Sq \&] +and +.Sq \&} +.Pc +is not preceded by white-space. +. +.Pp +If the input is +.Xr mdoc 7 , +however, these rules are also applied to macro arguments when appropriate. +. +. +.Ss ASCII Output +Output produced by +.Fl T Ns Ar ascii , +which is the default, is rendered in standard 7-bit ASCII documented in +.Xr ascii 7 . +.Pp +Font styles are applied by using back-spaced encoding such that an +underlined character +.Sq c +is rendered as +.Sq _ Ns \e[bs] Ns c , +where +.Sq \e[bs] +is the back-space character number 8. Emboldened characters are rendered as +.Sq c Ns \e[bs] Ns c . +.Pp +The special characters documented in +.Xr mandoc_char 7 +are rendered best-effort in an ASCII equivalent. +.Pp +Output width is limited to 78 visible columns unless literal input lines +exceed this limit. +. +. +.Ss HTML Output +Output produced by +.Fl T Ns Ar html +conforms to HTML-4.01 strict. +.Pp +Font styles and page structure are applied using CSS2. By default, no +font style is applied to any text, although CSS2 is hard-coded to format +the basic structure of output. +.Pp +The +.Pa example.style.css +file documents the range of styles applied to output and, if used, will +cause rendered documents to appear as they do in +.Fl T Ns Ar ascii . +.Pp +Special characters are rendered in decimal-encoded UTF-8. +. +. +.Ss XHTML Output +Output produced by +.Fl T Ns Ar xhtml +conforms to XHTML-1.0 strict. +.Pp +See +.Sx HTML Output +for details; beyond generating XHTML tags instead of HTML tags, these +output modes are identical. +. +. .Sh EXAMPLES To page manuals to the terminal: . @@ -304,7 +375,7 @@ To produce HTML manuals with .Ar style.css as the style-sheet: .Pp -.D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html +.D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html .Pp To check over a large set of manuals: . @@ -320,18 +391,18 @@ compatibility with Each input and output format is separately noted. . . -.Ss ASCII output +.Ss ASCII Compatibility .Bl -bullet -compact .It -The +The .Sq \e~ -special character doesn't produce expected behaviour in +special character doesn't produce expected behaviour in .Fl T Ns Ar ascii . . .It -The +The .Sq \&Bd \-literal -and +and .Sq \&Bd \-unfilled macros of .Xr mdoc 7 @@ -340,7 +411,7 @@ in are synonyms, as are \-filled and \-ragged. . .It -In +In .Xr groff 1 , the .Sq \&Pa @@ -380,10 +451,21 @@ retains spaces. Sentences are unilaterally monospaced. .El . -.Ss HTML output +. +.Ss HTML/XHTML Compatibility .Bl -bullet -compact .It The +.Sq \efP +escape will revert the font to the previous +.Sq \ef +escape, not to the last rendered decoration, which is now dictated by +CSS instead of hard-coded. It also will not span past the current +scope, for the same reason. Note that in +.Sx ASCII Output +mode, this will work fine. +.It +The .Xr mdoc 7 .Sq \&Bl \-hang and @@ -399,7 +481,8 @@ and .Sq TP lists render similarly. .El -.\" SECTION +. +. .Sh SEE ALSO .Xr mandoc_char 7 , .Xr mdoc 7 , @@ -411,11 +494,34 @@ The utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . . +. .Sh CAVEATS +The +.Fl T Ns Ar html +and +.Fl T Ns Ar xhtml +CSS2 styling used for +.Fl m Ns Ar doc +input lists does not render properly in brain-dead browsers, such as +Internet Explorer 6 and earlier. +.Pp In -.Fl T Ns Ar html , +.Fl T Ns Ar html +and +.Fl T Ns Ar xhtml , the maximum size of an element attribute is determined by .Dv BUFSIZ , which is usually 1024 bytes. Be aware of this when setting long link -formats with -.Fl O Ns Ar man=fmt . +formats, e.g., +.Fl O Ns Ar style=really/long/link . +.Pp +The +.Fl T Ns Ar html +and +.Fl T Ns Ar xhtml +output modes don't render the +.Sq \es +font size escape documented in +.Xr mdoc 7 +and +.Xr man 7 .