=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.116 retrieving revision 1.131 diff -u -p -r1.116 -r1.131 --- mandoc/mandoc.1 2014/10/10 08:44:24 1.116 +++ mandoc/mandoc.1 2015/01/14 22:02:49 1.131 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.116 2014/10/10 08:44:24 kristaps Exp $ +.\" $Id: mandoc.1,v 1.131 2015/01/14 22:02:49 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2012, 2014 Ingo Schwarze +.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -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: October 10 2014 $ +.Dd $Mdocdate: January 14 2015 $ .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 @@ -48,7 +49,7 @@ or text from stdin, implying .Fl m Ns Cm andoc , and produces -.Fl T Ns Cm ascii +.Fl T Ns Cm locale output. .Pp The options are as follows: @@ -84,11 +85,39 @@ Override the default operating system for the .Xr mdoc 7 .Sq \&Os +and for the +.Xr man 7 +.Sq \&TH 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 . @@ -120,7 +149,7 @@ See .Sx Output Formats for available formats. Defaults to -.Fl T Ns Cm ascii . +.Fl T Ns Cm locale . .It Fl V Print version and exit. .It Fl W Ns Ar level @@ -229,7 +258,6 @@ arguments, which correspond to output modes: .Bl -tag -width "-Tlocale" .It Fl T Ns Cm ascii Produce 7-bit ASCII output. -This is the default. See .Sx ASCII Output . .It Fl T Ns Cm html @@ -242,6 +270,7 @@ Implies .Fl W Ns Cm warning . .It Fl T Ns Cm locale Encode output using the current locale. +This is the default. See .Sx Locale Output . .It Fl T Ns Cm man @@ -273,8 +302,8 @@ If multiple input files are specified, these will be p corresponding filter in-order. .Ss ASCII Output Output produced by -.Fl T Ns Cm ascii , -which is the default, is rendered in standard 7-bit ASCII documented in +.Fl T Ns Cm ascii +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 @@ -342,16 +371,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. @@ -395,6 +416,8 @@ relative URI. .Ss Locale Output Locale-depending output encoding is triggered with .Fl T Ns Cm locale . +This is the default. +.Pp This option is not available on all systems: systems without locale support, or those whose internal representation is not natively UCS-4, will fall back to @@ -520,8 +543,8 @@ A fatal parsing error occurred. Invalid command line arguments were specified. No input files have been read. .It 6 -An operating system error occurred, for example memory exhaustion or an -error accessing input files. +An operating system error occurred, for example exhaustion +of memory, file descriptors, or process table entries. Such errors cause .Nm to exit at once, possibly in the middle of parsing or formatting a file. @@ -580,9 +603,6 @@ fields. .Pp Message levels have the following meanings: .Bl -tag -width "warning" -.It Cm syserr -Opening or reading an input file failed, so the parser cannot -even be started and no output is produced from that input file. .It Cm fatal The parser is unable to parse a given input file at all. No formatted output is produced from that input file. @@ -596,6 +616,12 @@ the parser is able to continue, and the error does not generation of formatted output, but typically, preparing that output involves information loss, broken document structure or unintended formatting. +.Pp +Non-existent or unreadable input files are also reported on the +.Cm error +level. +In that case, the parser cannot even be started and no output +is produced from those input files. .It Cm warning An input file uses obsolete, discouraged or non-portable syntax. All the same, the meaning of the input is unambiguous and a correct @@ -609,7 +635,8 @@ Messages of the .Cm warning and .Cm error -levels are hidden unless their level, or a lower level, is requested using a +levels except those about non-existent or unreadable input files +are hidden unless their level, or a lower level, is requested using a .Fl W option or .Fl T Ns Cm lint @@ -647,12 +674,6 @@ macro lacks the mandatory section argument. The section number in a .Ic \&Dt line is invalid, but still used. -.It Sy "unknown manual volume or arch" -.Pq mdoc -The volume name in a -.Ic \&Dt -line is invalid, but still used. -The manual is assumed to be architecture-independent. .It Sy "missing date, using today's date" .Pq mdoc, man The document was parsed as @@ -791,6 +812,13 @@ Probably, there are author names lacking markup. See the .Xr mdoc 7 manual for replacements. +.It Sy "macro neither callable nor escaped" +.Pq mdoc +The name of a macro that is not callable appears on a macro line. +It is printed verbatim. +If the intention is to call it, move it to its own line; +otherwise, escape it by prepending +.Sq \e& . .It Sy "skipping paragraph macro" In .Xr mdoc 7 @@ -911,8 +939,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 @@ -1032,6 +1063,14 @@ argument is invalid. The default font .Cm \efR is used instead. +.It Sy "nothing follows prefix" +.Pq mdoc +A +.Ic \&Pf +macro has no argument, or only one argument and no macro follows +on the same input line. +This defeats its purpose; in particular, spacing is not suppressed +before the text or macros following on the next input line. .It Sy "missing -std argument, adding it" .Pq mdoc An @@ -1046,6 +1085,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 @@ -1120,6 +1164,14 @@ An argument of an 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 @@ -1210,7 +1262,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 @@ -1222,6 +1273,7 @@ keeps the code more readable. .It "ignore data in cell" .It "data block still open" .It "ignoring extra data cells" +.It "ignoring macro in table" .El .Ss "Errors related to roff, mdoc, and man code" .Bl -ohang @@ -1264,12 +1316,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 @@ -1290,7 +1345,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. @@ -1358,6 +1415,17 @@ The indicated request or macro has too few or too many The syntax tree will contain the wrong number of arguments as given. Formatting behaviour depends on the specific request or macro in question. Note that the same message may also occur as a WARNING, see above. +.It Sy "NOT IMPLEMENTED: Bd -file" +.Pq mdoc +For security reasons, the +.Ic \&Bd +macro does not support the +.Fl file +argument. +By requesting the inclusion of a sensitive file, a malicious document +might otherwise trick a privileged user into inadvertently displaying +the file on the screen, revealing the file content to bystanders. +The argument is ignored including the file name following it. .It Sy "missing list type, using -item" .Pq mdoc A @@ -1387,11 +1455,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 @@ -1414,6 +1487,8 @@ or .Ic \&PP macro, an .Xr eqn 7 +.Ic \&EQ +or .Ic \&EN macro, or a .Xr roff 7 @@ -1439,17 +1514,6 @@ cannot handle input files larger than its arbitrary si of 2^31 bytes (2 Gigabytes). Since useful manuals are always small, this is not a problem in practice. Parsing is aborted as soon as the condition is detected. -.It Sy "NOT IMPLEMENTED: Bd -file" -.Pq mdoc -For security reasons, the -.Ic \&Bd -macro does not support the -.Fl file -argument. -By requesting the inclusion of a sensitive file, a malicious document -might otherwise trick a privileged user into inadvertently displaying -the file on the screen, revealing the file content to bystanders. -The parser exits immediately. .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" .Pq roff For security reasons,