-.\" $Id: mandoc.1,v 1.172 2017/01/28 23:30:08 schwarze Exp $
+.\" $Id: mandoc.1,v 1.188 2017/05/17 23:39:31 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: January 28 2017 $
+.Dd $Mdocdate: May 17 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
.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
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.
.It Fl K Ar encoding
Specify the input encoding.
.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.
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.
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
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
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
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
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
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
.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 .
.It
A full stop if the node ends a sentence.
.It
+BROKEN if the node is a block broken by another block.
+.It
NOSRC if the node is not in the input file,
but automatically generated from macros.
.It
for any output format.
.El
.El
+.Pp
+The following
+.Fl O
+argument is accepted:
+.Bl -tag -width Ds
+.It Cm noval
+Skip validation and show the unvalidated syntax tree.
+This can help to find out whether a given behaviour is caused by
+the parser or by the validator.
+Meta data is not available in this case.
+.El
.Sh ENVIRONMENT
.Bl -tag -width MANPAGER
.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
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
.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.
.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
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
.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.
.Ic \&Bl
.Fl offset
or
-.Fl width.
+.Fl width .
.It Sy "missing display type, using -ragged"
.Pq mdoc
The
.Xr mdoc 7 ,
.Xr roff 7 ,
.Xr tbl 7
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Ox 4.8 .
+The option
+.Fl I
+appeared in
+.Ox 5.2 ,
+and
+.Fl aCcfhKklMSsw
+in
+.Ox 5.7 .
.Sh AUTHORS
.An -nosplit
The
git.ckatri.com / mandoc.git / blobdiff