diff options
| -rw-r--r-- | mandoc.1 | 37 | ||||
| -rw-r--r-- | manuals.7 | 40 | ||||
| -rw-r--r-- | mdoc.3 | 11 | ||||
| -rw-r--r-- | term.c | 6 |
4 files changed, 77 insertions, 17 deletions
@@ -118,14 +118,19 @@ and .El .\" PARAGRAPH .Pp -Note that reserved words may occur in streams of text, so the following: +Note that reserved words only register as such as if they appear as +standalone tokens, either in parsed lines or streams of text. Thus, the +following fragment: .Bd -literal -offset XXXX this self is not that of the waking , empirically real man .Ed .\" PARAGRAPH .Pp \&...correctly adjusts the comma spacing to -.Qq this self is not that of the waking , empirically real man . +.Dq this self is not that of the waking , empirically real man . +However, if the comma were part of +.Dq ,empirically , +it would not. .\" SUB-SECTION .Ss Output Formats The @@ -193,18 +198,28 @@ mode doesn't yet know how to display the following: The \-hang .Sq \&Bl list is not yet supported. +.El +.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. -.\" LIST-ITEM -.It -The -.Sq \&Bd -macro doesn't process \-compact . .El -.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. @@ -1,3 +1,21 @@ +.\" $Id$ +.\" +.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the +.\" above copyright notice and this permission notice appear in all +.\" copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL +.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE +.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER +.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" .Dd $Mdocdate$ .Dt manuals 7 .Os @@ -29,6 +47,8 @@ format or directory structure or device driver, it needs documentation. Prepare your composition environment by copying over the manual template from .Pa /usr/share/misc/mdoc.template . +.Pp +If this file doesn't exist, bug your administrator. .Em \&Do not start afresh or by copying another manual unless you know exactly what you're doing! @@ -144,6 +164,11 @@ to version-control your work. If you wish the last check-in to effect your document's date, use the following RCS tag for the date macro: .Pp .Dl \&.Dd $Mdocdate$ +.Pp +If using version control, the first line in your manual should be a +comment with the +.Li $Id$ +rcs tag. .\" SUBSECTION .Ss Viewing mdoc documents may be paged to your terminal with traditional @@ -182,6 +207,10 @@ output: \&.1.txt: mandoc -Tascii $< | col -b >$@ .Ed +.\" SUBSECTION +.Ss Licensing +Your manual must have a license. It should be listed at the start of +your document, just as in source code. .\" SECTION .Sh BEST PRACTICES The @@ -211,6 +240,17 @@ symbols and so on), use the escapes dictated in .Xr mdoc 7 . .El .\" SUBSECTION +.Ss Style +The structure of the mdoc language makes it very hard to have any +particular format style. Keep your lines under 72 characters in length. +If you must have long option lines, use +.Sq \&Oo/Oc . +.Em \&Do not +use +.Sq \&Xo/Xc ; +instead, either fine another way to write long lines, or, at the +absolute worst, use CPP-style newline escapes. +.\" SUBSECTION .Ss References Other components may be referenced with the .Sq \&Xr @@ -324,19 +324,22 @@ macro. .It The .Sq \&Bsx -macro doesn't yet understand version arguments. +macro family doesn't yet understand version arguments. .\" LIST-ITEM .It If not given a value, the \-offset argument to .Sq \&Bd and .Sq \&Bl -should by the width of -.Qq <string> . +should be the width of +.Qq <string> ; +instead, a value of +.Li 10n +is provided. .\" LIST-ITEM .It Columns widths in -.Sq \&Bl -column +.Sq \&Bl \-column should default to width .Qq <stringx> if not included. @@ -56,7 +56,8 @@ #define TTYPE_LINK_ANCHOR 19 #define TTYPE_LINK_TEXT 20 #define TTYPE_REF_JOURNAL 21 -#define TTYPE_NMAX 22 +#define TTYPE_LIST 22 +#define TTYPE_NMAX 23 /* * These define "styles" for element types, like command arguments or @@ -88,7 +89,8 @@ const int ttypes[TTYPE_NMAX] = { TERMP_BOLD, /* TTYPE_DIAG */ TERMP_UNDER, /* TTYPE_LINK_ANCHOR */ TERMP_BOLD, /* TTYPE_LINK_TEXT */ - TERMP_UNDER /* TTYPE_REF_JOURNAL */ + TERMP_UNDER, /* TTYPE_REF_JOURNAL */ + TERMP_BOLD /* TTYPE_LIST */ }; static int arg_hasattr(int, const struct mdoc_node *); |