From 9dc7df5a86cb463550e48720c3e7d2911ada3a33 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Sat, 2 Jan 2010 02:42:07 +0000 Subject: complete the sync to 1.9.15-pre2: mostly minor fixes * bugfix: do not restore TERMP flags when leaving lists, just reset them * and a few HTML fixes * clarity: return width from a2width, not width+2, and adapt to it * manual: document .Bl and .Fl * portability: no need to escape '%' in macro names --- usr.bin/mandoc/Makefile | 4 +- usr.bin/mandoc/mdoc.7 | 114 ++++++++++++++++++++++++++++++++++--- usr.bin/mandoc/mdoc.c | 15 +++-- usr.bin/mandoc/mdoc_html.c | 26 ++++++--- usr.bin/mandoc/mdoc_term.c | 138 ++++++++++++++++++++++++++++----------------- 5 files changed, 220 insertions(+), 77 deletions(-) (limited to 'usr.bin/mandoc') diff --git a/usr.bin/mandoc/Makefile b/usr.bin/mandoc/Makefile index 28338b2380e..011bd7c4454 100644 --- a/usr.bin/mandoc/Makefile +++ b/usr.bin/mandoc/Makefile @@ -1,8 +1,8 @@ -# $OpenBSD: Makefile,v 1.24 2009/12/24 02:08:14 schwarze Exp $ +# $OpenBSD: Makefile,v 1.25 2010/01/02 02:42:06 schwarze Exp $ .include -VERSION=1.9.14 +VERSION=1.9.15 CFLAGS+=-DVERSION=\"${VERSION}\" CFLAGS+=-W -Wall -Wstrict-prototypes .if ${USE_GCC3:L} != "no" diff --git a/usr.bin/mandoc/mdoc.7 b/usr.bin/mandoc/mdoc.7 index 80d2eac2019..0f3840f72a0 100644 --- a/usr.bin/mandoc/mdoc.7 +++ b/usr.bin/mandoc/mdoc.7 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.20 2009/12/24 02:08:14 schwarze Exp $ +.\" $Id: mdoc.7,v 1.21 2010/01/02 02:42:06 schwarze Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,7 +14,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: December 24 2009 $ +.Dd $Mdocdate: January 2 2010 $ .Dt MDOC 7 .Os . @@ -419,6 +419,11 @@ The macro(s) must precede the .Sx \&Nd macro. +.Pp +See +.Sx \&Nm +and +.Sx \&Nd . . .It Em LIBRARY The name of the library containing the documented material, which is @@ -429,8 +434,7 @@ this is as follows: .Ed .Pp See -.Sx \&Lb -for details. +.Sx \&Lb . . .It Em SYNOPSIS Documents the utility invocation syntax, function call syntax, or device @@ -467,6 +471,14 @@ And for the third, configurations (section 4): .Pp Manuals not in these sections generally don't need a .Em SYNOPSIS . +.Pp +See +.Sx \&Op , +.Sx \&Cd , +.Sx \&Fn , +.Sx \&Ft , +and +.Sx \&Vt . . .It Em DESCRIPTION This expands upon the brief, one-line description in @@ -480,6 +492,7 @@ The arguments are as follows: Print verbose information. \&.El .Ed +.Pp Manuals not documenting a command won't include the above fragment. . .It Em IMPLEMENTATION NOTES @@ -535,7 +548,8 @@ for manuals in sections 1, 6, and 8; however, this practise is discouraged. .Pp See -.Sx \&Bl No \-diag . +.Sx \&Bl +.Fl diag . . .It Em ERRORS Documents error handling in sections 2, 3, and 9. @@ -1160,7 +1174,60 @@ and .Ss \&Bf .Ss \&Bk .Ss \&Bl -. +.\" Begins a list composed of one or more list entries. A list entry is +.\" specified by the +.\" .Sx \&It +.\" macro, which consists of a head and optional body. By default, a list +.\" is preceded by a blank line. A list must specify one of the following +.\" list types: +.\" .Bl -tag -width 12n +.\" .It Fl bullet +.\" A list offset by a bullet. The head of list entries must be empty. +.\" List entry bodies are justified after the bullet. +.\" .It Fl column +.\" A columnated list. The number of columns is specified as arguments to +.\" the +.\" .Sx \&Bl +.\" macro (the deprecated form of following the invocation of +.\" .Fl column +.\" is also accepted). Arguments dictate the width of columns specified in +.\" list entries. List entry bodies must be left empty. Columns specified +.\" in the list entry head are justified to their position in the sequence +.\" of columns. +.\" .It Fl dash +.\" A list offset by a dash (hyphen). The head of list entries must be +.\" empty. List entry bodies are justified past the dash. +.\" .It Fl diag +.\" Like +.\" .Fl inset +.\" lists, but with additional formatting to the head. +.\" .It Fl enum +.\" A list offset by a number indicating list entry position. The head of +.\" list entries must be empty. List entry bodies are justified past the +.\" enumeration. +.\" .It Fl hang +.\" Like +.\" .Fl tag , +.\" but instead of list bodies justifying to the head on the first line, +.\" they trail the head text. +.\" .It Fl hyphen +.\" Synonym for +.\" .Fl dash . +.\" .It Fl inset +.\" Like +.\" .Fl tag , +.\" but list entry bodies aren't justified. +.\" .It Fl item +.\" An un-justified list. This produces blocks of text. +.\" .It Fl ohang +.\" List bodies are placed on the line following the head. +.\" .It Fl tag +.\" A list offset by list entry heads. List entry bodies are justified +.\" after the head. +.\" .El +.\" .Pp +.\" More... +.\" . .Ss \&Bo Begins a block enclosed by square brackets. Does not have any head arguments. @@ -1596,6 +1663,22 @@ is provided. .Ss \&Fc .Ss \&Fd .Ss \&Fl +Command-line flag. Used when listing arguments to command-line +utilities. Prints a fixed-width hyphen +.Sq \- +before each delimited argument. If no arguments are provided, a hyphen +is still printed. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl a b c +\&.Fl +\&.Op Fl o Ns Ar file +.Ed +.Pp +See also +.Sx \&Cm . +. .Ss \&Fn .Ss \&Fo .Ss \&Fr @@ -1830,6 +1913,23 @@ file re-write .Pp .Bl -dash -compact .It +The comment syntax +.Sq \e." +is no longer accepted. +.It +In +.Xr groff 1 , +the +.Sx \&Pa +macro does not format its arguments when used in the FILES section under +certain list types. This irregular behaviour has been discontinued. +.It +Historic +.Xr groff 1 +does not print a dash for empty +.Sx \&Fl +arguments. This behaviour has been discontinued. +.It .Xr groff 1 behaves strangely (even between versions) when specifying .Sq \ef @@ -1839,7 +1939,7 @@ normalised. Negative scaling units are now truncated to zero instead of creating interesting conditions, such as with .Sx \&sp -.Cm \-1i . +.Fl 1i . Furthermore, the .Sq f scaling unit, while accepted, is rendered as the default unit. diff --git a/usr.bin/mandoc/mdoc.c b/usr.bin/mandoc/mdoc.c index ae69cb2f05c..e8eeed72a37 100644 --- a/usr.bin/mandoc/mdoc.c +++ b/usr.bin/mandoc/mdoc.c @@ -1,4 +1,4 @@ -/* $Id: mdoc.c,v 1.32 2009/12/22 23:58:00 schwarze Exp $ */ +/* $Id: mdoc.c,v 1.33 2010/01/02 02:42:06 schwarze Exp $ */ /* * Copyright (c) 2008, 2009 Kristaps Dzonsons * @@ -93,11 +93,11 @@ const char *const __mdoc_macronames[MDOC_MAX] = { "Nm", "Op", "Ot", "Pa", "Rv", "St", "Va", "Vt", /* LINTED */ - "Xr", "\%A", "\%B", "\%D", + "Xr", "%A", "%B", "%D", /* LINTED */ - "\%I", "\%J", "\%N", "\%O", + "%I", "%J", "%N", "%O", /* LINTED */ - "\%P", "\%R", "\%T", "\%V", + "%P", "%R", "%T", "%V", "Ac", "Ao", "Aq", "At", "Bc", "Bf", "Bo", "Bq", "Bsx", "Bx", "Db", "Dc", @@ -114,11 +114,11 @@ const char *const __mdoc_macronames[MDOC_MAX] = { "Fr", "Ud", "Lb", "Lp", "Lk", "Mt", "Brq", "Bro", /* LINTED */ - "Brc", "\%C", "Es", "En", + "Brc", "%C", "Es", "En", /* LINTED */ - "Dx", "\%Q", "br", "sp", + "Dx", "%Q", "br", "sp", /* LINTED */ - "\%U" + "%U" }; const char *const __mdoc_argnames[MDOC_ARG_MAX] = { @@ -148,7 +148,6 @@ static int macrowarn(struct mdoc *, int, const char *); static int pstring(struct mdoc *, int, int, const char *, size_t); - const struct mdoc_node * mdoc_node(const struct mdoc *m) { diff --git a/usr.bin/mandoc/mdoc_html.c b/usr.bin/mandoc/mdoc_html.c index 24e549193bd..ca34fa46656 100644 --- a/usr.bin/mandoc/mdoc_html.c +++ b/usr.bin/mandoc/mdoc_html.c @@ -1,4 +1,4 @@ -/* $Id: mdoc_html.c,v 1.5 2009/12/24 02:08:14 schwarze Exp $ */ +/* $Id: mdoc_html.c,v 1.6 2010/01/02 02:42:06 schwarze Exp $ */ /* * Copyright (c) 2008, 2009 Kristaps Dzonsons * @@ -15,7 +15,6 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ #include -#include #include #include @@ -36,6 +35,10 @@ const struct mdoc_node *n, \ struct html *h +#ifndef MIN +#define MIN(a,b) ((/*CONSTCOND*/(a)<(b))?(a):(b)) +#endif + struct htmlmdoc { int (*pre)(MDOC_ARGS); void (*post)(MDOC_ARGS); @@ -656,10 +659,19 @@ mdoc_fl_pre(MDOC_ARGS) PAIR_CLASS_INIT(&tag, "flag"); print_otag(h, TAG_SPAN, 1, &tag); - if (MDOC_Fl == n->tok) { - print_text(h, "\\-"); + + /* `Cm' has no leading hyphen. */ + + if (MDOC_Cm == n->tok) + return(1); + + print_text(h, "\\-"); + + /* A blank `Fl' should incur a subsequent space. */ + + if (n->child) h->flags |= HTML_NOSPACE; - } + return(1); } @@ -1568,9 +1580,9 @@ mdoc_vt_pre(MDOC_ARGS) struct roffsu su; if (SEC_SYNOPSIS == n->sec) { - if (n->next && MDOC_Vt != n->next->tok) { + if (n->prev && MDOC_Vt != n->prev->tok) { SCALE_VS_INIT(&su, 1); - bufcat_su(h, "margin-bottom", &su); + bufcat_su(h, "margin-top", &su); PAIR_STYLE_INIT(&tag, h); print_otag(h, TAG_DIV, 1, &tag); } else diff --git a/usr.bin/mandoc/mdoc_term.c b/usr.bin/mandoc/mdoc_term.c index 9688fca09d3..b3e3f0116d1 100644 --- a/usr.bin/mandoc/mdoc_term.c +++ b/usr.bin/mandoc/mdoc_term.c @@ -1,4 +1,4 @@ -/* $Id: mdoc_term.c,v 1.67 2010/01/01 23:28:03 schwarze Exp $ */ +/* $Id: mdoc_term.c,v 1.68 2010/01/02 02:42:06 schwarze Exp $ */ /* * Copyright (c) 2008, 2009 Kristaps Dzonsons * @@ -33,7 +33,6 @@ struct termpair { struct termpair *ppair; - int flag; int count; }; @@ -466,12 +465,7 @@ a2width(const struct mdoc_argv *arg, int pos) if ( ! a2roffsu(arg->value[pos], &su, SCALE_MAX)) SCALE_HS_INIT(&su, strlen(arg->value[pos])); - /* - * This is a bit if a magic number on groff's part. Be careful - * in changing it, as the MDOC_Column handler will subtract one - * from this for >5 columns (don't go below zero!). - */ - return(term_hspan(&su) + 2); + return(term_hspan(&su)); } @@ -536,6 +530,10 @@ a2offs(const struct mdoc_argv *arg) } +/* + * Return 1 if an argument has a particular argument value or 0 if it + * does not. See arg_getattr(). + */ static int arg_hasattr(int arg, const struct mdoc_node *n) { @@ -544,6 +542,10 @@ arg_hasattr(int arg, const struct mdoc_node *n) } +/* + * Get the index of an argument in a node's argument list or -1 if it + * does not exist. See arg_getattrs(). + */ static int arg_getattr(int v, const struct mdoc_node *n) { @@ -553,6 +555,12 @@ arg_getattr(int v, const struct mdoc_node *n) } +/* + * Walk through the argument list for a node and fill an array "vals" + * with the positions of the argument structures listed in "keys". + * Return the number of elements that were written into "vals", which + * can be zero. + */ static int arg_getattrs(const int *keys, int *vals, size_t sz, const struct mdoc_node *n) @@ -572,6 +580,11 @@ arg_getattrs(const int *keys, int *vals, } +/* + * Determine how much space to print out before block elements of `It' + * (and thus `Bl') and `Bd'. And then go ahead and print that space, + * too. + */ static void print_bvspace(struct termp *p, const struct mdoc_node *bl, @@ -650,8 +663,7 @@ termp_it_pre(DECL_ARGS) const struct mdoc_node *bl, *nn; char buf[7]; int i, type, keys[3], vals[3]; - size_t width, offset, ncols; - int dcol; + size_t width, offset, ncols, dcol; if (MDOC_BLOCK == n->type) { print_bvspace(p, n->parent->parent, n); @@ -660,11 +672,7 @@ termp_it_pre(DECL_ARGS) bl = n->parent->parent->parent; - /* Save parent attributes. */ - - pair->flag = p->flags; - - /* Get list width and offset. */ + /* Get list width, offset, and list type from argument list. */ keys[0] = MDOC_Width; keys[1] = MDOC_Offset; @@ -672,55 +680,71 @@ termp_it_pre(DECL_ARGS) vals[0] = vals[1] = vals[2] = -1; - width = offset = 0; - - (void)arg_getattrs(keys, vals, 3, bl); + arg_getattrs(keys, vals, 3, bl); type = arg_listtype(bl); assert(-1 != type); + /* + * First calculate width and offset. This is pretty easy unless + * we're a -column list, in which case all prior columns must + * be accounted for. + */ + + width = offset = 0; + if (vals[1] >= 0) offset = a2offs(&bl->args->argv[vals[1]]); - /* Calculate real width and offset. */ - switch (type) { case (MDOC_Column): if (MDOC_BODY == n->type) break; - /* - * Imitate groff's column handling. - * For each earlier column, add its width. - * For less than 5 columns, add two more blanks per column. - * For exactly 5 columns, add only one more blank per column. - * For more than 5 columns, SUBTRACT one column. We can - * do this because a2width() pads exactly 2 spaces. + * Imitate groff's column handling: + * - For each earlier column, add its width. + * - For less than 5 columns, add four more blanks per + * column. + * - For exactly 5 columns, add three more blank per + * column. + * - For more than 5 columns, add only one column. */ ncols = bl->args->argv[vals[2]].sz; - dcol = ncols < 5 ? 2 : ncols == 5 ? 1 : -1; - for (i=0, nn=n->prev; nn && i < (int)ncols; nn=nn->prev, i++) - offset += a2width(&bl->args->argv[vals[2]], i) + - (size_t)dcol; + /* LINTED */ + dcol = ncols < 5 ? 4 : ncols == 5 ? 3 : 1; + + for (i = 0, nn = n->prev; + nn && i < (int)ncols; + nn = nn->prev, i++) + offset += dcol + a2width + (&bl->args->argv[vals[2]], i); + /* - * Use the declared column widths, - * extended as explained in the preceding paragraph. + * When exceeding the declared number of columns, leave + * the remaining widths at 0. This will later be + * adjusted to the default width of 10, or, for the last + * column, stretched to the right margin. */ - if (i < (int)ncols) - width = a2width(&bl->args->argv[vals[2]], i) + - (size_t)dcol; + if (i >= (int)ncols) + break; /* - * When exceeding the declared number of columns, - * leave the remaining widths at 0. - * This will later be adjusted to the default width of 10, - * or, for the last column, stretched to the right margin. + * Use the declared column widths, extended as explained + * in the preceding paragraph. */ + width = a2width(&bl->args->argv[vals[2]], i) + dcol; break; default: - if (vals[0] >= 0) - width = a2width(&bl->args->argv[vals[0]], 0); + if (vals[0] < 0) + break; + + /* + * Note: buffer the width by 2, which is groff's magic + * number for buffering single arguments. See the above + * handling for column for how this changes. + */ + width = a2width(&bl->args->argv[vals[0]], 0) + 2; break; } @@ -789,11 +813,10 @@ termp_it_pre(DECL_ARGS) } /* - * Pad and break control. This is the tricker part. Lists with - * set right-margins for the head get TERMP_NOBREAK because, if - * they overrun the margin, they wrap to the new margin. - * Correspondingly, the body for these types don't left-pad, as - * the head will pad out to to the right. + * Pad and break control. This is the tricky part. These flags + * are documented in term_flushln() in term.c. Note that we're + * going to unset all of these flags in termp_it_post() when we + * exit. */ switch (type) { @@ -934,7 +957,7 @@ termp_it_pre(DECL_ARGS) break; case (MDOC_Enum): (pair->ppair->ppair->count)++; - (void)snprintf(buf, sizeof(buf), "%d.", + snprintf(buf, sizeof(buf), "%d.", pair->ppair->ppair->count); term_word(p, buf); break; @@ -977,7 +1000,7 @@ termp_it_post(DECL_ARGS) { int type; - if (MDOC_BODY != n->type && MDOC_HEAD != n->type) + if (MDOC_BLOCK == n->type) return; type = arg_listtype(n->parent->parent->parent); @@ -1001,7 +1024,17 @@ termp_it_post(DECL_ARGS) break; } - p->flags = pair->flag; + /* + * Now that our output is flushed, we can reset our tags. Since + * only `It' sets these flags, we're free to assume that nobody + * has munged them in the meanwhile. + */ + + p->flags &= ~TERMP_DANGLE; + p->flags &= ~TERMP_NOBREAK; + p->flags &= ~TERMP_TWOSPACE; + p->flags &= ~TERMP_NOLPAD; + p->flags &= ~TERMP_HANG; } @@ -1982,10 +2015,9 @@ termp_sm_pre(DECL_ARGS) { assert(n->child && MDOC_TEXT == n->child->type); - if (0 == strcmp("on", n->child->string)) { + if (0 == strcmp("on", n->child->string)) p->flags &= ~TERMP_NONOSPACE; - p->flags &= ~TERMP_NOSPACE; - } else + else p->flags |= TERMP_NONOSPACE; return(0); -- cgit v1.2.3