=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.232 retrieving revision 1.244 diff -u -p -r1.232 -r1.244 --- mandoc/mandoc.1 2018/12/15 19:30:26 1.232 +++ mandoc/mandoc.1 2020/06/15 18:05:18 1.244 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.232 2018/12/15 19:30:26 schwarze Exp $ +.\" $OpenBSD: mandoc.1,v 1.244 2020/06/15 18:05:18 schwarze Exp $ .\" +.\" Copyright (c) 2012, 2014-2020 Ingo Schwarze .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2012, 2014-2018 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: December 15 2018 $ +.Dd $Mdocdate: June 15 2020 $ .Dt MANDOC 1 .Os .Sh NAME @@ -222,7 +222,8 @@ reads from standard input. .Pp The options .Fl fhklw -are also supported and are documented in man(1). +are also supported and are documented in +.Xr man 1 . In .Fl f and @@ -256,10 +257,28 @@ where is the back-space character number 8. Emboldened characters are rendered as .Sq c Ns \e[bs] Ns c . +This markup is typically converted to appropriate terminal sequences by +the pager or +.Xr ul 1 . +To remove the markup, pipe the output to +.Xr col 1 +.Fl b +instead. .Pp The special characters documented in .Xr mandoc_char 7 are rendered best-effort in an ASCII equivalent. +In particular, opening and closing +.Sq single quotes +are represented as characters number 0x60 and 0x27, respectively, +which agrees with all ASCII standards from 1965 to the latest +revision (2012) and which matches the traditional way in which +.Xr roff 7 +formatters represent single quotes in ASCII output. +This correct ASCII rendering may look strange with modern +Unicode-compatible fonts because contrary to ASCII, Unicode uses +the code point U+0060 for the grave accent only, never for an opening +quote. .Pp The following .Fl O @@ -300,8 +319,16 @@ If no is specified, reuse the first command line argument that is not a .Ar section number. -This is useful when it is the name of a manual page, -in particular the name of a library function. +If that argument is in +.Xr apropos 1 +.Ar key Ns = Ns Ar val +format, only the +.Ar val +is used rather than the argument as a whole. +This is useful for commands like +.Ql man -akO tag Ic=ulimit +to search for a keyword and jump right to its definition +in the matching manual pages. .It Cm width Ns = Ns Ar width The output width is set to .Ar width @@ -320,9 +347,9 @@ Equations rendered from .Xr eqn 7 blocks use MathML. .Pp -The -.Pa mandoc.css -file documents style-sheet classes available for customising output. +The file +.Pa /usr/share/misc/mandoc.css +documents style-sheet classes available for customising output. If a style-sheet is not specified with .Fl O Cm style , .Fl T Cm html @@ -383,6 +410,23 @@ The file is used for an external style-sheet. This must be a valid absolute or relative URI. +.It Cm tag Ns Op = Ns Ar term +Same syntax and semantics as for +.Sx ASCII Output . +This is implemented by passing a +.Ic file:// +URI ending in a fragment identifier to the pager +rather than passing merely a file name. +When using this argument, use a pager supporting such URIs, for example +.Bd -literal -offset 3n +MANPAGER='lynx -force_html' man -T html -O tag=MANPAGER man +MANPAGER='w3m -T text/html' man -T html -O tag=toc mandoc +.Ed +.Pp +This argument does not work with +.Xr more 1 +or +.Xr less 1 . .It Cm toc If an input file contains at least two non-standard sections, print a table of contents near the beginning of the output. @@ -416,6 +460,11 @@ This is useful for distributing manual sources to lega lacking .Xr mdoc 7 formatters. +Embedded +.Xr eqn 7 +and +.Xr tbl 7 +code is not supported. .Pp If the input format of a file is .Xr man 7 , @@ -671,7 +720,7 @@ No input files have been read. .It 6 An operating system error occurred, for example exhaustion of memory, file descriptors, or process table entries. -Such errors cause +Such errors may cause .Nm to exit at once, possibly in the middle of parsing or formatting a file. .El @@ -686,10 +735,10 @@ To page manuals to the terminal: .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 .Pp To produce HTML manuals with -.Pa mandoc.css +.Pa /usr/share/misc/mandoc.css as the style-sheet: .Pp -.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html +.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html .Pp To check over a large set of manuals: .Pp @@ -697,7 +746,7 @@ To check over a large set of manuals: .Pp To produce a series of PostScript manuals for A4 paper: .Pp -.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps +.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps .Pp Convert a modern .Xr mdoc 7 @@ -707,20 +756,36 @@ format, for use on systems lacking an .Xr mdoc 7 parser: .Pp -.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man +.Dl $ mandoc \-T man foo.mdoc > foo.man .Sh DIAGNOSTICS Messages displayed by .Nm follow this format: .Bd -ragged -offset indent .Nm : -.Ar file : Ns Ar line : Ns Ar column : level : message : macro args +.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments .Pq Ar os .Ed .Pp -Line and column numbers start at 1. +The first three fields identify the +.Ar file +name, +.Ar line +number, and +.Ar column +number of the input file where the message was triggered. +The line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. -Macro names and arguments are omitted where meaningless. +All +.Ar level +and +.Ar message +strings are explained below. +The name of the +.Ar macro +triggering the message and its +.Ar arguments +are omitted where meaningless. The .Ar os operating system specifier is omitted for messages that are relevant @@ -735,6 +800,13 @@ fields. .Pp Message levels have the following meanings: .Bl -tag -width "warning" +.It Cm syserr +An operating system error occurred. +There isn't necessarily anything wrong with the input files. +Output may all the same be missing or incomplete. +.It Cm badarg +Invalid command line arguments were specified. +No input files have been read and no output is produced. .It Cm unsupp An input file uses unsupported low-level .Xr roff 7 @@ -783,8 +855,7 @@ Messages of the .Cm error , and .Cm unsupp -levels except those about non-existent or unreadable input files -are hidden unless their level, or a lower level, is requested using a +levels are hidden unless their level, or a lower level, is requested using a .Fl W option or .Fl T Cm lint @@ -1024,7 +1095,21 @@ macro lacks the mandatory section argument. The section number in a .Ic \&Dt line is invalid, but still used. -.It Sy "missing date, using today's date" +.It Sy "filename/section mismatch" +.Pq mdoc , man +The name of the input file being processed is known and its file +name extension starts with a non-zero digit, but the +.Ic \&Dt +or +.Ic \&TH +macro contains a +.Ar section +argument that starts with a different non-zero digit. +The +.Ar section +argument is used as provided anyway. +Consider checking whether the file name or the argument need a correction. +.It Sy "missing date, using \(dq\(dq" .Pq mdoc, man The document was parsed as .Xr mdoc 7 @@ -1657,9 +1742,12 @@ The meaning of blank input lines is only well-defined In fill mode, line breaks of text input lines are not supposed to be significant. However, for compatibility with groff, blank lines in fill mode -are replaced with +are formatted like .Ic \&sp requests. +To request a paragraph break, use +.Ic \&Pp +instead of a blank line. .It Sy "tab in filled text" .Pq mdoc , man The meaning of tab characters is only well-defined in non-fill mode: @@ -2195,6 +2283,43 @@ or macro or of an undefined macro. The macro is ignored, and its arguments are handled as if they were a text line. +.El +.Ss Bad command line arguments +.Bl -ohang +.It Sy "bad command line argument" +The argument following one of the +.Fl IKMmOTW +command line options is invalid, or a +.Ar file +given as a command line argument cannot be opened. +.It Sy "duplicate command line argument" +The +.Fl I +command line option was specified twice. +.It Sy "option has a superfluous value" +An argument to the +.Fl O +option has a value but does not accept one. +.It Sy "missing option value" +An argument to the +.Fl O +option has no argument but requires one. +.It Sy "bad option value" +An argument to the +.Fl O +.Cm indent +or +.Cm width +option has an invalid value. +.It Sy "duplicate option value" +The same +.Fl O +option is specified more than once. +.It Sy "no such tag" +The +.Fl O Cm tag +option was specified but the tag was not found in any of the displayed +manual pages. .El .Sh SEE ALSO .Xr apropos 1 ,