From ca91d8f3ace59249bb9ba5e96567d230e6a0afde Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Mon, 23 Mar 2009 09:42:43 +0000 Subject: More manual documentation fixed/improved. --- mandoc.1 | 41 ++++++++++++++++++++++++++++------------- manuals.7 | 44 ++++++++++++++++++++++++++++++++++++++++++-- mdoc.3 | 15 +++++++++------ term.c | 8 +++++--- 4 files changed, 84 insertions(+), 24 deletions(-) diff --git a/mandoc.1 b/mandoc.1 index 40bffea7..8cc56b2b 100644 --- a/mandoc.1 +++ b/mandoc.1 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.6 2009/03/22 19:08:53 kristaps Exp $ +.\" $Id: mandoc.1,v 1.7 2009/03/23 09:42:43 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 22 2009 $ +.Dd $Mdocdate: March 23 2009 $ .Dt mandoc 1 .Os .\" SECTION @@ -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. diff --git a/manuals.7 b/manuals.7 index 318441ec..348772c4 100644 --- a/manuals.7 +++ b/manuals.7 @@ -1,4 +1,22 @@ -.Dd $Mdocdate: March 22 2009 $ +.\" $Id: manuals.7,v 1.8 2009/03/23 09:42:43 kristaps Exp $ +.\" +.\" Copyright (c) 2009 Kristaps Dzonsons +.\" +.\" 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: March 23 2009 $ .Dt manuals 7 .Os .\" SECTION @@ -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! @@ -143,7 +163,12 @@ or, if not available, 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: March 22 2009 $ +.Dl \&.Dd $Mdocdate: March 23 2009 $ +.Pp +If using version control, the first line in your manual should be a +comment with the +.Li $Id: manuals.7,v 1.8 2009/03/23 09:42:43 kristaps Exp $ +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 diff --git a/mdoc.3 b/mdoc.3 index 959cca97..31e86791 100644 --- a/mdoc.3 +++ b/mdoc.3 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.3,v 1.22 2009/03/22 08:52:27 kristaps Exp $ +.\" $Id: mdoc.3,v 1.23 2009/03/23 09:42:43 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 22 2009 $ +.Dd $Mdocdate: March 23 2009 $ .Dt mdoc 3 .Os .\" SECTION @@ -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 . +should be the width of +.Qq ; +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 if not included. diff --git a/term.c b/term.c index a5ea91af..76cc437b 100644 --- a/term.c +++ b/term.c @@ -1,4 +1,4 @@ -/* $Id: term.c,v 1.68 2009/03/22 21:19:34 kristaps Exp $ */ +/* $Id: term.c,v 1.69 2009/03/23 09:42:43 kristaps Exp $ */ /* * Copyright (c) 2008, 2009 Kristaps Dzonsons * @@ -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 *); -- cgit v1.2.3-56-ge451