Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#122 man: Prevent hyphenation of symbols

output: manpages
closed-fixed
XSL (122)
5
2005-11-16
2005-02-16
hofschnr
No

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.

Discussion

  • hofschnr
    hofschnr
    2005-02-17

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

     
    Attachments
  • 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.

     
  • 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

     
  • 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/

     
  • 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).

     
    • status: open --> closed-fixed
     
    • labels: 681486 -->
    • summary: Prevent hyphenation of symbols --> man: Prevent hyphenation of symbols
     
    • labels: --> XSL
    • milestone: --> output: manpages