=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.112 retrieving revision 1.123 diff -u -p -r1.112 -r1.123 --- mandoc/mandoc.1 2014/09/12 00:10:26 1.112 +++ mandoc/mandoc.1 2014/11/25 20:18:15 1.123 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.112 2014/09/12 00:10:26 schwarze Exp $ +.\" $Id: mandoc.1,v 1.123 2014/11/25 20:18:15 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014 Ingo Schwarze @@ -15,7 +15,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: September 12 2014 $ +.Dd $Mdocdate: November 25 2014 $ .Dt MANDOC 1 .Os .Sh NAME @@ -27,6 +27,7 @@ .Sm off .Op Fl I Cm os Li = Ar name .Sm on +.Op Fl K Ns Ar encoding .Op Fl m Ns Ar format .Op Fl O Ns Ar option .Op Fl T Ns Ar output @@ -88,7 +89,32 @@ macro. .It Fl h Display only the SYNOPSIS lines. Implies -.Fl a . +.Fl c . +.It Fl K Ns Ar encoding +Specify the input encoding. +The supported +.Ar encoding +arguments are +.Cm us-ascii , +.Cm iso-8859-1 , +and +.Cm utf-8 . +If not specified, autodetection uses the first match: +.Bl -tag -width iso-8859-1 +.It Cm utf-8 +if the first three bytes of the input file +are the UTF-8 byte order mark (BOM, 0xefbbbf) +.It Ar encoding +if the first or second line of the input file matches the +.Sy emacs +mode line format +.Pp +.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- +.It Cm utf-8 +if the first non-ASCII byte in the file introduces a valid UTF-8 sequence +.It Cm iso-8859-1 +otherwise +.El .It Fl k A synonym for .Xr apropos 1 . @@ -233,7 +259,7 @@ This is the default. See .Sx ASCII Output . .It Fl T Ns Cm html -Produce strict CSS1/HTML-4.01 output. +Produce HTML5, CSS1, and MathML output. See .Sx HTML Output . .It Fl T Ns Cm lint @@ -265,9 +291,8 @@ Encode output in the UTF\-8 multi-byte format. See .Sx UTF\-8 Output . .It Fl T Ns Cm xhtml -Produce strict CSS1/XHTML-1.0 output. -See -.Sx XHTML Output . +This is a synonym for +.Fl T Ns Cm html . .El .Pp If multiple input files are specified, these will be processed by the @@ -320,7 +345,11 @@ which will normalise to \(>=60. .Ss HTML Output Output produced by .Fl T Ns Cm html -conforms to HTML-4.01 strict. +conforms to HTML5 using optional self-closing tags. +Default styles use only CSS1. +Equations rendered from +.Xr eqn 7 +blocks use MathML. .Pp The .Pa example.style.css @@ -328,7 +357,8 @@ file documents style-sheet classes available for custo If a style-sheet is not specified with .Fl O Ns Ar style , .Fl T Ns Cm html -defaults to simple output readable in any graphical or text-based web +defaults to simple output (via an embedded style-sheet) +readable in any graphical or text-based web browser. .Pp Special characters are rendered in decimal-encoded UTF\-8. @@ -338,16 +368,8 @@ The following arguments are accepted: .Bl -tag -width Ds .It Cm fragment -Omit the -.Aq !DOCTYPE -declaration and the -.Aq html , -.Aq head , -and -.Aq body -elements and only emit the subtree below the -.Aq body -element. +Omit the declaration and the , , and +elements and only emit the subtree below the element. The .Cm style argument will be ignored. @@ -471,15 +493,6 @@ to force a UTF\-8 locale. See .Sx Locale Output for details and options. -.Ss XHTML Output -Output produced by -.Fl T Ns Cm 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 ENVIRONMENT .Bl -tag -width MANPAGER .It Ev MANPAGER @@ -916,8 +929,11 @@ The previous, interrupted macro is deleted from the pa .Ss "Warnings related to missing arguments" .Bl -ohang .It Sy "skipping empty request" -.Pq roff -The macro name is missing from a macro definition request. +.Pq roff , eqn +The macro name is missing from a macro definition request, +or an +.Xr eqn 7 +control statement or operation keyword lacks its required argument. .It Sy "conditional request controls empty scope" .Pq roff A conditional request is only useful if any of the following @@ -1051,6 +1067,11 @@ The utility assumes .Fl std even when it is not specified, but other implementations may not. +.It Sy "missing eqn box, using \(dq\(dq" +.Pq eqn +A diacritic mark or a binary operator is found, +but there is nothing to the left of it. +An empty box is inserted. .El .Ss "Warnings related to bad macro arguments" .Bl -ohang @@ -1118,6 +1139,21 @@ macro has an invalid argument. It is used verbatim, with .Qq "AT&T UNIX " prefixed to it. +.It Sy "comma in function argument" +.Pq mdoc +An argument of an +.Ic \&Fa +or +.Ic \&Fn +macro contains a comma; it should probably be split into two arguments. +.It Sy "parenthesis in function name" +.Pq mdoc +The first argument of an +.Ic \&Fc +or +.Ic \&Fn +macro contains an opening or closing parenthesis; that's probably wrong, +parentheses are added automatically. .It Sy "invalid content in Rs block" .Pq mdoc An @@ -1136,11 +1172,16 @@ or The invalid argument is moved out of the macro, which leaves the macro empty, causing it to toggle the spacing mode. .It Sy "unknown font, skipping request" -.Pq man +.Pq man , tbl A .Xr roff 7 .Ic \&ft -request has an invalid argument. +request or a +.Xr tbl 7 +.Ic \&f +layout modifier has an unknown +.Ar font +argument. .El .Ss "Warnings related to plain text" .Bl -ohang @@ -1203,7 +1244,6 @@ keeps the code more readable. .It "equation scope open on exit" .It "overlapping equation scopes" .It "unexpected end of equation" -.It "equation syntax error" .El .Ss "Errors related to tables" .Bl -inset -compact @@ -1257,12 +1297,15 @@ macro. It may be mistyped or unsupported. The request or macro is discarded including its arguments. .It Sy "skipping item outside list" -.Pq mdoc +.Pq mdoc , eqn An .Ic \&It macro occurs outside any .Ic \&Bl -list. +list, or an +.Xr eqn 7 +.Ic above +delimiter occurs outside any pile. It is discarded including its arguments. .It Sy "skipping column outside column list" .Pq mdoc @@ -1283,7 +1326,9 @@ block closing macro, a .Ic \&RE or .Ic \&UE -macro, or the end of an equation, table, or +macro, an +.Xr eqn 7 +right delimiter or closing brace, or the end of an equation, table, or .Xr roff 7 conditional request is encountered but no matching block is open. The offending request or macro is discarded. @@ -1380,11 +1425,16 @@ An .Ic \&St macro has an unknown argument and is discarded. .It Sy "skipping request without numeric argument" -.Pq roff +.Pq roff , eqn An .Ic \&it -request has a non-numeric or negative argument or no argument at all. -The invalid request is ignored. +request or an +.Xr eqn 7 +.Ic \&size +or +.Ic \&gsize +statement has a non-numeric or negative argument or no argument at all. +The invalid request or statement is ignored. .It Sy "skipping all arguments" .Pq mdoc , man , eqn , roff An @@ -1407,6 +1457,8 @@ or .Ic \&PP macro, an .Xr eqn 7 +.Ic \&EQ +or .Ic \&EN macro, or a .Xr roff 7 @@ -1522,7 +1574,7 @@ has no effect. .It Words aren't hyphenated. .El -.Ss HTML/XHTML Compatibility +.Ss HTML Compatibility .Bl -bullet -compact .It The