=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.215 retrieving revision 1.222 diff -u -p -r1.215 -r1.222 --- mandoc/mandoc.1 2017/07/06 22:59:48 1.215 +++ mandoc/mandoc.1 2018/03/16 15:05:44 1.222 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.215 2017/07/06 22:59:48 schwarze Exp $ +.\" $Id: mandoc.1,v 1.222 2018/03/16 15:05:44 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze +.\" 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: July 6 2017 $ +.Dd $Mdocdate: March 16 2018 $ .Dt MANDOC 1 .Os .Sh NAME @@ -118,7 +118,7 @@ With 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 +if the first macro is .Ic \&Dd or .Ic \&Dt , @@ -238,7 +238,9 @@ See .It Fl T Cm lint Parse only: produce no output. Implies -.Fl W Cm all . +.Fl W Cm all +and redirects parser messages, which usually appear +on standard error output, to standard output. .It Fl T Cm locale Encode output using the current locale. This is the default. @@ -313,6 +315,20 @@ and seven for .Xr man 7 . Increasing this is not recommended; it may result in degraded formatting, for example overfull lines or ugly line breaks. +.It Cm mdoc +Format +.Xr man 7 +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 +.Fl O Cm indent Ns =5 . +One useful application is for checking that +.Fl T Cm man +output formats in the same way as the +.Xr mdoc 7 +source it was generated from. .It Cm width Ns = Ns Ar width The output width is set to .Ar width . @@ -719,32 +735,13 @@ so using GNU troff instead of .Nm to process the file may be preferable. .It Cm error -An input file contains invalid syntax that cannot be safely interpreted. -By discarding part of the input or inserting missing tokens, -the parser is able to continue, and the error does not prevent -generation of formatted output, but typically, preparing that -output involves information loss, broken document structure -or unintended formatting, no matter whether -.Nm -or GNU troff is used. -In many cases, the output of -.Nm -and GNU troff is identical, but in some, -.Nm -is more resilient than GNU troff with respect to malformed input. -.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. +Indicates a risk of information loss or severe misformatting, +in most cases caused by serious syntax errors. .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 -rendering can be produced. -Documents causing warnings may render poorly when using other -formatting tools instead of -.Nm . +Indicates a risk that the information shown or its formatting +may mismatch the author's intent in minor ways. +Additionally, syntax errors are classified at least as warnings, +even if they do not usually cause misformatting. .It Cm style An input file uses dubious or discouraged style. This is not a complaint about the syntax, and probably neither @@ -758,7 +755,7 @@ Please use your good judgement to decide whether any p .Cm style suggestion really justifies a change to the input file. .It Cm base -A convertion used in the base system of a specific operating system +A convention used in the base system of a specific operating system is not adhered to. These are not markup mistakes, and neither the quality of formatting nor portability are in danger. @@ -878,7 +875,7 @@ A single manual page contains two copies of the RCS id the same operating system. Consider deleting the later instance and moving the first one up to the top of the page. -.It Sy "typo in section name" +.It Sy "possible typo in section name" .Pq mdoc Fuzzy string matching revealed that the argument of an .Ic \&Sh @@ -955,6 +952,12 @@ 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 "verbatim \(dq--\(dq, maybe consider using \e(em" +.Pq mdoc +Even though the ASCII output device renders an em-dash as +.Qq \-\- , +that is not a good way to write it in an input file +because it renders poorly on all other output devices. .It Sy "function name without markup" .Pq mdoc A word followed by an empty pair of parentheses occurs on a text line.