Re: [cc65] Patch for linuxdoc documentation

Uz creates only HTML documents.  Spiro tried to create all of the formats.
Those error messages came from the text and GNU Info backends.  Those
backends aren't developed as much as the HTML and Tex ones.

From: "Spiro Trikaliotis"; on Sunday, January 18, 2009; at 09:26 AM -0500
>
> (BTW: does anyone know how I can debug such issues?  The linuxdoc tools
> present some arbitrary line numbers which do not reflect the actual
> line numbers in the source file.  Thus, it is always a blind guess.)

LinuxDoc's tools are adopted from other packages.  They are strung together
into "filter pipes."  Those line-numbers are describing the output from one
of the intermediate programs in the pipe (in the other package, they
described a disk file).  Those numbers are useless to us.

>
> What did I fix?
>
> 1. lynx.sgml: Some 'R' and the like have been changed to `R'.
>
> 5. apple2.sgml, apple2enh.sgml:  Same as in 1.
>
> 2. co65.sgml:  LinuxDoc does not like the title "Examples: ..." -- it
>    seems it does not like the colon.  I replaced it with "Examples -
>    ...".
>
> 3. cbm510.sgml, cbm610.sgml:  There are two <sect1> with the name
>    "Interrupts".  Although they appear in different <sect>, it seems
>    LinuxDoc does not like that.  I renamed one of the <sect1>,
>    in order to fix that.
>
> 4. ca65.sgml:
>    a. Like cbm510.sgml with <sect1> of "Overview".
>    b. I replaced some '...' with `...' (at first, I thought this was the
>       problem, but I was wrong here).
>    c. The weird errors are fixed by adding some (empty) comments at the
>       end of some lines.  To make them easily recognisable, I added "SRT"
>       (<!--SRT -->).  Please, don't ask me *why* that fixes those issues;
>       but, it fixes them, anyway.

Only 2, 3, and 4a are bugs in the CC65 documents.  LinuxDoc uses the
"makeinfo" command to create the final document.  That program cannot make
menues and navigation headers if there are duplicate labels.  And, it
doesn't like colons in labels because it needs to use colons to separate the
different parts of a menu-line.

1, 5, 4b, and 4c are two bugs in LinuxDoc.

I don't know where the first bug is; but, I know a very simple work-around
for it.  We see those kinds of error messages if an apostrophe is the first
non-blank character on a SGML source line.  Therefore, putting something in
front of apostrophes will avoid that problem.  So ...

In the apple2 documents, move the word "message" from the previous line down
to a spot in front of 'FAILED.

We traditionally have formatted the SGML sources for an 80-column screen.
In "lynx.sgml", the "Keyboard" paragraph has some empty space on its right
side.  Tell your editor to re-format (justify) that paragraph (within 80
columns).  Text will flow into the empty place, the apostrophes will be
moved, the error messages will disappear, and the document will be created
correctly.

As Spiro noticed, the apostrophes in "ca65.sgml" don't cause any trouble.
In fact, two of them _must not_ be changed, because they sit in example
code; CA65 requires apostrophes in character literals.

The "<newline>"-tag bug is caused by a patch to a LinuxDoc mapping file.  It
should not have been done!  You should "remove" it.  Find the
"share/linuxdoc-tools/dist/linuxdoc-tools/groff/mapping" file.  Go to
line 228.  You will see three lines that start with "newline".  The first
one is commented out; the second one is the bad patch.  So, uncomment the
first one; and, comment out the second one.  A second file,
"latin1/mapping", either is linked to "groff/mapping", or it is a copy
(depending on whether or not the file-system has links).  If it is a copy,
then fix it, too.

That's it!  LinuxDoc should be able to make CC65's text and info documents
without complaints.

(I never have touched the Tex format.  How well does LinuxDoc build it?)

----------------------------------------------------------------------
To unsubscribe from the list send mail to majordomo@musoftware.de with
the string "unsubscribe cc65" in the body(!) of the mail.