Space after .E[dl...]?

Space after .E[dl...]?

[Thomas Klausner]

Hi!

groff by default doesn't add space after a Bd/Ed, Bl/El etc. Many man
page authors do like to have one there though and add a Pp for this
reason.

I think that Bd/Ed etc should have a space by default afterwards (like
before the block); except perhaps when used with -compact.

Opinions?
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Space after .E[dl...]?

[Ingo Schwarze]

Hi Thomas,

Thomas Klausner wrote on Tue, Nov 22, 2011 at 11:34:16PM +0100:

> groff by default doesn't add space after a Bd/Ed, Bl/El etc.
> Many man page authors do like to have one there though
> and add a Pp for this reason.
> 
> I think that Bd/Ed etc should have a space by default afterwards
> (like before the block); except perhaps when used with -compact.
> 
> Opinions?

Maybe that would have been better design.
I'm not completely sure that i don't miss good reasons for the
established behaviour, but your idea does seem more natural to
me than what we have now.

However, this is not just a question of what we like better,
but also a question of compatibility.  There are three aspects
to compatibility:

(1) At the very least, if we were to change this, groff and
mandoc would have to change at the same time.  This is clearly
not a good point to introduce a groff-mandoc difference.
Currently, it is not easy to push changes into the groff
mainline.  Werner Lemberg, the groff technical lead, is
overworked, and while he does take care of critical stuff and
also some of the less important things that seem interesting
to him, he does not respond to all suggestions.  No other groff
committer takes the initiative when it comes to changing
established behaviour, unless my impressions during the last
year or so are quite wrong.

(2) Even if we would manage to write patches for groff and
mandoc and get them into both trees, we have to consider that
people writing new or editing existing manuals will start
relying on the new behaviour, and such manuals will look bad
with older formatters, for example on Solaris.  For that reason,
if the existing behaviour has been consistent for a very long
time on almost all mdoc(7) implementations, i'd be rather
hesitant to change it now.  On the other hand, if existing
older implementations were inconsistent with one another
anyway, this item (2) wouldn't be a relevant point.  Note that
i have still not come round to tracking down, installing, and
testing legacy mdoc(7) implementations, such that i have no
idea which kinds of changes would be how disrupting.  Before
setting out to change the language, i'd consider it important
to have a good understanding of such questions.  However, right
now, i still see much more important issues to work on than
investigating compatibility with legacy mdoc(7) implementations
and trying to polish the language definition.

(3) There are thousands of real-world manuals written for the
old behaviour.  Quite probably, there are some that will look
worse after the change because the additional blank line is not
an improvement in their particular case, even if it is in many
other cases, and the authors of course relied on the fact that
there is no blank line.  Before even proposing this change in
the language definition, i'd like some rough estimate, or at
least feeling, how many pages might be affected by this effect,
and how much effort we are imposing on people like jmc@ to
clean up the tree after the change.

In short, i think this is much less trivial than it may seem,
and i'm not that thrilled about the idea, unless somebody else
is going to do all the work outlined above.

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

Re: Space after .E[dl...]?

[Thomas Klausner]

On Wed, Nov 23, 2011 at 01:31:19AM +0100, Ingo Schwarze wrote:
> However, this is not just a question of what we like better,
> but also a question of compatibility.  There are three aspects
> to compatibility:

I understand your point. Most (if not all) mdoc man pages that a
typical BSD user is interested in will come with their operating
system though, so I don't see it as such a big hindrance as you do,
because we can fix them.

> (3) There are thousands of real-world manuals written for the
> old behaviour.  Quite probably, there are some that will look
> worse after the change because the additional blank line is not
> an improvement in their particular case, even if it is in many
> other cases, and the authors of course relied on the fact that
> there is no blank line.  Before even proposing this change in
> the language definition, i'd like some rough estimate, or at
> least feeling, how many pages might be affected by this effect,
> and how much effort we are imposing on people like jmc@ to
> clean up the tree after the change.

For backwards compat, I'd like to have Pp after El etc. ignored; this
should fix this problem.

Thanks for your feedback!
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Space after .E[dl...]?

[Ingo Schwarze]

Hi Thomas,

Thomas Klausner wrote on Wed, Nov 23, 2011 at 01:54:26PM +0100:
> On Wed, Nov 23, 2011 at 01:31:19AM +0100, Ingo Schwarze wrote:

>> However, this is not just a question of what we like better,
>> but also a question of compatibility.  There are three aspects
>> to compatibility:

> I understand your point. Most (if not all) mdoc man pages that a
> typical BSD user is interested in will come with their operating
> system though, so I don't see it as such a big hindrance as you do,
> because we can fix them.

There are several ports containing mdoc(7) manuals.
Besides, it would be a pain if moving manuals from one
operating system to another would require fixing up the
manual source code because of language incompatibilities.
I'd rather reduce such incompatibilies than deliberately
add to them.

>> (3) There are thousands of real-world manuals written for the
>> old behaviour.  Quite probably, there are some that will look
>> worse after the change because the additional blank line is not
>> an improvement in their particular case, even if it is in many
>> other cases, and the authors of course relied on the fact that
>> there is no blank line.  Before even proposing this change in
>> the language definition, i'd like some rough estimate, or at
>> least feeling, how many pages might be affected by this effect,
>> and how much effort we are imposing on people like jmc@ to
>> clean up the tree after the change.

> For backwards compat, I'd like to have Pp after El etc. ignored;

For sure; in mandoc, that would be more or less automatic;
in groff, i don't really know.

> this should fix this problem.

Er, no, i tried to talk about the reverse problem:
Existing pages that do not have a .Pp after .Ed or .El
because the author did not intend a blank line at that place.

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