Bk -words badness

Bk -words badness

[Kristaps Dzonsons]

Ingo, how goes the `Bk' work?  Scanning through mandoc's rendering of 
current manuals, I see a lot of the following sort of breakage:

.Bk -words
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
.Op Fl a Ar b
...

Which will, for obvious reasons, continue eternally past rmargin.

I have an intuition for how to implement an implied `Bk' for all 
SYNPRETTY blocks: to hook into print_mdoc_node() and set/unset the 
PREKEEP flag depending on the line number as reported in mdoc_node.

Would this sort of behaviour satisfy you?  The effect would be:

<PREKEEP>.Op Fl a Ar b<UNKEEP>
<PREKEEP>.Op Fl a Ar b<UNKEEP>

...etc.

The `Bk' handler would then be responsible for simply setting the flag 
that would be OR'd in print_mdoc_node() for keeps (SYNPRETTY|KEEPPRETTY 
or whatever).

This way, we can simply say that SYNOPSIS implies a `Bk -words' for the 
entire section (i.e., SYNPRETTY) and that `Bk -words' means that 
contained macro lines aren't space-broken between words.

Thoughts?

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

Re: Bk -words badness

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 677 bytes --]

> Ingo, how goes the `Bk' work?  Scanning through mandoc's rendering of
> current manuals, I see a lot of the following sort of breakage:
> 
> .Bk -words
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
> ...

The enclosed patch is a first stab at this.  It only works for explicit
`Bk -words' for now; it's trivial to extend this to SYNPRETTY.  As you
can see, it simply checks whether it's in a KEEP mode and resets to
PREKEEP if it's a line subsequent the prior node.

This fixes the badness mentioned above.

Thoughts?

Kristaps


[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 1106 bytes --]

? .foo.1.swp
? config.h
? config.log
? foo.1
? foo.1.html
? foo.3
? foo.7
? foo.html
? mandoc
? patch.txt
? relayd.8
? relayd.8.html
? spamd.8
? ssh.1
? ssh.1.html
? regress/output
Index: mdoc_term.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_term.c,v
retrieving revision 1.171
diff -u -r1.171 mdoc_term.c
--- mdoc_term.c	4 Jul 2010 22:04:04 -0000	1.171
+++ mdoc_term.c	5 Jul 2010 10:36:57 -0000
@@ -330,6 +330,23 @@
 	else if (termacts[n->tok].pre && ENDBODY_NOT == n->end)
 		chld = (*termacts[n->tok].pre)(p, &npair, m, n);
 
+	/*
+	 * Keeps only work until the end of a line.  If a keep was
+	 * invoked in a prior line, revert it to PREKEEP.
+	 */
+
+	if (TERMP_KEEP & p->flags) {
+		if (n->prev && n->prev->line != n->line) {
+			p->flags &= ~TERMP_KEEP;
+			p->flags |= TERMP_PREKEEP;
+		} else if (NULL == n->prev) {
+			if (n->parent && n->parent->line != n->line) {
+				p->flags &= ~TERMP_KEEP;
+				p->flags |= TERMP_PREKEEP;
+			}
+		}
+	}
+
 	if (chld && n->child)
 		print_mdoc_nodelist(p, &npair, m, n->child);
 

Re: Bk -words badness

[Kristaps Dzonsons]

>> Ingo, how goes the `Bk' work?  Scanning through mandoc's rendering of
>> current manuals, I see a lot of the following sort of breakage:
>>
>> .Bk -words
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> .Op Fl a Ar b
>> ...
> 
> The enclosed patch is a first stab at this.  It only works for explicit
> `Bk -words' for now; it's trivial to extend this to SYNPRETTY.  As you
> can see, it simply checks whether it's in a KEEP mode and resets to
> PREKEEP if it's a line subsequent the prior node.
> 
> This fixes the badness mentioned above.

...so I visually checked this against /all/ OpenBSD manuals with `Bk'
and didn't notice anything out of the ordinary except ssh-keygen(1) and
crunchgen(8).  Both exhibit block-breaking behaviour regarding `Nm' and
`Bk'.

The only systematic difference I see between mandoc and groff is that
given two `Nm' blocks in the SYNOPSIS, groff remembers the first
indentation whilst mandoc will readjust itself.  I prefer the latter,
but that's just me.

Example (edited, as groff doesn't have our awesome -Owidth=xxx option):

groff:
     newfs [-Nq] [-b block-size] [-c fragments-per-cylinder-group]
           [-f frag-size] [-g avgfilesize] [-h avgfpdir]

     mount_mfs [-b block-size] [-c fragments-per-cylinder-group]
           [-f frag-size] [-i bytes] [-m free-space] [-o options]

mandoc:
     newfs [-Nq] [-b block-size] [-c fragments-per-cylinder-group]
           [-f frag-size] [-g avgfilesize] [-h avgfpdir]

     mount_mfs [-b block-size] [-c fragments-per-cylinder-group]
               [-f frag-size] [-i bytes] [-m free-space]

If this behaviour is desired, I think it's pretty trivial to implement
given an extra state variable.

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

Re: Bk -words badness

[Ingo Schwarze]

Hi Kristaps,

> The enclosed patch is a first stab at this.  It only works for explicit
> `Bk -words' for now; it's trivial to extend this to SYNPRETTY.  As you
> can see, it simply checks whether it's in a KEEP mode and resets to
> PREKEEP if it's a line subsequent the prior node.

Excellent, this is much more elegant than what i would have done,
which is closing out a pending keep at the end of the line and
re-opening it, in a way similar to .Fl closing out and reopening
itself when encountering punctuation.

Please commit to both repositories!

> Thoughts?

If we now enable automatic implicit word keeping in the SYNOPSIS,
i guess we are mostly done with .Bk.

We only need to pay attention because .Bk doesn't nest well.
An explicit .Bk/.Ek in the SYNOPSIS would have the .Ek close
out the implicit automatic keep, so i guess we need to skip
the code in termp_bk_post in SYNOPSIS mode.

Yours,
  Ingo


> Index: mdoc_term.c
> ===================================================================
> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_term.c,v
> retrieving revision 1.171
> diff -u -r1.171 mdoc_term.c
> --- mdoc_term.c	4 Jul 2010 22:04:04 -0000	1.171
> +++ mdoc_term.c	5 Jul 2010 10:36:57 -0000
> @@ -330,6 +330,23 @@
>  	else if (termacts[n->tok].pre && ENDBODY_NOT == n->end)
>  		chld = (*termacts[n->tok].pre)(p, &npair, m, n);
>  
> +	/*
> +	 * Keeps only work until the end of a line.  If a keep was
> +	 * invoked in a prior line, revert it to PREKEEP.
> +	 */
> +
> +	if (TERMP_KEEP & p->flags) {
> +		if (n->prev && n->prev->line != n->line) {
> +			p->flags &= ~TERMP_KEEP;
> +			p->flags |= TERMP_PREKEEP;
> +		} else if (NULL == n->prev) {
> +			if (n->parent && n->parent->line != n->line) {
> +				p->flags &= ~TERMP_KEEP;
> +				p->flags |= TERMP_PREKEEP;
> +			}
> +		}
> +	}
> +
>  	if (chld && n->child)
>  		print_mdoc_nodelist(p, &npair, m, n->child);
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Bk -words badness

[Kristaps Dzonsons]

>> Thoughts?
> 
> If we now enable automatic implicit word keeping in the SYNOPSIS,
> i guess we are mostly done with .Bk.

Ja.  I'll check this in, first.  The SYNPRETTY part is trivial.

> We only need to pay attention because .Bk doesn't nest well.
> An explicit .Bk/.Ek in the SYNOPSIS would have the .Ek close
> out the implicit automatic keep, so i guess we need to skip
> the code in termp_bk_post in SYNOPSIS mode.

Do you know whether a `Pp' ends the SYNPRETTY flag?  I remember some 
talk about `Pp' having this effect but can't remember.  It would be a 
trivial change, but should be looked into: if a `Pp' is encountered in a 
SYNOPSIS and what comes after is regular stuff, the hard-breaks will 
raise hell.  These thoughts are off the top of my head: I have no idea 
how this works in practise.

Thanks,

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

Re: Bk -words badness

[Ingo Schwarze]

Hi Kristaps,

> Do you know whether a `Pp' ends the SYNPRETTY flag?

It does not, see the example file below, which mandoc, old and new
groff all render like this:

  SYNOPSIS
     #include <math.h>

     double
     sin(double x);

     double
     cos(double x);

Of course, we should not recommend using .Pp in the SYNOPSIS,
but that is a separate question.

> I remember some talk about `Pp' having this effect but can't
> remember.

Well, Joerg suggested that it might make sense, but apparently,
it is not how it worked in the past, so i don't think we should
change the rules here.  Even more so given that .Pp is neither
very common nor that useful in the SYNOPSIS.

Yours,
  Ingo


.Dd July 7, 2010
.Dt FN-WITH-PP 3
.Os
.Sh NAME
.Nm Fn-with-Pp
.Nd special handling of .Fn together with .Pp
.Sh SYNOPSIS
.In math.h
.Ft double
.Fn sin "double x"
.Pp
.Ft double
.Fn cos "double x"
.Sh CUSTOM
.nr nS 1
.In math.h
.Ft double
.Fn sinh "double x"
.Pp
.Ft double
.Fn cosh "double x"
.nr nS 0
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Bk -words badness

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Jul 05, 2010 at 11:18:33AM +0200:

> Ingo, how goes the `Bk' work?

Not.

I was slacking in Bob's garden, then on the plane, then sleeping,
then at work.  Now i'm catching up on my mail.  :-)

> Scanning through mandoc's rendering
> of current manuals, I see a lot of the following sort of breakage:
> 
> .Bk -words
> .Op Fl a Ar b
> .Op Fl a Ar b
> .Op Fl a Ar b
[...]

> Which will, for obvious reasons, continue eternally past rmargin.

Right, that is one of the most annoying problems we still have.

> I have an intuition for how to implement an implied `Bk' for all
> SYNPRETTY blocks: to hook into print_mdoc_node() and set/unset the
> PREKEEP flag depending on the line number as reported in mdoc_node.

Sounds good.

> Would this sort of behaviour satisfy you?  The effect would be:
> 
> <PREKEEP>.Op Fl a Ar b<UNKEEP>
> <PREKEEP>.Op Fl a Ar b<UNKEEP>

Yes, if i understand correctly, that is what groff does.
It also ought to allow almost any desired formatting,
and it is somewhat intuitive:  People are likely to put
on one input line whatever belongs closely together,
even when they don't remember the rule.

> The `Bk' handler would then be responsible for simply setting the
> flag that would be OR'd in print_mdoc_node() for keeps
> (SYNPRETTY|KEEPPRETTY or whatever).
> 
> This way, we can simply say that SYNOPSIS implies a `Bk -words' for
> the entire section (i.e., SYNPRETTY) and that `Bk -words' means that
> contained macro lines aren't space-broken between words.

Yes, you are right, the documentation is also very simple to write
and very simple to understand.

> Thoughts?

[x] Try that!

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