Re: Patches to run makeinfo on snarfed libguile docstrings

[Dirk Herrmann]

On Mon, 25 Sep 2000, Neil Jerram wrote:

> This would be quite easy to implement.  To indicate a paragraph break,
> you could either leave a blank line like this:
> 
>    "Break a long sentence into paragraphs."
>    ""
>    "@example"
>    "(break-sentence s)"
>    "@end example"
> 
> or, to save valuable lines of code, use an explicit newline:
> 
>    "Break a long sentence into paragraphs.\n"
>    "@example"
>    "(break-sentence s)"
>    "@end example"
> 
> But how does this line-breaking relate to the discussion that we had
> on the list a few months ago?  We'd better go back and check the
> archives first.  (I guess one disadvantage of taking out one newline
> per line is that, if we ever wanted to use the ANSI C interpretation
> of these strings, which just concatenates the strings, the
> concatenation would be wrong.)

Right, to get the right concatenation, you would have to put a blank at
the end of each line (or at the beginning of consecutive lines).  But this
is still less annoying than the \n stuff, and should be as easy to check
automatically.  If done this way, the ANSI C representation would be one
long line for each paragraph, followed by a (double?) newline.

The difference from a comment-maintaining point of view is, that you could
just take the comment written in emacs, and the only thing you'd have to
insert were \"s.  Now you have to put in those and also have to replace
the blanks at the end of the line with "\n" characters.  If you later want
to change the text, you first undo these steps and after editing apply
them again.  :-(

To make missing blanks visually apparent, the following layout could be
used:

    "This is a long paragraph, which continues across"
    " several lines.  Thus, every new line is started"
    " with a blank.  This is nice to read, since the"
    " beginning of a new paragraph is apparent to the"
    " reader.  Paragraph breaks are displayed with two"
    " newline characters.\n\n"
    "The next paragraph starts at the first char again. "
    " However, a single \\n indicates a line break"
    " within the paragraph, for example to show some"
    " lines of code:\n"
    "  @code{(help help)}\n"
    " All these lines, however, belong to the same"
    " paragraph."

Now, you have a valid ANSI C representation, that displays an empty line
for a paragraph break (as TeX users are used to) and also shows line
breaks within a paragraph nicely.  A problematic thing here is the
handling of dots that end a sentence:  If these appear at the end of a
line, you would have to provide an additional blank.

In any case, you are right that it would make sense to reread the
discussion.  But, that discussion was mostly theoretical.  Now we do have
some experience with the documentation system, which may lead to a
different view on old arguments.

Best regards
Dirk