-.\" $Id: mandoc.1,v 1.16 2009/04/12 19:45:26 kristaps Exp $
+.\" $Id: mandoc.1,v 1.22 2009/06/22 12:04:05 kristaps Exp $
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: April 12 2009 $
+.Dd $Mdocdate: June 22 2009 $
.Dt MANDOC 1
.Os
.\" SECTION
utility formats
.Ux
manual pages for display. The arguments are as follows:
-.Bl -tag -width XXXXXXXXXXXX
+.Bl -tag -width Ds
.\" ITEM
.It Fl f Ns Ar option...
Override default compiler behaviour. See
.Sx Compiler Options
for details.
.\" ITEM
-.It Fl m
+.It Fl m Ns Ar format
Input format. See
.Sx Input Formats
for available formats. Defaults to
.Fl m Ns Ar andoc .
.\" ITEM
-.It Fl T
+.It Fl T Ns Ar output
Output format. See
.Sx Output Formats
for available formats. Defaults to
.Pp
.Ex -std mandoc
.\" SUB-SECTION
-.Ss Punctuation
+.Ss Punctuation and Spacing
If punctuation is set apart from words, such as in the phrase
.Dq to be \&, or not to be ,
it's processed by
.Nm
-according to the following rules. Opening punctuation
+according to the following rules: opening punctuation
.Po
.Sq \&( ,
.Sq \&[ ,
and
.Sq \&{
.Pc
-is not followed by a space. Closing punctuation
+is not followed by a space; closing punctuation
.Po
.Sq \&. ,
.Sq \&, ,
If the input is
.Xr mdoc 7 ,
these rules are also applied to macro arguments when appropriate.
+.Pp
+White-space, in non-literal (normal) mode, is stripped from input and
+replaced on output by a single space. Thus, if you wish to preserve
+multiple spaces, they must be space-escaped
+.Sq \e\ .
+or used in a literal display mode, e.g.,
+.Sq \&.Bd \-literal
+in
+.Xr mdoc 7 .
.\" SUB-SECTION
.Ss Input Formats
The
utility accepts the following
.Fl T
arguments:
-.Bl -tag -width XXXXXXXXXXXX
+.Bl -tag -width Ds
.It Fl T Ns Ar ascii
Produce 7-bit ASCII output, backspace-encoded for bold and underline
styles. This is the default.
Default compiler behaviour may be overriden with the
.Fl f
flag.
-.Bl -tag -width XXXXXXXXXXXXXX
+.Bl -tag -width Ds
.It Fl f Ns Ar ign-scope
When rewinding the scope of a block macro, forces the compiler to ignore
scope violations. This can seriously mangle the resulting tree.
.Pq mdoc only
-.It Fl f Ns Ar ign-escape
-Ignore invalid escape sequences.
-.It Fl f Ns Ar ign-macro
-Ignore unknown macros at the start of input lines (default for
-.Xr man 7
-parsing).
+.It Fl f Ns Ar no-ign-escape
+Don't ignore invalid escape sequences.
.It Fl f Ns Ar no-ign-macro
-Do not ignore unknown macros at the start of input lines (default for
-.Xr mdoc 7
-parsing).
+Do not ignore unknown macros at the start of input lines.
+.It Fl f Ns Ar no-ign-chars
+Do not ignore disallowed characters.
+.It Fl f Ns Ar strict
+Implies
+.Fl f Ns Ar no-ign-escape ,
+.Fl f Ns Ar no-ign-macro
+and
+.Fl f Ns Ar no-ign-chars .
.El
.\" PARAGRAPH
.Pp
flag, multiple
.Fl f
options may be grouped and delimited with a comma. Using
-.Fl f Ns Ar ign-scope,ign-escape ,
-for example, will try to ignore scope and character-escape errors.
+.Fl f Ns Ar ign-scope,no-ign-escape ,
+for example, will try to ignore scope and not ignore character-escape
+errors.
.\" SECTION
.Sh EXAMPLES
To page manuals to the terminal:
.\" PARAGRAPH
.Pp
-.D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
-.Pp
+.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
.\" SECTION
+.Sh COMPATIBILITY
+This section summarises
+.Nm
+compatibility with
+.Xr groff 1 .
+.Pp
+.Bl -bullet -compact
+.It
+A list or display following
+.Sq \&.Ss
+does not assert a prior vertical break, just as it doesn't with
+.Sq \&.Sh .
+.It
+The \-literal and \-unfilled
+.Sq \&.Bd
+displays types are synonyms, as are \-filled and \-ragged.
+.It
+Words aren't hyphenated.
+.It
+In normal mode (not a literal block), blocks of spaces aren't preserved,
+so double spaces following sentence closure
+.Pq Qq French spacing
+are reduced to a single space.
+.El
+.\" SECTION
.Sh SEE ALSO
.Xr mandoc_char 7 ,
.Xr mdoc 7 ,
.Xr man 7
-.\"
+.\" SECTION
.Sh AUTHORS
The
.Nm
utility was written by
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
+.An Kristaps Dzonsons Aq kristaps@kth.se .
.\" SECTION
.Sh CAVEATS
The
.Nm
-utility in
-.Fl T Ns Ar ascii
-mode doesn't yet know how to display the following:
-.Pp
-.Bl -bullet -compact
-.It
-The \-hang
-.Sq \&.Bl
-list is not yet supported.
-.El
+utility doesn't yet know how to display \-hang lists.
.Pp
Other macros still aren't supported by virtue of nobody complaining
-about their absence. Please report any omissions: this is a work in
-progress.
-.Pp
-The following list documents differences between traditional
-.Xr nroff 1
-output and
-.Nm :
-.Pp
-.Bl -bullet -compact
-.It
-A list of display following
-.Sq \&.Ss
-does not assert a prior vertical break, just as it doesn't with
-.Sq \&.Sh .
-.It
-Special characters don't follow the current font style.
-.\" LIST-ITEM
-.It
-The \-literal and \-unfilled
-.Sq \&.Bd
-displays types are synonyms, as are \-filled and \-ragged.
-.El
+about their absence.
git.ckatri.com / mandoc.git / blobdiff