diff options
Diffstat (limited to 'mandoc.1')
| -rw-r--r-- | mandoc.1 | 141 |
1 files changed, 118 insertions, 23 deletions
@@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.240 2019/07/10 19:39:01 schwarze Exp $ +.\" $OpenBSD: mandoc.1,v 1.166 2020/02/15 15:28:01 schwarze Exp $ .\" +.\" Copyright (c) 2012, 2014-2021 Ingo Schwarze <schwarze@openbsd.org> .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2012, 2014-2019 Ingo Schwarze <schwarze@openbsd.org> .\" .\" 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: July 10 2019 $ +.Dd $Mdocdate: August 14 2021 $ .Dt MANDOC 1 .Os .Sh NAME @@ -52,13 +52,13 @@ The options are as follows: If the standard output is a terminal device and .Fl c is not specified, use -.Xr more 1 +.Xr less 1 to paginate the output, just like .Xr man 1 would. .It Fl c Copy the formatted manual pages to the standard output without using -.Xr more 1 +.Xr less 1 to paginate them. This is the default. It can be specified to override @@ -301,8 +301,8 @@ Format input files in .Xr mdoc 7 output style. -Specifically, this suppresses the two additional blank lines near the -top and the bottom of each page, and it implies +This prints the operating system name rather than the page title +on the right side of the footer line, and it implies .Fl O Cm indent Ns =5 . One useful application is for checking that .Fl T Cm man @@ -410,6 +410,30 @@ 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 +Consequently, for HTML output, this argument does not work with +.Xr more 1 +or +.Xr less 1 . +For example, +.Ql MANPAGER=less man -T html -O tag=toc mandoc +does not work because +.Xr less 1 +does not support +.Ic file:// +URIs. .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. @@ -443,13 +467,15 @@ This is useful for distributing manual sources to legacy systems 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 , -the input is copied to the output, expanding any -.Xr roff 7 -.Ic so -requests. +the input is copied to the output. The parser is also run, and as usual, the .Fl W level controls which @@ -628,7 +654,7 @@ It never affects the interpretation of input files. Any non-empty value of the environment variable .Ev MANPAGER is used instead of the standard pagination program, -.Xr more 1 ; +.Xr less 1 ; see .Xr man 1 for details. @@ -642,8 +668,7 @@ Specifies the pagination program to use when .Ev MANPAGER is not defined. If neither PAGER nor MANPAGER is defined, -.Xr more 1 -.Fl s +.Xr less 1 is used. Only used if .Fl a @@ -897,14 +922,6 @@ generated by CVS or .Ic NetBSD keyword substitution as conventionally used in these operating systems. -.It Sy "referenced manual not found" -.Pq mdoc -An -.Ic \&Xr -macro references a manual page that is not found in the base system. -The path to look for base system manuals is configurable at compile -time and defaults to -.Pa /usr/share/man : /usr/X11R6/man . .El .Ss Style suggestions .Bl -ohang @@ -991,6 +1008,35 @@ list contains two consecutive entries describing the same .Ic \&Er number. +.It Sy "referenced manual not found" +.Pq mdoc +An +.Ic \&Xr +macro references a manual page that was not found. +When running with +.Fl W Cm base , +the search is restricted to the base system, by default to +.Pa /usr/share/man : Ns Pa /usr/X11R6/man . +This path can be configured at compile time using the +.Dv MANPATH_BASE +preprocessor macro. +When running with +.Fl W Cm style , +the search is done along the full search path as described in the +.Xr man 1 +manual page, respecting the +.Fl m +and +.Fl M +command line options, the +.Ev MANPATH +environment variable, the +.Xr man.conf 5 +file and falling back to the default of +.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man , +also configurable at compile time using the +.Dv MANPATH_DEFAULT +preprocessor macro. .It Sy "trailing delimiter" .Pq mdoc The last argument of an @@ -1020,6 +1066,9 @@ An request occurs even though the document already switched to no-fill mode and did not switch back to fill mode yet. It has no effect. +.It Sy "input text line longer than 80 bytes" +Consider breaking the input text line +at one of the blank characters before column 80. .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" .Pq mdoc Even though the ASCII output device renders an em-dash as @@ -1073,7 +1122,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 @@ -1811,6 +1874,10 @@ The invalid character is discarded. A table layout specification contains an opening parenthesis, but no matching closing parenthesis. The rest of the input line, starting from the parenthesis, has no effect. +.It Sy "ignoring excessive spacing in tbl layout" +.Pq tbl +A spacing modifier in a table layout is unreasonably large. +The default spacing of 3n is used instead. .It Sy "tbl without any data cells" .Pq tbl A table does not contain any data cells. @@ -2247,6 +2314,26 @@ or macro or of an undefined macro. The macro is ignored, and its arguments are handled as if they were a text line. +.It Sy "skipping tbl in -Tman mode" +.Pq mdoc , tbl +An input file contains the +.Ic \&TS +macro. +This message is only generated in +.Fl T Cm man +output mode, where +.Xr tbl 7 +input is not supported. +.It Sy "skipping eqn in -Tman mode" +.Pq mdoc , eqn +An input file contains the +.Ic \&EQ +macro. +This message is only generated in +.Fl T Cm man +output mode, where +.Xr eqn 7 +input is not supported. .El .Ss Bad command line arguments .Bl -ohang @@ -2284,6 +2371,14 @@ The .Fl O Cm tag option was specified but the tag was not found in any of the displayed manual pages. +.It Sy "\-Tmarkdown unsupported for man(7) input" +.Pq man +The +.Fl T Cm markdown +option was specified but an input file uses the +.Xr man 7 +language. +No output is produced for that input file. .El .Sh SEE ALSO .Xr apropos 1 , |