[ clisp-Patches-1238558 ] Improve handling of comments

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Patches item #1238558, was opened at 2005-07-15 08:49
Message generated for change (Comment added) made by xmldoc
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=301355&aid=1238558&group_id=1355

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Closed
Resolution: Accepted
Priority: 5
Submitted By: Michael Smith (xmldoc)
Assigned to: Nobody/Anonymous (nobody)
Summary: Improve handling of comments

Initial Comment:
["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.

----------------------------------------------------------------------

>Comment By: Michael Smith (xmldoc)
Date: 2005-09-21 16:45

Message:
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).

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2005-07-18 13:45

Message:
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.

----------------------------------------------------------------------

Comment By: Sam Steingold (sds)
Date: 2005-07-18 02:54

Message:
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

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2005-07-16 13:49

Message:
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.

----------------------------------------------------------------------

Comment By: Sam Steingold (sds)
Date: 2005-07-15 23:40

Message:
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]

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=301355&aid=1238558&group_id=1355