support .Nm indentation in manual SYNOPSIS mode

support .Nm indentation in manual SYNOPSIS mode

[Ingo Schwarze]

Hi,

Jason McIntyre and Igor Sobrado have done some testing of the new .Nm
SYNOPSIS indentation and we have found that is not only needed in the
.Sh SYNOPSIS section proper, but also in .nr nS 1 manual SYNOPSIS mode,
for example in the ifconfig(8) manual.

To achieve that, i need access to register cues in macro handlers,
in particular in ctx_synopsis:  Setting up the cues in node_alloc
is too late.

The situation is improved by the following diff.
Below the diff itself, there is a patch to the ifconfig.8 manual
showing how to use the new functionality to produce such output:

  VLAN
     ifconfig vlan-interface [vlan vlan-tag] [[-] vlandev parent-interface]
              [vlanprio vlan-priority]

     The following options are available for a vlan(4) interface:

Of course, the ifconfig(8) part of this patch is just intended as
a demonstration, not as a full fix to the ifconfig manual,
and the full fix should probably wait until .Bk support is
finished.

Technically, this diff
 * adds a SYNOPSIS cue to struct mdoc (in addition to struct mdoc_node)
 * uses registers to set up that new cue up front in mdoc_parseln()
 * in node_alloc, only copies the new cue to struct mdoc_node
 * also sets the new cue in post_sh
 * uses the new cue in ctx_synopsis
 * in case there are any, rewinds .Nm blocks before .Pp

I'm well aware that the latter point is gross and incomplete;
in the long run, we need a better way to do rewinding:
So far, only very few macro types care to rewind whatever
happened before them.  When we have more implicit blocks that
close out quickly (like .Nm), more macros need to consider rewinding
before they start their own work, and we need some clean, generic
approach for that.  But that's not the point of the current diff.
For now, the Pp-Nm quickhack is sufficient; i can be improved later.

OK?

Yours,
  Ingo


Index: libmdoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/libmdoc.h,v
retrieving revision 1.39
diff -u -p -r1.39 libmdoc.h
--- libmdoc.h	29 Jun 2010 17:10:29 -0000	1.39
+++ libmdoc.h	1 Jul 2010 17:27:53 -0000
@@ -36,6 +36,7 @@ struct	mdoc {
 #define	MDOC_PHRASELIT	 (1 << 4) /* literal within a partila phrase */
 #define	MDOC_PPHRASE	 (1 << 5) /* within a partial phrase */
 #define	MDOC_FREECOL	 (1 << 6) /* `It' invocation should close */
+#define	MDOC_SYNOPSIS	 (1 << 7) /* SYNOPSIS-style formatting */
 	int		  pflags;
 	enum mdoc_next	  next; /* where to put the next node */
 	struct mdoc_node *last; /* the last node parsed */
Index: mdoc.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc.c,v
retrieving revision 1.59
diff -u -p -r1.59 mdoc.c
--- mdoc.c	29 Jun 2010 17:10:29 -0000	1.59
+++ mdoc.c	1 Jul 2010 17:27:53 -0000
@@ -235,6 +235,14 @@ mdoc_parseln(struct mdoc *m, int ln, cha
 		return(0);
 
 	m->flags |= MDOC_NEWLINE;
+
+	if (m->regs->regs[(int)REG_nS].set) {
+		if (m->regs->regs[(int)REG_nS].v.u)
+			m->flags |= MDOC_SYNOPSIS;
+		else
+			m->flags &= ~MDOC_SYNOPSIS;
+	}
+
 	return(('.' == buf[offs] || '\'' == buf[offs]) ? 
 			mdoc_pmacro(m, ln, buf, offs) :
 			mdoc_ptext(m, ln, buf, offs));
@@ -369,23 +377,13 @@ node_alloc(struct mdoc *m, int line, int
 
 	/* Flag analysis. */
 
+	if (MDOC_SYNOPSIS & m->flags)
+		p->flags |= MDOC_SYNPRETTY;
+	else
+		p->flags &= ~MDOC_SYNPRETTY;
 	if (MDOC_NEWLINE & m->flags)
 		p->flags |= MDOC_LINE;
 	m->flags &= ~MDOC_NEWLINE;
-
-	/* Section analysis. */
-
-	if (SEC_SYNOPSIS == p->sec)
-		p->flags |= MDOC_SYNPRETTY;
-
-	/* Register analysis. */
-
-	if (m->regs->regs[(int)REG_nS].set) {
-		if (m->regs->regs[(int)REG_nS].v.u)
-			p->flags |= MDOC_SYNPRETTY;
-		else
-			p->flags &= ~MDOC_SYNPRETTY;
-	}
 
 	return(p);
 }
Index: mdoc_action.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_action.c,v
retrieving revision 1.41
diff -u -p -r1.41 mdoc_action.c
--- mdoc_action.c	26 Jun 2010 17:56:43 -0000	1.41
+++ mdoc_action.c	1 Jul 2010 17:27:53 -0000
@@ -448,6 +448,11 @@ post_sh(POST_ARGS)
 	if (SEC_NONE == m->lastnamed || SEC_CUSTOM != sec)
 		m->lastnamed = sec;
 
+	if (SEC_SYNOPSIS == sec)
+		m->flags |= MDOC_SYNOPSIS;
+	else
+		m->flags &= ~MDOC_SYNOPSIS;
+
 	/* Some sections only live in certain manual sections. */
 
 	switch ((m->lastsec = sec)) {
Index: mdoc_macro.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_macro.c,v
retrieving revision 1.51
diff -u -p -r1.51 mdoc_macro.c
--- mdoc_macro.c	1 Jul 2010 15:36:59 -0000	1.51
+++ mdoc_macro.c	1 Jul 2010 17:27:54 -0000
@@ -1570,6 +1570,9 @@ in_line_eoln(MACRO_PROT_ARGS)
 
 	assert( ! (MDOC_PARSED & mdoc_macros[tok].flags));
 
+	if (tok == MDOC_Pp)
+		rew_sub(MDOC_BLOCK, m, MDOC_Nm, line, ppos);
+
 	/* Parse macro arguments. */
 
 	for (arg = NULL; ; ) {
@@ -1633,7 +1636,7 @@ ctx_synopsis(MACRO_PROT_ARGS)
 	nl = MDOC_NEWLINE & m->flags;
 
 	/* If we're not in the SYNOPSIS, go straight to in-line. */
-	if (SEC_SYNOPSIS != m->lastsec)
+	if ( ! (MDOC_SYNOPSIS & m->flags))
 		return(in_line(m, tok, line, ppos, pos, buf));
 
 	/* If we're a nested call, same place. */
Index: ifconfig.8
===================================================================
RCS file: /cvs/src/sbin/ifconfig/ifconfig.8,v
retrieving revision 1.205
diff -u -r1.205 ifconfig.8
--- ifconfig.8	29 Jun 2010 21:28:38 -0000	1.205
+++ ifconfig.8	1 Jul 2010 17:42:16 -0000
@@ -1448,13 +1448,15 @@
 .El
 .\" VLAN
 .Sh VLAN
+.nr nS 1
 .Nm ifconfig
-.Bk -words
 .Ar vlan-interface
 .Op Cm vlan Ar vlan-tag
+.Bk -words
 .Op Oo Fl Oc Cm vlandev Ar parent-interface
+.Ek
 .Op Cm vlanprio Ar vlan-priority
-.Ek
+.nr nS 0
 .Pp
 The following options are available for a
 .Xr vlan 4
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: support .Nm indentation in manual SYNOPSIS mode

[Kristaps Dzonsons]

> Jason McIntyre and Igor Sobrado have done some testing of the new .Nm
> SYNOPSIS indentation and we have found that is not only needed in the
> .Sh SYNOPSIS section proper, but also in .nr nS 1 manual SYNOPSIS mode,
> for example in the ifconfig(8) manual.

Thanks jmc!  Igor isn't subscribed...

> To achieve that, i need access to register cues in macro handlers,
> in particular in ctx_synopsis:  Setting up the cues in node_alloc
> is too late.
> 
> The situation is improved by the following diff.
> Below the diff itself, there is a patch to the ifconfig.8 manual
> showing how to use the new functionality to produce such output:
> 
>   VLAN
>      ifconfig vlan-interface [vlan vlan-tag] [[-] vlandev parent-interface]
>               [vlanprio vlan-priority]
> 
>      The following options are available for a vlan(4) interface:
> 
> Of course, the ifconfig(8) part of this patch is just intended as
> a demonstration, not as a full fix to the ifconfig manual,
> and the full fix should probably wait until .Bk support is
> finished.
> 
> Technically, this diff
>  * adds a SYNOPSIS cue to struct mdoc (in addition to struct mdoc_node)
>  * uses registers to set up that new cue up front in mdoc_parseln()
>  * in node_alloc, only copies the new cue to struct mdoc_node
>  * also sets the new cue in post_sh
>  * uses the new cue in ctx_synopsis
>  * in case there are any, rewinds .Nm blocks before .Pp
> 
> I'm well aware that the latter point is gross and incomplete;
> in the long run, we need a better way to do rewinding:
> So far, only very few macro types care to rewind whatever
> happened before them.  When we have more implicit blocks that
> close out quickly (like .Nm), more macros need to consider rewinding
> before they start their own work, and we need some clean, generic
> approach for that.  But that's not the point of the current diff.
> For now, the Pp-Nm quickhack is sufficient; i can be improved later.

This is fine, and I don't think there's need for a more fancy way of 
doing the special-case rewinding as it happens seldom.  Not yet at least.

Please put in some comments before the mdoc.c scanning of the registers.

Beyond that, this looks fine to me.

Thanks,

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv