Improve .Nm indentation in the SYNOPSIS;

kristaps@ will do the missing HTML part soon.
"looks nicer" jmc@
"seems perfect to me" sobrado@
"slap it in" kristaps@

diff --git a/main.c b/main.c
index c9905f0b5cd67028cdd220fcbf123cbda13f7322..2f5ff8dd58bf04b40c0660b0a4a57f429a8364cd 100644 (file)
--- a/main.c
+++ b/main.c
@@ -1,4 +1,4 @@
-/*     $Id: main.c,v 1.94 2010/06/30 20:32:15 schwarze Exp $ */
+/*     $Id: main.c,v 1.95 2010/07/01 15:38:56 schwarze Exp $ */

 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  *
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  *


@@ -120,6 +120,7 @@ static      const char * const      mandocerrs[MANDOCERR_MAX] = {
        "unknown manual section",
        "section not in conventional manual section",
        "end of line whitespace",
        "unknown manual section",
        "section not in conventional manual section",
        "end of line whitespace",

+       "blocks badly nested",

        "scope open on exit",
 
        "generic error",
        "scope open on exit",
 
        "generic error",


@@ -143,7 +144,6 @@ static      const char * const      mandocerrs[MANDOCERR_MAX] = {
        "bad comment style",
        "unknown macro will be lost",
        "line scope broken",
        "bad comment style",
        "unknown macro will be lost",
        "line scope broken",

-       "scope broken",

        "argument count wrong",
        "request scope close w/none open",
        "scope already open",
        "argument count wrong",
        "request scope close w/none open",
        "scope already open",


@@ -162,7 +162,8 @@ static      const char * const      mandocerrs[MANDOCERR_MAX] = {
        "missing font type",
        "displays may not be nested",
        "unsupported display type",
        "missing font type",
        "displays may not be nested",
        "unsupported display type",

-       "no scope to rewind: syntax violated",
+       "blocks badly nested",
+       "no such block is open",

        "scope broken, syntax violated",
        "line scope broken, syntax violated",
        "argument count wrong, violates syntax",
        "scope broken, syntax violated",
        "line scope broken, syntax violated",
        "argument count wrong, violates syntax",

diff --git a/mandoc.h b/mandoc.h
index 121e9d8d868d091144d35d1ceda1ad87c0b6a3a9..948fb078955d93c8451512c6cc6b2e38d0564553 100644 (file)
--- a/mandoc.h
+++ b/mandoc.h
@@ -1,4 +1,4 @@
-/*     $Id: mandoc.h,v 1.13 2010/06/30 20:32:15 schwarze Exp $ */
+/*     $Id: mandoc.h,v 1.14 2010/07/01 15:38:56 schwarze Exp $ */

 /*
  * Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
  *
 /*
  * Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
  *


@@ -47,6 +47,7 @@ enum  mandocerr {
        MANDOCERR_BADMSEC, /* unknown manual section */
        MANDOCERR_SECMSEC, /* section not in conventional manual section */
        MANDOCERR_EOLNSPACE, /* end of line whitespace */
        MANDOCERR_BADMSEC, /* unknown manual section */
        MANDOCERR_SECMSEC, /* section not in conventional manual section */
        MANDOCERR_EOLNSPACE, /* end of line whitespace */

+       MANDOCERR_SCOPENEST, /* blocks badly nested */

        MANDOCERR_SCOPEEXIT, /* scope open on exit */
 
        MANDOCERR_ERROR, /* ===== end of errors ===== */
        MANDOCERR_SCOPEEXIT, /* scope open on exit */
 
        MANDOCERR_ERROR, /* ===== end of errors ===== */


@@ -70,9 +71,8 @@ enum  mandocerr {
        MANDOCERR_BADCOMMENT, /* bad comment style */
        MANDOCERR_MACRO, /* unknown macro will be lost */
        MANDOCERR_LINESCOPE, /* line scope broken */
        MANDOCERR_BADCOMMENT, /* bad comment style */
        MANDOCERR_MACRO, /* unknown macro will be lost */
        MANDOCERR_LINESCOPE, /* line scope broken */

-       MANDOCERR_SCOPE, /* scope broken */

        MANDOCERR_ARGCOUNT, /* argument count wrong */
        MANDOCERR_ARGCOUNT, /* argument count wrong */

-       MANDOCERR_NOSCOPE, /* request scope close w/none open */
+       MANDOCERR_NOSCOPE, /* no such block is open */

        MANDOCERR_SCOPEREP, /* scope already open */
        /* FIXME: merge following with MANDOCERR_ARGCOUNT */
        MANDOCERR_NOARGS, /* macro requires line argument(s) */
        MANDOCERR_SCOPEREP, /* scope already open */
        /* FIXME: merge following with MANDOCERR_ARGCOUNT */
        MANDOCERR_NOARGS, /* macro requires line argument(s) */


@@ -92,6 +92,7 @@ enum  mandocerr {
        /* FIXME: this should be a MANDOCERR_ERROR */
        MANDOCERR_NESTEDDISP, /* displays may not be nested */
        MANDOCERR_BADDISP, /* unsupported display type */
        /* FIXME: this should be a MANDOCERR_ERROR */
        MANDOCERR_NESTEDDISP, /* displays may not be nested */
        MANDOCERR_BADDISP, /* unsupported display type */

+       MANDOCERR_SCOPEFATAL, /* blocks badly nested */

        MANDOCERR_SYNTNOSCOPE, /* no scope to rewind: syntax violated */
        MANDOCERR_SYNTSCOPE, /* scope broken, syntax violated */
        MANDOCERR_SYNTLINESCOPE, /* line scope broken, syntax violated */
        MANDOCERR_SYNTNOSCOPE, /* no scope to rewind: syntax violated */
        MANDOCERR_SYNTSCOPE, /* scope broken, syntax violated */
        MANDOCERR_SYNTLINESCOPE, /* line scope broken, syntax violated */

diff --git a/mdoc.7 b/mdoc.7
index deee615adba919dd1af8f03c41e565135b904363..0de145c3f8ca55d1ebb1e4e0cf30e9057d57bcf6 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.127 2010/06/27 13:30:51 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.128 2010/07/01 15:38:56 schwarze Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -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.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: June 27 2010 $
+.Dd $Mdocdate: July 1 2010 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -478,6 +478,19 @@ they are separated by a vertical space, unless in the case of
 and
 .Sx \&Ft ,
 which are always separated by vertical space.
 and
 .Sx \&Ft ,
 which are always separated by vertical space.

+.Pp
+When text and macros following an
+.Sx \&Nm
+macro starting an input line span multiple output lines,
+all output lines but the first will be indented to align
+with the text immediately following the
+.Sx \&Nm
+macro, up to the next
+.Sx \&Nm ,
+.Sx \&Sx ,
+or
+.Sx \&Ss
+macro or the end of an enclosing block, whichever comes first.

 .It Em DESCRIPTION
 This expands upon the brief, one-line description in
 .Em NAME .
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in
 .Em NAME .


@@ -672,9 +685,20 @@ has multiple heads.
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
 .It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx \&El
 .It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
 .It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx \&El
 .It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh

+.It Sx \&Nm  Ta    \&No     Ta  Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss

 .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
 .El
 .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
 .El

+.Pp
+Note that the
+.Sx \&Nm
+macro is a
+.Sx Block full-implicit
+macro only when invoked as the first macro
+in a
+.Em SYNOPSIS
+section line, else it is
+.Sx In-line .

 .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.
 Each has at least a body and, in limited circumstances, a head
 .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.
 Each has at least a body and, in limited circumstances, a head


@@ -1958,6 +1982,42 @@ Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
 .Ss \&Nm
 .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
 .Ss \&Nm

+The name of the manual page, or \(em in particular in section 1, 6,
+and 8 pages \(em of an additional command or feature documented in
+the manual page.
+When first invoked, the
+.Sx \&Nm
+macro expects a single argument, the name of the manual page.
+Usually, the first invocation happens in the
+.Em NAME
+section of the page.
+The specified name will be remembered and used whenever the macro is
+called again without arguments later in the page.
+The
+.Sx \&Nm
+macro uses
+.Sx Block full-implicit
+semantics when invoked as the first macro on an input line in the
+.Em SYNOPSIS
+section; otherwise, it uses ordinary
+.Sx In-line
+semantics.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Sh SYNOPSIS
+\&.Nm cat
+\&.Op Fl benstuv
+\&.Op Ar
+.Ed
+.Pp
+In the
+.Em SYNOPSIS
+of section 2, 3 and 9 manual pages, use the
+.Sx \&Fn
+macro rather than
+.Sx \&Nm
+to mark up the name of the manual page.

 .Ss \&No
 .Ss \&Ns
 .Ss \&Nx
 .Ss \&No
 .Ss \&Ns
 .Ss \&Nx

diff --git a/mdoc_macro.c b/mdoc_macro.c
index 8755cf5b674d1b6db74e1fc165e3ed793d76ed23..87e5d8950272056ad9ee2efef71d94e798e66e38 100644 (file)
--- a/mdoc_macro.c
+++ b/mdoc_macro.c
@@ -1,4 +1,4 @@
-/*     $Id: mdoc_macro.c,v 1.87 2010/07/01 14:28:12 kristaps Exp $ */
+/*     $Id: mdoc_macro.c,v 1.88 2010/07/01 15:38:56 schwarze Exp $ */

 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  *
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  *


@@ -97,7 +97,7 @@ const struct mdoc_macro __mdoc_macros[MDOC_MAX] = {
        { in_line_argn, MDOC_CALLABLE | MDOC_PARSED }, /* In */
        { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Li */
        { blk_full, 0 }, /* Nd */ 
        { in_line_argn, MDOC_CALLABLE | MDOC_PARSED }, /* In */
        { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Li */
        { blk_full, 0 }, /* Nd */ 

-       { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Nm */ 
+       { ctx_synopsis, MDOC_CALLABLE | MDOC_PARSED }, /* Nm */ 

        { blk_part_imp, MDOC_CALLABLE | MDOC_PARSED }, /* Op */
        { obsolete, 0 }, /* Ot */
        { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Pa */
        { blk_part_imp, MDOC_CALLABLE | MDOC_PARSED }, /* Op */
        { obsolete, 0 }, /* Ot */
        { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Pa */


@@ -392,6 +392,8 @@ rew_dohalt(enum mdoct tok, enum mdoc_type type,
                if (MDOC_Op == p->tok)
                        return(REWIND_MORE);
                break;
                if (MDOC_Op == p->tok)
                        return(REWIND_MORE);
                break;

+       case (MDOC_Nm):
+               return(REWIND_NONE);

        case (MDOC_Nd):
                /* FALLTHROUGH */
        case (MDOC_Ss):
        case (MDOC_Nd):
                /* FALLTHROUGH */
        case (MDOC_Ss):


@@ -409,9 +411,11 @@ rew_dohalt(enum mdoct tok, enum mdoc_type type,
 
        /*
         * Default block rewinding rules.
 
        /*
         * Default block rewinding rules.

-        * In particular, always skip block end markers.
+        * In particular, always skip block end markers,
+        * and let all blocks rewind Nm children.

         */
         */

-       if (ENDBODY_NOT != p->end || (MDOC_BLOCK == p->type &&
+       if (ENDBODY_NOT != p->end || MDOC_Nm == p->tok ||
+           (MDOC_BLOCK == p->type &&

            ! (MDOC_EXPLICIT & mdoc_macros[tok].flags)))
                return(REWIND_MORE);
 
            ! (MDOC_EXPLICIT & mdoc_macros[tok].flags)))
                return(REWIND_MORE);
 


@@ -507,8 +511,9 @@ make_pending(struct mdoc_node *broken, enum mdoct tok,
                        taker->pending = broken->pending;
                }
                broken->pending = breaker;
                        taker->pending = broken->pending;
                }
                broken->pending = breaker;

-               mdoc_vmsg(m, MANDOCERR_SCOPE, line, ppos, "%s breaks %s",
-                   mdoc_macronames[tok], mdoc_macronames[broken->tok]);
+               mdoc_vmsg(m, MANDOCERR_SCOPENEST, line, ppos,
+                   "%s breaks %s", mdoc_macronames[tok],
+                   mdoc_macronames[broken->tok]);

                return(1);
        }
 
                return(1);
        }
 


@@ -542,7 +547,9 @@ rew_sub(enum mdoc_type t, struct mdoc *m,
                        return(make_pending(n, tok, m, line, ppos));
                case (REWIND_ERROR):
                        /* XXX Make this non-fatal. */
                        return(make_pending(n, tok, m, line, ppos));
                case (REWIND_ERROR):
                        /* XXX Make this non-fatal. */

-                       mdoc_pmsg(m, line, ppos, MANDOCERR_SYNTNOSCOPE);
+                       mdoc_vmsg(m, MANDOCERR_SCOPEFATAL, line, ppos,
+                           "%s cannot break %s", mdoc_macronames[tok],
+                           mdoc_macronames[n->tok]);

                        return 0;
                }
                break;
                        return 0;
                }
                break;


@@ -653,7 +660,7 @@ blk_exp_close(MACRO_PROT_ARGS)
                        continue;
                }
 
                        continue;
                }
 

-               if (MDOC_BLOCK != n->type)
+               if (MDOC_BLOCK != n->type || MDOC_Nm == n->tok)

                        continue;
                if (atok == n->tok) {
                        assert(body);
                        continue;
                if (atok == n->tok) {
                        assert(body);


@@ -1290,8 +1297,8 @@ blk_part_imp(MACRO_PROT_ARGS)
         * is ugly behaviour nodding its head to OpenBSD's overwhelming
         * crufty use of `Op' breakage.
         */
         * is ugly behaviour nodding its head to OpenBSD's overwhelming
         * crufty use of `Op' breakage.
         */

-       if (n != body && ! mdoc_vmsg(m, MANDOCERR_SCOPE, line, ppos,
-           "%s broken", mdoc_macronames[tok]))
+       if (n != body && ! mdoc_vmsg(m, MANDOCERR_SCOPENEST,
+           line, ppos, "%s broken", mdoc_macronames[tok]))

                return(0);
 
        if (n && ! rew_sub(MDOC_BODY, m, tok, line, ppos))
                return(0);
 
        if (n && ! rew_sub(MDOC_BODY, m, tok, line, ppos))


@@ -1647,7 +1654,9 @@ ctx_synopsis(MACRO_PROT_ARGS)
         * up formatting the block scope, then child nodes will inherit
         * the formatting.  Be careful.
         */
         * up formatting the block scope, then child nodes will inherit
         * the formatting.  Be careful.
         */

-
+       if (MDOC_Nm == tok)
+               return(blk_full(m, tok, line, ppos, pos, buf));
+       assert(MDOC_Vt == tok);

        return(blk_part_imp(m, tok, line, ppos, pos, buf));
 }
 
        return(blk_part_imp(m, tok, line, ppos, pos, buf));
 }
 

diff --git a/mdoc_term.c b/mdoc_term.c
index 0207756357b14719b4886c27a8c950f8da0c0fda..338e3c72b5d6fd0454b89ae4fd4d4bd8a6c93fd6 100644 (file)
--- a/mdoc_term.c
+++ b/mdoc_term.c
@@ -1,4 +1,4 @@
-/*     $Id: mdoc_term.c,v 1.163 2010/07/01 14:34:03 kristaps Exp $ */
+/*     $Id: mdoc_term.c,v 1.164 2010/07/01 15:38:56 schwarze Exp $ */

 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  *
 /*
  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  *


@@ -85,6 +85,7 @@ static        void      termp_fo_post(DECL_ARGS);
 static void      termp_in_post(DECL_ARGS);
 static void      termp_it_post(DECL_ARGS);
 static void      termp_lb_post(DECL_ARGS);
 static void      termp_in_post(DECL_ARGS);
 static void      termp_it_post(DECL_ARGS);
 static void      termp_lb_post(DECL_ARGS);

+static void      termp_nm_post(DECL_ARGS);

 static void      termp_op_post(DECL_ARGS);
 static void      termp_pf_post(DECL_ARGS);
 static void      termp_pq_post(DECL_ARGS);
 static void      termp_op_post(DECL_ARGS);
 static void      termp_pf_post(DECL_ARGS);
 static void      termp_pq_post(DECL_ARGS);


@@ -170,7 +171,7 @@ static      const struct termact termacts[MDOC_MAX] = {
        { termp_in_pre, termp_in_post }, /* In */ 
        { termp_li_pre, NULL }, /* Li */
        { termp_nd_pre, NULL }, /* Nd */ 
        { termp_in_pre, termp_in_post }, /* In */ 
        { termp_li_pre, NULL }, /* Li */
        { termp_nd_pre, NULL }, /* Nd */ 

-       { termp_nm_pre, NULL }, /* Nm */ 
+       { termp_nm_pre, termp_nm_post }, /* Nm */ 

        { termp_op_pre, termp_op_post }, /* Op */
        { NULL, NULL }, /* Ot */
        { termp_under_pre, NULL }, /* Pa */
        { termp_op_pre, termp_op_post }, /* Op */
        { NULL, NULL }, /* Ot */
        { termp_under_pre, NULL }, /* Pa */


@@ -1025,11 +1026,35 @@ static int
 termp_nm_pre(DECL_ARGS)
 {
 
 termp_nm_pre(DECL_ARGS)
 {
 

-       if (NULL == n->child && NULL == m->name)
+       if (MDOC_BLOCK == n->type)
+               return(1);
+
+       if (MDOC_BODY == n->type) {
+               if (NULL == n->child)
+                       return(0);
+               p->flags |= TERMP_NOLPAD | TERMP_NOSPACE;
+               p->offset += term_len(p, 1) +
+                   (NULL == n->prev->child ? term_strlen(p, m->name) :
+                    MDOC_TEXT == n->prev->child->type ?
+                       term_strlen(p, n->prev->child->string) :
+                    term_len(p, 5));

                return(1);
                return(1);

+       }
+
+       if (NULL == n->child && NULL == m->name)
+               return(0);

 
        synopsis_pre(p, n);
 
 
        synopsis_pre(p, n);
 

+       if (MDOC_HEAD == n->type && n->next->child) {
+               p->flags |= TERMP_NOSPACE | TERMP_NOBREAK | TERMP_HANG;
+               p->rmargin = p->offset + term_len(p, 1) +
+                   (NULL == n->child ? term_strlen(p, m->name) :
+                    MDOC_TEXT == n->child->type ?
+                       term_strlen(p, n->child->string) :
+                    term_len(p, 5));
+       }
+

        term_fontpush(p, TERMFONT_BOLD);
        if (NULL == n->child)
                term_word(p, m->name);
        term_fontpush(p, TERMFONT_BOLD);
        if (NULL == n->child)
                term_word(p, m->name);


@@ -1037,6 +1062,21 @@ termp_nm_pre(DECL_ARGS)
 }
 
 
 }
 
 

+/* ARGSUSED */
+static void
+termp_nm_post(DECL_ARGS)
+{
+
+       if (MDOC_HEAD == n->type && n->next->child) {
+               term_flushln(p);
+               p->flags &= ~(TERMP_NOBREAK | TERMP_HANG);
+       } else if (MDOC_BODY == n->type && n->child) {
+               term_flushln(p);
+               p->flags &= ~TERMP_NOLPAD;
+       }
+}
+
+               

 /* ARGSUSED */
 static int
 termp_fl_pre(DECL_ARGS)
 /* ARGSUSED */
 static int
 termp_fl_pre(DECL_ARGS)