mdoc.samples.7

早期freebsd实现

Literal mode is
asserted and tabs are set at 8 constant width character
intervals, however any
.Xr troff/ Ns Nm \-mdoc
commands in file will be processed.
.It Fl offset Ar string
If
.Fl offset
is specified with one of the following strings, the string
is interpreted to indicate the level of indentation for the
forthcoming block of text:
.Pp
.Bl -tag -width "indent-two" -compact
.It Ar left
Align block on the current left margin,
this is the default mode of
.Ql \&.Bd .
.It Ar center
Supposedly center the block.
At this time
unfortunately, the block merely gets
left aligned about an imaginary center margin.
.It Ar indent
Indents by one default indent value or tab.
The default
indent value is also used for the
.Ql \&.D1
display so one is guaranteed the two types of displays
will line up.
This indent is normally set to 6n or about two
thirds of an inch (six constant width characters).
.It Ar indent-two
Indents two times the default indent value.
.It Ar right
This
.Em left
aligns the block about two inches from
the right side of the page.
This macro needs
work and perhaps may never do the right thing by
.Xr troff .
.El
.El
.It ".Ed"
End-display.
.El
.Ss Tagged Lists and Columns
There are several types of lists which may be initiated with the
.Ql ".Bl"
begin-list macro.
Items within the list
are specified with the
.Ql ".It"
item macro and
each list must end with the
.Ql ".El"
macro.
Lists may be nested within themselves and within displays.
Columns may be used inside of lists, but lists are unproven
inside of columns.
.Pp
In addition, several list attributes may be specified such as
the width of a tag, the list offset, and compactness
(blank lines between items allowed or disallowed).
Most of this document has been formatted with a tag style list
.Pq Fl tag .
For a change of pace, the list-type used to present the list-types
is an over-hanging list
.Pq Fl ohang .
This type of list is quite popular with
.Tn TeX
users, but might look a bit funny after having read many pages of
tagged lists.
The following list types are accepted by
.Ql ".Bl" :
.Pp
.Bl -ohang -compact
.It Fl bullet
.It Fl item
.It Fl enum
These three are the simplest types of lists.
Once the
.Ql ".Bl"
macro has been given, items in the list are merely
indicated by a line consisting solely of the
.Ql ".It"
macro.
For example, the source text for a simple enumerated list
would look like:
.Bd -literal -offset indent-two
\&.Bl -enum -compact
\&.It
\&Item one goes here.
\&.It
\&And item two here.
\&.It
\&Lastly item three goes here.
\&.El
.Ed
.Pp
The results:
.Pp
.Bl -enum -offset indent-two -compact
.It
Item one goes here.
.It
And item two here.
.It
Lastly item three goes here.
.El
.Pp
A simple bullet list construction:
.Bd -literal -offset indent-two
\&.Bl -bullet -compact
\&.It
\&Bullet one goes here.
\&.It
\&Bullet two here.
\&.El
.Ed
.Pp
Produces:
.Bl -bullet -offset indent-two -compact
.It
Bullet one goes here.
.It
Bullet two here.
.El
.Pp
.It Fl tag
.It Fl diag
.It Fl hang
.It Fl ohang
.It Fl inset
These list-types collect arguments specified with the
.Ql \&.It
macro and create a label which may be
.Em inset
into the forthcoming text,
.Em hanged
from the forthcoming text,
.Em overhanged
from above and not indented or
.Em tagged .
This
list was constructed with the
.Ql Fl ohang
list-type.
The
.Ql \&.It
macro is parsed only for the inset, hang
and tag list-types and is not callable.
Here is an example of inset labels:
.Bl -inset -offset indent
.It Em Tag
The tagged list (also called a tagged paragraph) is the
most common type of list used in the Berkeley manuals.
.It Em Diag
Diag lists create section four diagnostic lists
and are similar to inset lists except callable
macros are ignored.
.It Em Hang
Hanged labels are a matter of taste.
.It Em Ohang
Overhanging labels are nice when space is constrained.
.It Em Inset
Inset labels are useful for controlling blocks of
paragraphs and are valuable for converting
.Nm \-mdoc
manuals to other formats.
.El
.Pp
Here is the source text which produced the above example:
.Bd -literal -offset indent
\&.Bl -inset -offset indent
\&.It Em Tag
\&The tagged list (also called a tagged paragraph) is the
\&most common type of list used in the Berkeley manuals.
\&.It Em Diag
\&Diag lists create section four diagnostic lists
\&and are similar to inset lists except callable
\&macros are ignored.
\&.It Em Hang
\&Hanged labels are a matter of taste.
\&.It Em Ohang
\&Overhanging labels are nice when space is constrained.
\&.It Em Inset
\&Inset labels are useful for controlling blocks of
\&paragraphs and are valuable for converting
\&.Nm \-mdoc
\&manuals to other formats.
\&.El
.Ed
.Pp
Here is a hanged list with just one item:
.Bl -hang -offset indent
.It Em Hanged
labels appear similar to tagged lists when the
label is smaller than the label width.
.It Em Longer hanged list labels
blend in to the paragraph unlike
tagged paragraph labels.
.El
.Pp
And the unformatted text which created it:
.Bd -literal -offset indent
\&.Bl -hang -offset indent
\&.It Em Hanged
\&labels appear similar to tagged lists when the
\&label is smaller than the label width.
\&.It Em Longer hanged list labels
\&blend in to the paragraph unlike
\&tagged paragraph labels.
\&.El
.Ed
.Pp
The tagged list which follows uses an optional width specifier to control
the width of the tag.
.Pp
.Bl -tag -width "PAGEIN" -compact -offset indent
.It SL
sleep time of the process (seconds blocked)
.It PAGEIN
number of disk
.Tn I/O Ns 's
resulting from references
by the process to pages not loaded in core.
.It UID
numerical user-id of process owner
.It PPID
numerical id of parent of process process priority
(non-positive when in non-interruptible wait)
.El
.Pp
The raw text:
.Bd -literal -offset indent
\&.Bl -tag -width "PAGEIN" -compact -offset indent
\&.It SL
\&sleep time of the process (seconds blocked)
\&.It PAGEIN
\&number of disk
\&.Tn I/O Ns 's
\&resulting from references
\&by the process to pages not loaded in core.
\&.It UID
\&numerical user-id of process owner
\&.It PPID
\&numerical id of parent of process process priority
\&(non-positive when in non-interruptible wait)
\&.El
.Ed
.Pp
Acceptable width specifiers:
.Bl -tag -width Ar -offset indent
.It Fl width Ar "\&Fl"
sets the width to the default width for a flag.
All callable
macros have a default width value.
The
.Ql \&.Fl ,
value is presently
set to ten constant width characters or about five sixth of
an inch.
.It Fl width Ar "24n"
sets the width to 24 constant width characters or about two
inches.
The
.Ql n
is absolutely necessary for the scaling to work correctly.
.It Fl width Ar "ENAMETOOLONG"
sets width to the constant width length of the
string given.
.It Fl width  Ar "\\*qint mkfifo\\*q"
again, the width is set to the constant width of the string
given.
.El
.Pp
If a width is not specified for the tag list type, the first
time
.Ql \&.It
is invoked, an attempt is made to determine an appropriate
width.
If the first argument to
.Ql ".It"
is a callable macro, the default width for that macro will be used
as if the macro name had been supplied as the width.
However,
if another item in the list is given with a different callable
macro name, a new and nested list is assumed.
.Sh PREDEFINED STRINGS
The following strings are predefined as may be used by
preceding with the troff string interpreting sequence
.Ql \&\e*(xx
where
.Em xx
is the name of the defined string or as
.Ql \&\e*x
where
.Em x
is the name of the string.
The interpreting sequence may be used any where in the text.
.Pp
.Bl -column "String " "Nroff " "Troff " -offset indent
.It Sy "String	Nroff	Troff"
.It Li "<=" Ta \&<\&= Ta \*(<=
.It Li ">=" Ta \&>\&= Ta \*(>=
.It Li "Rq" Ta "''" Ta \*(Rq
.It Li "Lq" Ta "``" Ta \*(Lq
.It Li "ua" Ta ^ Ta \*(ua
.It Li "aa" Ta ' Ta \*(aa
.It Li "ga" Ta \` Ta \*(ga
.\" .It Li "sL" Ta ` Ta \*(sL
.\" .It Li "sR" Ta ' Ta \*(sR
.It Li "q" Ta \&" Ta \*q
.It Li "Pi" Ta pi Ta \*(Pi
.It Li "Ne" Ta != Ta \*(Ne
.It Li "Le" Ta <= Ta \*(Le
.It Li "Ge" Ta >= Ta \*(Ge
.It Li "Lt" Ta < Ta \*(Gt
.It Li "Gt" Ta > Ta \*(Lt
.It Li "Pm" Ta +- Ta \*(Pm
.It Li "If" Ta infinity Ta \*(If
.It Li "Na" Ta \fINaN\fP Ta \*(Na
.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba
.El
.Pp
.Sy Note :
The string named
.Ql q
should be written as
.Ql \e*q
since it is only one char.
.Sh DIAGNOSTICS
The debugging facilities for
.Nm \-mdoc
are limited, but can help detect subtle errors such
as the collision of an argument name with an internal
register or macro name.
(A what?)
A register is an arithmetic storage class for
.Xr troff
with a one or two character name.
All registers internal to
.Nm \-mdoc
for
.Xr troff
and
.Xr ditroff
are two characters and
of the form <upper_case><lower_case> such as
.Ql \&Ar ,
<lower_case><upper_case> as
.Ql \&aR
or
<upper or lower letter><digit> as
.Ql \&C\&1 .
And adding to the muddle,
.Xr troff
has its own internal registers all of which are either
two lower case characters or a dot plus a letter or meta-character
character.
In one of the introduction examples, it was shown how to
prevent the interpretation of a macro name with the escape sequence
.Ql \e& .
This is sufficient for the internal register names also.
.Pp
.\" Every callable macro name has a corresponding register
.\" of the same name (<upper_case><lower_case>).
.\" There are also specific registers which have
.\" been used for stacks and arrays and are listed in the
.\" .Sx Appendix .
.\" .Bd -ragged -offset 4n
.\" [A-Z][a-z]	registers corresponding to macro names (example ``Ar'')
.\" [a-z][A-Z]	registers corresponding to macro names (example ``aR'')
.\" C[0-9]		argument types (example C1)
.\" O[0-9]		offset stack (displays)
.\" h[0-9]		horizontal spacing stack (lists)
.\" o[0-9]		offset (stack) (lists)
.\" t[0-9]		tag stack (lists)
.\" v[0-9]		vertical spacing stack (lists)
.\" w[0-9]		width tag/label stack
.\" .Ed
.\" .Pp
If a non-escaped register name is given in the argument list of a request
unpredictable behavior will occur.
In general, any time huge portions
of text do not appear where expected in the output, or small strings
such as list tags disappear, chances are there is a misunderstanding
about an argument type in the argument list.
Your mother never intended for you to remember this evil stuff - so here
is a way to find out whether or not your arguments are valid: The
.Ql \&.Db
(debug)
macro displays the interpretation of the argument list for most
macros.
Macros such as the
.Ql \&.Pp
(paragraph)
macro do not contain debugging information.
All of the callable macros do,
and it is strongly advised whenever in doubt,
turn on the
.Ql \&.Db
macro.
.Pp
.Dl Usage: \&.Db [on | off]
.Pp
An example of a portion of text with
the debug macro placed above and below an
artificially created problem (a flag argument
.Ql \&aC
which should be
.Ql \e&aC
in order to work):
.Bd -literal -offset indent
\&.Db on
\&.Op Fl aC Ar file )
\&.Db off
.Ed
.Pp
The resulting output:
.Bd -literal -offset indent
DEBUGGING ON
DEBUG(argv) MACRO: `.Op'  Line #: 2
	Argc: 1  Argv: `Fl'  Length: 2
	Space: `'  Class: Executable
	Argc: 2  Argv: `aC'  Length: 2
	Space: `'  Class: Executable
	Argc: 3  Argv: `Ar'  Length: 2
	Space: `'  Class: Executable
	Argc: 4  Argv: `file'  Length: 4
	Space: ` '  Class: String
	Argc: 5  Argv: `)'  Length: 1
	Space: ` '  Class: Closing Punctuation or suffix
	MACRO REQUEST: .Op Fl aC Ar file )
DEBUGGING OFF
.Ed
.Pp
The first line of information tells the name of the calling
macro, here
.Ql \&.Op ,
and the line number it appears on.
If one or more files are involved
(especially if text from another file is included) the line number
may be bogus.
If there is only one file, it should be accurate.
The second line gives the argument count, the argument
.Pq Ql \&Fl
and its length.
If the length of an argument is two characters, the
argument is tested to see if it is executable (unfortunately, any
register which contains a non-zero value appears executable).
The third line gives the space allotted for a class, and the
class type.
The problem here is the argument aC should not be
executable.
The four types of classes are string, executable, closing
punctuation and opening punctuation.
The last line shows the entire
argument list as it was read.
In this next example, the offending
.Ql \&aC
is escaped:
.Bd -literal -offset indent
\&.Db on
\&.Em An escaped \e&aC
\&.Db off
.Ed
.Bd -literal -offset indent
DEBUGGING ON
DEBUG(fargv) MACRO: `.Em'  Line #: 2
	Argc: 1  Argv: `An'  Length: 2
	Space: ` '  Class: String
	Argc: 2  Argv: `escaped'  Length: 7
	Space: ` '  Class: String
	Argc: 3  Argv: `aC'  Length: 2
	Space: ` '  Class: String
	MACRO REQUEST: .Em An escaped &aC
DEBUGGING OFF
.Ed
.Pp
The argument
.Ql \e&aC
shows up with the same length of 2 as the
.Ql \e&
sequence produces a zero width, but a register
named
.Ql \e&aC
was not found and the type classified as string.
.Pp
Other diagnostics consist of usage statements and are self explanatory.
.Sh GROFF, TROFF AND NROFF
The
.Nm \-mdoc
package does not need compatibility mode with
.Xr groff .
.Pp
The package inhibits page breaks, and the headers and footers
which normally occur at those breaks with
.Xr nroff ,
to make the manual more efficient for viewing on-line.
At the moment,
.Xr groff
with
.Fl T Ns Ar ascii
does eject the imaginary remainder of the page at end of file.
The inhibiting of the page breaks makes
.Xr nroff Ns 'd
files unsuitable for hardcopy.
There is a register named
.Ql \&cR
which can be set to zero in the site dependent style file
.Pa /usr/src/share/tmac/doc-nroff
to restore the old style behavior.
.Sh FILES
.Bl -tag -width /usr/share/man0/template.doc -compact
.It Pa /usr/share/tmac/tmac.doc
manual macro package
.It Pa /usr/share/man0/template.doc
template for writing a man page
.El
.Sh SEE ALSO
.Xr mdoc 7 ,
.Xr man 1 ,
.Xr troff 1
.Sh BUGS
Undesirable hyphenation on the dash of a flag
argument is not yet resolved, and causes
occasional mishaps in the
.Sx DESCRIPTION
section.
(line break on the hyphen).
.Pp
Predefined strings are not declared in documentation.
.Pp
Section 3f has not been added to the header routines.
.Pp
.Ql \&.Nm
font should be changed in
.Sx NAME
section.
.Pp
.Ql \&.Fn
needs to have a check to prevent splitting up
if the line length is too short.
Occasionally it
separates the last parenthesis, and sometimes
looks ridiculous if a line is in fill mode.
.Pp
The method used to prevent header and footer page
breaks (other than the initial header and footer) when using
nroff occasionally places an unsightly partially filled line (blank)
at the would be bottom of the page.
.Pp
The list and display macros to not do any keeps
and certainly should be able to.
.\" Note what happens if the parameter list overlaps a newline