(I'm not sure how to reply to these bug messages that I get because, I
assume, I'm a watcher on the bug. The only addresses offered to respond to
are invalid.nore...@gnu.org and bug-groff@gnu.org, and I'm not sure if
either of them correctly add my message to the bug. I'm copying you
directly in this one so that you don't have to dig it out of the
moderation queue. Let me know if there's some better place to send the
message that will work more smoothly with the bug system.)
"G. Branden Robinson" <invalid.nore...@gnu.org> writes:
> You might want to add
> .if n .nr HY 0
> to podlators-generated man pages.
Okay, thanks. I'll try to get a new release out with that change soon.
Currently, I just put .nh immediately after .TH and assume that it will
persist.
>> I think the important part for podlators going forward, given this
>> behavior, is to make sure that the ".if n .ds AD l" line stays in the
>> preamble (in other words, before .TH) so that groff can reassert user
>> preferences at .TH and not be confused with (3). That's easy enough
>> (and natural) to do.
> That should not be necessary, and in fact I expect such an early
> operation to be ignored.
Hm, I think there's some confusion here. Right now, the released version
of podlators puts the line:
.if n .ds AD l
right before the .TH macro, and this works correctly with groff 1.23.0.
Are you saying that this line needs to move to somewhere else with groff
1.24.0? Where, precisely? Will it still work correctly if moved with groff
1.23.0?
> Yes, as noted above,
> .if n .nr HY 0
> Is probably what you want, and moreover should work with every _groff_
> in the world even in old deployments. It's an old feature.[2]
Where should I put this in the document?
> [2] The code comments concede that the `HY` register isn't supported
> everywhere. That's true, but Solaris 10, DWB 3.3, and Seventh
> Edition Unix _troff_s are all historical implementations, and
> Plan 9 from User Space is a something of a niche exhibit--which
> might nevertheless accept a patch from me if I submitted one.[3]
> _mandoc_ doesn't support it, but doesn't need to.
Presumably I should both define HY *and* continue to use the .nh
directive to account for those systems.
Everything I write below this point can be safely ignored entirely. It has
no relevance to the technical discussion or this change in particular.
Read on only if you're interested in an opinionated argument about the
merits of hyphenation and justification for man pages from someone who
neither has nor wants any power to change the direction of groff in this
respect and is perfectly content for Branden to make these decisions. :)
> That is why modern typesetting systems like _TeX_ and _groff_ offer a
> variety of configuration knobs for automatic hyphenation.
Yes, but I think my point may not have been clear. You have doubtless read
even more about this than I have, but even in my casual reading of
commentary by professional proofreaders and typesetters (such as Benjamin
Dreyer's occasional commentary on the process of typesetting a book), it
is clear that, at least for high-quality output, they put a fair amount of
effort into avoiding poor hyphenation. The ways they avoid that for a
given page proof may even involve measures not available to the most
sophisticated typesetting system, such as changing the wording of a
sentence so that hyphenation becomes unnecessary without forcing poor
justification.
I've done this myself with TeX documents that I was formatting for
printing with a fixed typesetting target.
However nice it would be if people would routinely do this work for man
pages, my contention is that nearly all man page authors *don't* do this,
and are unlikely to do this in the future.
The choice for the typical page that uses the *defaults* is therefore
between purely mechanical hyphenation with all the endless errors and
infelicities that involves, or dispensing with hyphenation altogether. The
choice is somewhat difficult if one is attempting to produce fully
justified text, I admit, since fully justified text without hyphenation
often requires mangling the word spacing beyond any acceptable level. But
if one dispenses with both, the output is reasonable, if perhaps not as
aesthetically appealing, and far more robust.
On top of that, I will always argue that full justification is simply
incorrect to even attempt in a fixed width font on a terminal, since there
is no fine-grained control over interword spacing to smooth out the
justification and thus one has no choice but to scatter in random full
spaces in a way that is just embarrassingly hideous.
Not that I have strong opinions about this or anything. :)
And of course, regardless, I'm dealing with POD input source, so none of
those facilities for fine-tuning the hyphenation are available to the
author. To me that adds weight to the feeling that avoiding hyphenation
entirely is the only reasonable choice.
> .\" Resetting the hyphenation mode is a complicated dance.
> .\" 1. Man pages sometimes disable automatic hyphenation--when they
> .\" do, they nearly always forget to put it back the way it was.
I promise that I did not forget to put it back. That was entirely
intentional. :) I suspect that is the case for a lot of other man pages
that use .nh too, if they use it early in the document.
> With this extension, I serve two sets of users:
> * Those who, like _podlators_, want to just shut these things off and
> keep them off until the page is done rendering. (They have no right
> to dictate how subsequent pages get formatted.)
> * Those who favor or don't mind adjustment and hyphenation, but are
> fine-tuning their typeset _man_ document, and wish to disable these
> features at the granularity of a paragraph.
While I am sure that the second set of users do exist, I am a *little* bit
dubious that it contains more than on the order of ten people, and thus it
would make more sense to me if they had to explicitly turn on adjustment
and hyphenation to indicate that they know about the challenges and are
going to try to tackle them.
I am more concerned with a third set of users that I suspect is quite a
bit larger:
* Those who have never given any thought to adjustment or hyphenation and
are writing a man page because they want all commands to have man pages
and are mostly cargo-culting other man pages. These folks are not
fine-tuning the adjustment or hyphenation, and I feel would be better
served by ragged right and no hyphenation as less fragile defaults. Some
of the things those defaults will do will be perceived as ugly, but I
think the average damage to good typesetting would be less than trying
to force justification and hyphenation by default when the author is not
signed up for the work required to make them look good.
> I concede that my novelty here is inadequate to cope with situations
> where adjustment and automatic hyphenation need to come and go _within a
> paragraph_, but those are just about taken care of by other _man_ and
> *roff features.
Yes, as you can tell I'm not concerned with that. :)
I have absolutely no objections to, and indeed great admiration for, all
of the hard work that you are putting into adjustment and hyphenation
support, and I think both are important for good typesetting. My
objections to your approach (and again, I'm saying this only because you
seem willing to discuss it; you are the groff maintainer, a job I
definitely do not want and which I think you are doing a fine job at, and
therefore this is your decision and I will happily live with what you
decide) are just:
* Good justification and hyphenation require human attention to avoid
somewhat pathological cases ("overfull hbox") that are often best
avoided by rewording. The result can be quite nice when some human does
put in that attention, but this is far from the common case for,
specifically, man documents. Therefore, disabling both is a more robust
default. Those who wish to put in that work should have a way to
re-enable them for proper troff typeset output.
* Justification should be off for man pages formatted with nroff because
it cannot be done properly in a fixed-width font and attempting to do so
results in bizarre formatting that us old UNIX grognards are used to
from years of reading fully justified man pages, but which is less
readable than a ragged right margin. (Personal opinion alert! I realize
others disagree.)
> To elaborate slightly on the last point, when fine-tuning the
> typesetting of _groff_'s own man pages for our PDF compilation thereof,
> I make occasional recourse to formatter features, mainly to achieve more
> pleasant page breaks.
Yes, indeed, and I would never argue against your ability to enable full
justification and and hyphenation for troff formatting of such documents
when a human is investing that level of time and attention into fixing
typesetting issues.
> Another aspect is not surrendering to despair and futility when
> presented with technical challenges. ;-)
If you manage to figure out how to do proper fine-grained interword
spacing in a terminal with a fixed-width font, I will bow to your clearly
superior and astonishingly admirable ability to overcome technical
challenges. :)
--
Russ Allbery (ea...@eyrie.org) <https://www.eyrie.org/~eagle/>
