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 discuss+unsubscribe@mdocml.bsd.lv

Re: Basic implementation of .Bk/.Ek

[Ingo Schwarze]

Hi Jason,

> i'll request this again, publicly: Bk/Ek makes no sense for synopsis.

I tend to agree:  We do need a .Bk implementation even for the SYNOPSIS
to deal with existing pages, but always writing stuff like

.Bk -words
.Op o Ar file
.Ek

for each and every single argument is positively tedious, and figuring
out for which argument it is needed because it will end up near the end
of the line is tedious, too, fragile when adding arguments, and finally
broken now that we have -Owidth=width.

[...]
> what i'd like, though i have no idea if it's practical:
> mandoc recognises these macros but ignores them completely.

I think when present, they should be honoured, even in the SYNOPSIS.

> instead, it always formats SYNOPSIS in a way which causes no line
> break in the wrong place.  is that a possibility?

I suspect we will be able to identify a couple of cases that
basically always want to be wrapped in .Bk inside the SYNOPSIS,
and make that automatic.  For example, the following cases
come to mind:

 * We probably never want a line break in the middle of .Op
   or between .Oo and .Oc.
 * We probably never want a line break between .Fl and
   immediately following .Ar.

The trick is to unambiguously describe these cases and not just
resort to "do not break where it looks ugly" because that's kind
of hard to implement.  :)

I should like attacking that task after fixing more of the
outright bugs still keeping us company.

By the way, decent .Bk support is now committed both to bsd.lv
and openbsd.org.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv