diff options
Diffstat (limited to 'contrib/mdocml/mandoc.1')
| -rw-r--r-- | contrib/mdocml/mandoc.1 | 356 |
1 files changed, 228 insertions, 128 deletions
diff --git a/contrib/mdocml/mandoc.1 b/contrib/mdocml/mandoc.1 index 45615d5d02ba..166905b6bf2c 100644 --- a/contrib/mdocml/mandoc.1 +++ b/contrib/mdocml/mandoc.1 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.174 2017/02/10 15:45:28 schwarze Exp $ +.\" $Id: mandoc.1,v 1.196 2017/06/08 00:23:30 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org> @@ -15,19 +15,19 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: February 10 2017 $ +.Dd $Mdocdate: June 8 2017 $ .Dt MANDOC 1 .Os .Sh NAME .Nm mandoc -.Nd format and display UNIX manuals +.Nd format manual pages .Sh SYNOPSIS .Nm mandoc -.Op Fl acfhkl +.Op Fl ac .Op Fl I Cm os Ns = Ns Ar name .Op Fl K Ar encoding -.Op Fl m Ns Ar format -.Op Fl O Ar option +.Op Fl mdoc | man +.Op Fl O Ar options .Op Fl T Ar output .Op Fl W Ar level .Op Ar @@ -44,9 +44,7 @@ reads .Xr mdoc 7 or .Xr man 7 -text from stdin, implying -.Fl m Ns Cm andoc , -and produces +text from stdin and produces .Fl T Cm locale output. .Pp @@ -67,28 +65,21 @@ to paginate them. This is the default. It can be specified to override .Fl a . -.It Fl f -A synonym for -.Xr whatis 1 . -This overrides any earlier -.Fl k -and -.Fl l -options. -.It Fl h -Display only the SYNOPSIS lines. -Implies -.Fl c . .It Fl I Cm os Ns = Ns Ar name Override the default operating system .Ar name for the .Xr mdoc 7 -.Sq \&Os +.Ic \&Os and for the .Xr man 7 -.Sq \&TH +.Ic \&TH macro. +This can also be used to perform style checks according to the +conventions of one operating system while running on a different +operating system; see +.Sx Style messages +for details. .It Fl K Ar encoding Specify the input encoding. The supported @@ -98,46 +89,53 @@ arguments are .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 +If not specified, autodetection uses the first match in the following +list: +.Bl -enum +.It +If the first three bytes of the input file are the UTF-8 byte order +mark (BOM, 0xefbbbf), input is interpreted as +.Cm utf-8 . +.It +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 +.Pp +then input is interpreted according to +.Ar encoding . +.It +If the first non-ASCII byte in the file introduces a valid UTF-8 +sequence, input is interpreted as +.Cm utf-8 . +.It +Otherwise, input is interpreted as +.Cm iso-8859-1 . .El -.It Fl k -A synonym for -.Xr apropos 1 . -This overrides any earlier -.Fl f -and -.Fl l -options. -.It Fl l -A synonym for -.Fl a . -Also reverts any earlier -.Fl f -and -.Fl k -options. -.It Fl m Ns Ar format -Input format. -See -.Sx Input Formats -for available formats. -Defaults to -.Fl m Ns Cm andoc . -.It Fl O Ar option +.It Fl mdoc | man +With +.Fl mdoc , +all input files are interpreted as +.Xr mdoc 7 . +With +.Fl man , +all input files are interpreted as +.Xr man 7 . +By default, the input language is automatically detected for each file: +if the the first macro is +.Ic \&Dd +or +.Ic \&Dt , +the +.Xr mdoc 7 +parser is used; otherwise, the +.Xr man 7 +parser is used. +With other arguments, +.Fl m +is silently ignored. +.It Fl O Ar options Comma-separated output options. .It Fl T Ar output Output format. @@ -153,13 +151,14 @@ to be reported on the standard error output and to affect the exit status. The .Ar level can be +.Cm style , .Cm warning , .Cm error , or .Cm unsupp ; .Cm all is an alias for -.Cm warning . +.Cm style . By default, .Nm is silent. @@ -190,6 +189,9 @@ If multiple files are specified, will halt with the first failed parse. .El .Pp +The options +.Fl fhklw +are also supported and are documented in man(1). In .Fl f and @@ -197,60 +199,20 @@ and mode, .Nm also supports the options -.Fl CMmOSsw +.Fl CMmOSs described in the .Xr apropos 1 manual. -.Ss Input Formats -The -.Nm -utility accepts -.Xr mdoc 7 -and -.Xr man 7 -input with -.Fl m Ns Cm doc -and -.Fl m Ns Cm an , -respectively. -The -.Xr mdoc 7 -format is -.Em strongly -recommended; -.Xr man 7 -should only be used for legacy manuals. -.Pp -A third option, -.Fl m Ns Cm andoc , -which is also the default, determines encoding on-the-fly: if the first -non-comment macro is -.Sq \&Dd -or -.Sq \&Dt , -the -.Xr mdoc 7 -parser is used; otherwise, the -.Xr man 7 -parser is used. -.Pp -If multiple -files are specified with -.Fl m Ns Cm andoc , -each has its file-type determined this way. -If multiple files are -specified and -.Fl m Ns Cm doc -or -.Fl m Ns Cm an -is specified, then this format is used exclusively. +The options +.Fl fkl +are mutually exclusive and override each other. .Ss Output Formats The .Nm utility accepts the following .Fl T arguments, which correspond to output modes: -.Bl -tag -width "-T locale" +.Bl -tag -width "-T markdown" .It Fl T Cm ascii Produce 7-bit ASCII output. See @@ -262,7 +224,7 @@ See .It Fl T Cm lint Parse only: produce no output. Implies -.Fl W Cm warning . +.Fl W Cm style . .It Fl T Cm locale Encode output using the current locale. This is the default. @@ -274,6 +236,12 @@ Produce format output. See .Sx Man Output . +.It Fl T Cm markdown +Produce output in +.Sy markdown +format. +See +.Sx Markdown Output . .It Fl T Cm pdf Produce PDF output. See @@ -290,9 +258,6 @@ See Encode output in the UTF\-8 multi-byte format. See .Sx UTF\-8 Output . -.It Fl T Cm xhtml -This is a synonym for -.Fl T Cm html . .El .Pp If multiple input files are specified, these will be processed by the @@ -377,7 +342,7 @@ The string for example, .Ar ../src/%I.html , is used as a template for linked header files (usually via the -.Sq \&In +.Ic \&In macro). Instances of .Sq \&%I @@ -390,7 +355,7 @@ The string for example, .Ar ../html%S/%N.%S.html , is used as a template for linked manuals (usually via the -.Sq \&Xr +.Ic \&Xr macro). Instances of .Sq \&%N @@ -436,13 +401,47 @@ If the input format is .Xr man 7 , the input is copied to the output, expanding any .Xr roff 7 -.Sq so +.Ic so requests. The parser is also run, and as usual, the .Fl W level controls which .Sx DIAGNOSTICS are displayed before copying the input to the output. +.Ss Markdown Output +Translate +.Xr mdoc 7 +input to the +.Sy markdown +format conforming to +.Lk http://daringfireball.net/projects/markdown/syntax.text\ + "John Gruber's 2004 specification" . +The output also almost conforms to the +.Lk http://commonmark.org/ CommonMark +specification. +.Pp +The character set used for the markdown output is ASCII. +Non-ASCII characters are encoded as HTML entities. +Since that is not possible in literal font contexts, because these +are rendered as code spans and code blocks in the markdown output, +non-ASCII characters are transliterated to ASCII approximations in +these contexts. +.Pp +Markdown is a very weak markup language, so all semantic markup is +lost, and even part of the presentational markup may be lost. +Do not use this as an intermediate step in converting to HTML; +instead, use +.Fl T Cm html +directly. +.Pp +The +.Xr man 7 , +.Xr tbl 7 , +and +.Xr eqn 7 +input languages are not supported by +.Fl T Cm markdown +output mode. .Ss PDF Output PDF-1.1 output may be generated by .Fl T Cm pdf . @@ -563,8 +562,16 @@ Meta data is not available in this case. .It Ev MANPAGER Any non-empty value of the environment variable .Ev MANPAGER -will be used instead of the standard pagination program, -.Xr more 1 . +is used instead of the standard pagination program, +.Xr more 1 ; +see +.Xr man 1 +for details. +Only used if +.Fl a +or +.Fl l +is specified. .It Ev PAGER Specifies the pagination program to use when .Ev MANPAGER @@ -572,7 +579,12 @@ is not defined. If neither PAGER nor MANPAGER is defined, .Xr more 1 .Fl s -will be used. +is used. +Only used if +.Fl a +or +.Fl l +is specified. .El .Sh EXIT STATUS The @@ -585,27 +597,32 @@ option: .Pp .Bl -tag -width Ds -compact .It 0 -No warnings or errors occurred, or those that did were ignored because -they were lower than the requested +No style suggestions, warnings or errors occurred, or those that +did were ignored because they were lower than the requested .Ar level . +.It 1 +At least one style suggestion occurred, but no warning or error, and +.Fl W Cm style +was specified. .It 2 At least one warning occurred, but no error, and .Fl W Cm warning +or +.Fl W Cm style was specified. .It 3 At least one parsing error occurred, but no unsupported feature was encountered, and .Fl W Cm error -or -.Fl W Cm warning -was specified. +or a lower +.Ar level +was requested. .It 4 At least one unsupported feature was encountered, and -.Fl W Cm unsupp , -.Fl W Cm error -or -.Fl W Cm warning -was specified. +.Fl W Cm unsupp +or a lower +.Ar level +was requested. .It 5 Invalid command line arguments were specified. No input files have been read. @@ -620,12 +637,11 @@ to exit at once, possibly in the middle of parsing or formatting a file. Note that selecting .Fl T Cm lint output mode implies -.Fl W Cm warning . +.Fl W Cm style . .Sh EXAMPLES To page manuals to the terminal: .Pp -.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less -.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less +.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 .Pp To produce HTML manuals with .Pa mandoc.css @@ -705,9 +721,22 @@ rendering can be produced. Documents causing warnings may render poorly when using other formatting tools instead of .Nm . +.It Cm style +An input file uses dubious or discouraged style. +This is not a complaint about the syntax, and probably neither +formatting nor portability are in danger. +While great care is taken to avoid false positives on the higher +message levels, the +.Cm style +level tries to reduce the probability that issues go unnoticed, +so it may occasionally issue bogus suggestions. +Please use your good judgement to decide whether any particular +.Cm style +suggestion really justifies a change to the input file. .El .Pp Messages of the +.Cm style , .Cm warning , .Cm error , and @@ -718,6 +747,58 @@ are hidden unless their level, or a lower level, is requested using a option or .Fl T Cm lint output mode. +.Ss Style messages +As indicated below, some style checks are only performed if a +specific operating system name occurs in the arguments of the +.Ic \&Os +macro, of the +.Fl Ios +command line option, or, if neither are present, in the return value +of the +.Xr uname 3 +function. +.Bl -ohang +.It Sy "useless macro" +.Pq mdoc +A +.Ic \&Bt , +.Ic \&Tn , +or +.Ic \&Ud +macro was found. +Simply delete it: it serves no useful purpose. +.It Sy "consider using OS macro" +.Pq mdoc +A string was found in plain text or in a +.Ic \&Bx +macro that could be represented using +.Ic \&Ox , +.Ic \&Nx , +.Ic \&Fx , +or +.Ic \&Dx . +.It Sy "errnos out of order" +.Pq mdoc, Nx +The +.Ic \&Er +items in a +.Ic \&Bl +list are not in alphabetical order. +.It Sy "duplicate errno" +.Pq mdoc, Nx +A +.Ic \&Bl +list contains two consecutive +.Ic \&It +entries describing the same +.Ic \&Er +number. +.It Sy "description line ends with a full stop" +.Pq mdoc +Do not use punctuation at the end of an +.Ic \&Nd +block. +.El .Ss Warnings related to the document prologue .Bl -ohang .It Sy "missing manual title, using UNTITLED" @@ -870,6 +951,14 @@ The .Ic \&Nd macro lacks the required argument. The title line of the manual will end after the dash. +.It Sy "description line outside NAME section" +.Pq mdoc +An +.Ic \&Nd +macro appears outside the NAME section. +The arguments are printed anyway and the following text is used for +.Xr apropos 1 , +but none of that behaviour is portable. .It Sy "sections out of conventional order" .Pq mdoc A standard section occurs after another section it usually precedes. @@ -1088,7 +1177,7 @@ or .Ic \&Bl .Fl offset or -.Fl width. +.Fl width . .It Sy "missing display type, using -ragged" .Pq mdoc The @@ -1310,6 +1399,12 @@ or .Ic \&Fn macro contains an opening or closing parenthesis; that's probably wrong, parentheses are added automatically. +.It Sy "unknown library name" +.Pq mdoc, not on Ox +An +.Ic \&Lb +macro has an unknown name argument and will be rendered as +.Qq library Dq Ar name . .It Sy "invalid content in Rs block" .Pq mdoc An @@ -1657,6 +1752,11 @@ whatever mode was active before the block. A .Ic \&Bl macro fails to specify the list type. +.It Sy "argument is not numeric, using 1" +.Pq roff +The argument of a +.Ic \&ce +request is not a number. .It Sy "missing manual name, using \(dq\(dq" .Pq mdoc The first call to |