#122 man: Prevent hyphenation of symbols

[hofschnr]

Inserts the hyphenation character before replaceable, varname,
option, userinput, envar, errorcode, constant, type, refentrytitle,
command, function, and parameter text to prevent them from
being hyphenated by groff.

For filename text, zero-width break points are inserted after every
directory delimiter and hyphenation characters are inserted before
every filename component.

[hofschnr]

Patch file against docbook-xsl-1.68.1/manpages (fixed)

[Michael(tm) Smith]

Logged In: YES
user_id=118135

Hi Ryan,

Sorry for the delay in following up on this.

Today, I checked in two changes related to this request.

1. Added a new parameter, man.hyphenate

http://docbook.sf.net/snapshot/xsl/doc/manpages/man.hyphenate.html

If the value of that is zero (this is now the
default behavior for the stylesheets), then
hyphenation is disabled, globally. If it it
non-zero, hyphenation is enable (that is, the
normal default behavior for roff/groff.

The "disable hyphenation" behavior is implemented
simply by adding ".hy 0" to the beginning of each
output man page.

2. Added a new parameter, man.break.after.slash

If zero (the default), line-breaking after slashes
is disabled. If non-zero, it is enabled.

This was direct from you suggestin, but I
implemented it differently than you did in your
patch. The way it is is accomplished is simply by
adding ".cflags 4 /" to the beginning of each file.
That tells groff that it's OK to break after a slash.

One limitation is that it only works with groff (not
with non-GNU nroff/troff). But even after doing
quite a bit of testing, I have not been able to find
a way to enable breaking after slashes with non-GNU
roff (testing on Solaris and HP-UX and Dec machines.)

I looked very carefully at your patch and did a lot of
testing with it. Unfortunately, in my environments at
least, it doesn't seem to always have the effects you
intended.

One thing I've found is that despite what the groff
docs claim, \% placed before a word does always prevent
that word from being hyphenated. (If you have tested
with it much and found that it actually prevents words
from being hyphenated, please let me know. It could
just be that I am doing something wrong).

Two other things are problematic about putting \:\%
into URLs and pathnames:

- "\:" is groff-only escape. In trying to view a man
page with "\:" in it on Solaris and HP-UX and Dec
boxes, the results I found with that it either
shows up as a literal "\:" in output, or it causes
all kinds of strange formatting problems.

- "\%" seems to be interpreted differently by non-GNU
roff than it is by groff. In the Solaris
environment I tested with, it causes a hyphen to be
displayed at the end of the line where it breaks.
That seemse to have been the normal behavior in
non-GNU roff. But in groff, it causes a break, but
does not cause a hyphen to be added ad the end of
the line where it adds the break (the behavior your
patch depends on).

Anyway, I think the ".cflags 4 /" request achieves the
same affect without causing problems on other
platforms. Please try it and let me know what you think.

Now, about suppressing hyphenation of symbols. As I
mentioned, placing "\&" in front of a word does not
actually seem to prevent that word from being
hyphenated. At least not with the groff I've been
testing with (v.1.18.1). And after experimenting with
many other inline escapes and combinations of escapes,
I have not been able to find any that can actually
prevent hyphenation.

The only thing that does work reliably is to do this:

.hy 0
someSymbolicName
.hy

That is, to use the ".hy" request instead of an escape.
I am considering implementing that, but first I want to
ask you how important or valuable you would judge that
behavior to be, given that there is now the alternative
of disabling hyphenation globally (which is, by the
way, what all of the perl man pages do).

So, if/when you have time, please let me know if the
man.hyphenate option is "good enough" and/or whether
you think it will be good enough for others. If not, I
will add try to add the behavior using the ".hy"
request, and test it and see how it works.

I expect there will be some problems with the ".hy" way
that that I may make cause some undesirable side
effects in some contexts. But short of that, I don't
see any other potential way to implement it that will
work reliably.

[Michael(tm) Smith]

Logged In: YES
user_id=118135

Ryan,

Please ignore what I wrote previously about the \% not
working as expected. My default environment is
LANG=ja_JP.eucJP and I was testing with that. It
appears that handling of \% is borked in that environment.

If I set LANG=C, everything works fine.

After the 1.69.0 release, I will implement the change
you have suggested, using \% to prevent symbols (or
"computer inlines") from being hyphenated.

--Mike

[Michael(tm) Smith]

Logged In: YES
user_id=118135

A change for this issue has been added to the current codebase.
Please test the change with the latest snapshot from:

http://docbook.sourceforge.net/snapshots/

[Michael(tm) Smith]

Logged In: YES
user_id=118135

I have checked in some final changes related to this.

Now, by default, even when hyphenation is enabled
(globally), hyphenation is suppressed for "computer
inlines" (currently, just classname, constant, envar,
errorcode, option, replaceable, userinput, type,
varname -- but probably need to add more) and for
filenames, and for URLs from Ulink.

It can be (re)enabled using the
man.hyphenate.computer.inlines,
man.hyphenate.filenames, and man.hyphenate.urls params.

Also, as I mentioned earlier, I can't implement
anything that add the "\:" escape to output, because it
is not backward compatible with old roff ("AT&T troff",
as it is sometimes referred to).