Re: Basic implementation of .Bk/.Ek

Re: Basic implementation of .Bk/.Ek

[Ingo Schwarze]

Jason asked me to forward this to tech@, as he is not subscribed
and cannot post.  Since this discussion is of general interest
and not just about implementation details only, i suggest to post
to discuss@ in case you want to follow up.

----- Forwarded message from Jason McIntyre <jmc@kerhand.co.uk> -----

From: Jason McIntyre <jmc@kerhand.co.uk>
Date: Sun, 27 Jun 2010 15:45:04 +0100
To: Ingo Schwarze <schwarze@usta.de>
Cc: tech@mdocml.bsd.lv
Subject: Re: mdocml: Basic implementation of .Bk/.Ek; from OpenBSD.

On Sun, Jun 27, 2010 at 04:34:01PM +0200, Ingo Schwarze wrote:
> Hi Kristaps,
> 
> > Remember the mdoc.7 entries!
> 
> Sorry for forgetting; this is now done.
> 
> > All usages of `Bk' seem to use `-words'.
> 
> Right, and it is documented accordingly:
> 
>   More work needs to be done with the keep macros;
>   a -line option needs to be added.  -- from mdoc.samples
> 
> This is correct except that "-line" ought to read "-lines".
> 
> > Does not using this flag change the macros behaviour?
> 
> Here is old groff's behaviour:
> 
>   no arg: Usage: .Bk [-lines | -words] (#13) and ignoring .Bk
>   -lines: Not implemented yet. (#47) and ignoring .Bk
>   -line: No error message and ignoring .Bk
> 
> Here is new groff's behavious:
> 
>   no arg: no error message, and assuming -words
>   -lines: Not implemented yet. (#21) and assuming -words
>   -line: no error message, and assuming -words
> 
> Great, isn't it?
>   
> So, here is a patch to
>  * not print invalid arguments verbatim (no groffs prints them, either)
>  * not trigger TERMP_PREKEEP twice
>  * not die from invlid arguments (groff won't die, either)
>  * continue to ignore even valid arguments (just like groff)
> 
> OK?
> 

i'll request this again, publicly: Bk/Ek makes no sense for synopsis. it
is buggy, so the man page writer needs to guess where to stick them
until they hit upon the "right" combination. that sucks.

what i'd like, though i have no idea if it's practical: mandoc
recognises these macros but ignores them completely. instead, it always
formats SYNOPSIS in a way which causes no line break in the wrong place.
is that a possibility?

jmc


> 
> Index: mdoc_term.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/mdoc_term.c,v
> retrieving revision 1.90
> diff -u -p -r1.90 mdoc_term.c
> --- mdoc_term.c	27 Jun 2010 01:24:02 -0000	1.90
> +++ mdoc_term.c	27 Jun 2010 14:15:31 -0000
> @@ -2104,8 +2104,17 @@ static int
>  termp_bk_pre(DECL_ARGS)
>  {
>  
> -	p->flags |= TERMP_PREKEEP;
> -	return(1);
> +	switch (n->type) {
> +	case (MDOC_BLOCK):
> +		return(1);
> +	case (MDOC_HEAD):
> +		return(0);
> +	case (MDOC_BODY):
> +		p->flags |= TERMP_PREKEEP;
> +		return(1);
> +	default:
> +		abort();
> +	}
>  }
>  
>  
> @@ -2114,7 +2123,8 @@ static void
>  termp_bk_post(DECL_ARGS)
>  {
>  
> -	p->flags &= ~(TERMP_KEEP | TERMP_PREKEEP);
> +	if (MDOC_HEAD == n->type)
> +		p->flags &= ~(TERMP_KEEP | TERMP_PREKEEP);
>  }
>  
>  /* ARGSUSED */
> Index: mdoc_validate.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/mdoc_validate.c,v
> retrieving revision 1.61
> diff -u -p -r1.61 mdoc_validate.c
> --- mdoc_validate.c	26 Jun 2010 17:56:43 -0000	1.61
> +++ mdoc_validate.c	27 Jun 2010 14:15:32 -0000
> @@ -103,7 +103,7 @@ static	int	 pre_ss(PRE_ARGS);
>  
>  static	v_post	 posts_an[] = { post_an, NULL };
>  static	v_post	 posts_at[] = { post_at, NULL };
> -static	v_post	 posts_bd[] = { hwarn_eq0, bwarn_ge1, NULL };
> +static	v_post	 posts_bd_bk[] = { hwarn_eq0, bwarn_ge1, NULL };
>  static	v_post	 posts_bf[] = { hwarn_le1, post_bf, NULL };
>  static	v_post	 posts_bl[] = { bwarn_ge1, post_bl, NULL };
>  static	v_post	 posts_bool[] = { eerr_eq1, ebool, NULL };
> @@ -150,7 +150,7 @@ const	struct valids mdoc_valids[MDOC_MAX
>  	{ NULL, posts_notext },			/* Pp */ 
>  	{ pres_d1, posts_wline },		/* D1 */
>  	{ pres_d1, posts_wline },		/* Dl */
> -	{ pres_bd, posts_bd },			/* Bd */
> +	{ pres_bd, posts_bd_bk },			/* Bd */
>  	{ NULL, NULL },				/* Ed */
>  	{ pres_bl, posts_bl },			/* Bl */ 
>  	{ NULL, NULL },				/* El */
> @@ -241,7 +241,7 @@ const	struct valids mdoc_valids[MDOC_MAX
>  	{ NULL, NULL },				/* Fc */ 
>  	{ NULL, NULL },				/* Oo */
>  	{ NULL, NULL },				/* Oc */
> -	{ NULL, posts_wline },			/* Bk */
> +	{ NULL, posts_bd_bk },			/* Bk */
>  	{ NULL, NULL },				/* Ek */
>  	{ NULL, posts_eoln },			/* Bt */
>  	{ NULL, NULL },				/* Hf */

----- End forwarded message -----
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv