#16 Improve handling of comments

closed-accepted
nobody
None
5
2005-07-18
2005-07-14
No

["comments.patch" file attached/uploaded]

The attached patch attempts to improve handling of
"converted" comments. It turns them into "real" roff
comments and normalizes them such that they are always
preceded by, and followed by, a single newline.

It also updates the regexp used for "uncommenting" them
to create the _clisp.1 file.

Tested on my system after updating my CLISP CVS
sandbox, and everything seems to work as expected.

Discussion

  • patch file for improving comment handling

     
    Attachments
  • Sam Steingold
    Sam Steingold
    2005-07-15

    Logged In: YES
    user_id=5735

    I committed the man.xsl patch as is.
    I committed a different Makefile patch which appears to work.
    Please test.
    BTW, why do the numeric references appear before the term
    and not after it?
    e.g.
    [12]\&\fIenvironment variable\fR
    instead of
    \&\fIenvironment variable\fR[12]

     
  • Logged In: YES
    user_id=118135

    > I committed the man.xsl patch as is.
    > I committed a different Makefile patch which appears to work.
    > Please test.

    I see that in the patch I submitted, I had
    been careless and changed SGML_UNCOMMENT when I should
    have changed ROFF_UNCOMMENT. I wasn't thinking about
    the effects on the HTML build.

    Anyway, I just tested with your Makefile and output is
    fine. Thanks, and please feel free to close this out.

    > BTW, why do the numeric references appear before the term
    > and not after it?
    > e.g.
    > [12]\&\fIenvironment variable\fR
    > instead of
    > \&\fIenvironment variable\fR[12]

    For a couple of reasons. First, that's the way that
    lynx and other curses-based browsers seem to do it if
    you turned link-numbering one. And second, I plan to
    also support output for Footnote, which generates a
    number in square brackets wherever you put in.

    Footnote output is already partially supported. Try
    putting a Footnote somewhere in your doc and run in
    through the manpages stylesheet. You'll get a [1] in
    your output for first, a [2] for the second, etc.

    (Currently, that generated marker all you will get.
    Meaning, the Footnote contents won't actually show up
    anywhere. I plan to have a FOOTNOTES section generated
    in ourput, before the REFERENCES section, but I have
    not added it yet. The fact that the footnote markers
    get generated now is just a sort of side effect of the
    fact that the manpages stylesheets import the HTML
    stylesheets, so it just generates the markers in the
    same way the HTML stylesheets do. But the mechanism the
    HTML stylesheets used for collecting and printing the
    actual Footnote content does not automatically "port"
    to man output; hence, you get no Footnote contents.)

    So, consider the following:

    <ulink url="http://bar.org">foo</ulink><footnote
    ><para>baz</para></footnote>

    Suppose that is both the first Ulink in the doc and
    the second Footnote. In output, you currently get:

    [1]foo[2]

    If I generated the Ulink markers after the text, you'd
    get:

    foo[1][2]

    Which would be ambiguous unless you happened to know
    that link reference come before footnote markers. If
    you didn't know that, you couldn't tell whether to in
    the FOOTNOTES section for the 2nd footnote or the 1st,
    or look in the REFERENCES sectin for the 2nd
    link/reference or the 1st.

    I guess one way to deal with it would be to have link
    references rendered with parens or braces or something
    around them. But consider:

    foo(1)[2]

    Now it looks like I have a footnote #2 about a foo(1)
    command.

    So maybe braces:

    foo{1}[2]

    Which, though it is unambiguous, does not look so
    great, IHMO.

    So, it seems better to just output the link numbers
    before the text, especially since there seems to be a
    convention of doing it that way in other tools such as
    lynx.

     
  • Sam Steingold
    Sam Steingold
    2005-07-17

    Logged In: YES
    user_id=5735

    reference is a kind of footnote!!!
    section NOTES = section REFERENCES + section FOOTNOTES

    <ulink url="http://bar.org">foo</ulink><footnote
    ><para>baz</para></footnote>
    ==>
    foo[1][2]

    NOTES
    [1] see http://bar.org
    [2] bar

     
  • Logged In: YES
    user_id=118135

    I have created a new tracker item. Let's use that for
    further discussion about the footnote handling.

    http://sourceforge.net/tracker/index.php?func=detail&aid=1240032&group_id=21935&atid=516914

    > reference is a kind of footnote!!!
    > section NOTES = section REFERENCES + section FOOTNOTES
    >
    > <ulink url="http://bar.org">foo</ulink><footnote
    > ><para>baz</para></footnote>
    > ==>
    > foo[1][2]
    >
    > NOTES
    > [1] see http://bar.org
    > [2] bar

    The problem with that is, footnotes in manpages would
    then end up with different numbers than the footnotes
    in HTML and PDF output.

     
  • Sam Steingold
    Sam Steingold
    2005-07-18

    • status: open --> closed-accepted
     
  • Logged In: YES
    user_id=118135

    Sam, FWIW, I have come around to agreeing with you that
    footnotes and ulinks ought to be listed and numbered
    together in a single NOTES section in man-page output from
    the DocBook XSL stylesheets. There is a precedent in that if
    you set the ulink.footnotes param for XSL-FO output, it
    causes ulinks to be listed and numbered along with footnotes
    (in FO/PDF output).