Re: [docbook-apps] Refentry, man pages, and DocBook XSL 1.69.0

[Michael Smith <smith@xml-doc.org>]

Hi Tim,

You wrote:

> Text is no longer justified on the right-hand side.  Is that
> intentional?

Yep. I changed the default to be unjustified, and added the
man.justify parameter, which you can set to non-zero if you want
the old behavior. I also changed the default hyphenation behavior
to be such that hyphenation is off, globally. The parameter for
controlling that is man.hyphenate.

  http://docbook.sourceforge.net/release/xsl/current/doc/manpages/man.justify.html
  http://docbook.sourceforge.net/release/xsl/current/doc/manpages/man.hyphenate.html

I had some misgivings about changing the default behavior but I
did it for a reason (see below).  However, if you (or anybody
else) feel strongly that the old behavior should be restored as
the default, I will consider changing it back for the next
release. Let me know.

The rationale for the changes is explained in the documentation
for the parameters above and also in the "man" section of the
1.69.0 release notes -

  http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html#V1690_MAN

Basically, justified text looks good only when it's also hyphenated;
to quote the “Hyphenation” node from the groff info page:

  Since the odds are not great for finding a set of words, for
  every output line, which fit nicely on a line without inserting
  excessive amounts of space between words, 'gtroff' hyphenates
  words so that it can justify lines without inserting too much
  space between words.

The problem is that groff can end up hyphenating a lot of things
that you don't want hyphenated (variable names and command names,
for example). Keeping both justification and hyphenation disabled
ensures that hyphens never get inserted where you don't want to
them, and you don't end up with lines containing excessive amounts
of space between words.

Those default settings run counter to how most existing man pages
are formatted. But there are some notable exceptions, such as the
perl man pages.

  --Mike

Digital signature