Subject: Bug#3180: linuxdoc-sgml semantics and formatting problems

From: Ian Jackson <[email-masked]>
Date: Sun, 2 Jun 96 02:26 BST

Package: linuxdoc-sgml
Version: 1.5-2

(To linuxdoc-sgml people: this is a copy of a bug I'm reporting
 against Debian's linuxdoc-sgml package; if you reply CC debian-bugs
 please keep the `Bug#nnnn' or `Re: Bug#nnnn' in the Subject.  Note
 that debian-bugs stuff ends up on our debian-devel mailing list.

 To debian-devel and the package maintainer: I think that most of
 these problems are upstream ones; some may require considerable
 effort to fix, so I'm causing the bug system to CC the linuxdoc-sgml
 mailing list.

 Everyone: Please think about trimming recipients's when replying.)

I've written a part of the new dpkg programmers' manual in
linuxdoc-sgml, and I've come across a number of problems.  Since the
SGML source file so far is only 8K when compressed and uuencoded I've
attached it (after all, the message is 6K without it ...)

It's possible that many of the problems I'm describing are
misunderstandings on my part, in which case I apologise.  I would
point out though that the documentation (guide.sgml) is quite sketchy
and fails to format correctly anyway (looking at the HTML version
installed in the Debian package).

1. There is no tag meaning `this is a metasyntactic variable in an
example', a la <VAR> in HTML.  I've used <IT> for now but this is
obviously suboptimal.  I tried adding a VAR tag to the DTD and seeing
if I could still run the document through at least sgmlcheck by
essentially copying `em' both times it appeared (see my attached
patch), but got a cryptic error message (wrapped by me):
 sgmls: SGML error at /usr/lib/linuxdoc-sgml/dtd/linuxdoc.dtd,
        line 184 in declaration parameter 4:
        Content model token 97: more than GRPGTCNT
         content model tokens; terminated
 sgmls: SGML error at /usr/lib/linuxdoc-sgml/dtd/linuxdoc.dtd,
        line 186 at "<":
        Invalid character(s) ignored; attempting to resume
         DOCTYPE subset
At this point I decided I was well out of my depth and gave up.

I think the <VAR> tag should produce angle brackets (like <this>) in
text and info, <VAR> in HTML and italics in PostScript.  It should
produce \fI in manpages and probably other groffish contexts.

If someone would like to point me in roughly the right direction, or
even better demonstrate to me how to add a tag to the DTD and get it
recognised by all the backends, I'd be much obliged.

2. The <verb> tag doesn't appear to allow you to change font.  The
<quote> tag doesn't appear to follow your own linewrapping.  This
means that there's no way of getting an example laid out as you
present it, but with metasyntactic variables in italics or angle
brackets or whatever and typed text in a fixed-width font.

3. The info formatting is screwed up if you have section headings with
<tt> parts.  That info can't deal with `' in node names is a
deficiency of info which the GNU people know about, but linuxdoc-sgml
should work around it by stripping out the `' when they appear in a
node name.

4. There are unpredictable gaps around <tscreen><verb> blocks.  There
should either be no gap (I would prefer this, or at least like to have
a way to get it) so that you could use them in a running paragraph
              like this
or there should consistently be a gap on both sides or only
afterwards.  (By unpredictable I mean that info produces a gap after,
but HTML a gap on both sides.)  Whether or not there is supposed to be
a gap should be documented; if some of the output formats can't do it
(eg HTML) then fair enough.

5. The cross-referencing mechanism is rendered so differently in all
the output formats that I tried that it's practically impossible to
think of text that's suitable for putting around the <ref...> and in
the name="...".  I'd like to see some markup with which I could
produce:
  see also <A href="...">section 2.3 on wombats</A>.  (HTML)
  see also section 2.3 on wombats (page 23).          (PostScript)
  see also section 2.3 on wombats (line 200).         (Text)
  see also *Note: wombats.                            (Info)
Perhaps I can already do this.  If so then I'd like to see it
documented :-).

6. There are several other oddities with the info formatting.
(a) Right at the start of programmer.info I see:
    \input texinfo
(b) All the bits where I said <em> have come out with `' round them.
    I think something like *this* or _this_ would be more
    appropriate.
(c) List headings (<descrip> <tag> HERE </tag> have `' round them too.
    Is this really appropriate ?
(d) The filename heading before the first node lists a file in /tmp.
    I don't know if this is fixable, but it would be nice if it said
    that the thing came originally from programmer.sgml or whatever.
(f) When formatting using sgml2info I see:
    Making info file `programmer.info' from `/tmp/sgml2info15281tmp2'.
    /tmp/sgml2info15281tmp2:73: Misplaced `{'.
    /tmp/sgml2info15281tmp2:75: Misplaced `}'.

7. There are some oddities with the text formatting.
(a) The table of contents has some mangled entries, possibly it too
    cannot cope with <tt> inside a heading.
(b) The title page/screen/thing is quite cheesy.  A bit more
    whitespace, and having some of it centred and/or underlined (ie
    with a seperate row of characters) would be better.
(c) <em> doesn't show up at all.  How about *this* ?
(d) Section headings come *after* the relevant paragraph !  They also
    don't stand out at all.  Perhaps this is due to my failure to use
    <P> after section headings.  Why can't the SGML parser infer this
    ?  I thought SGML was supposed to be good at that kind of thing.
(e) Footnotes have a rather odd format; it looks deliberate, though.
    I presume there's no better way to do this ?  It would be good at
    least to leave footnotes until after the end of the paragraph.
(f) Cross-references come out with ``'' around them.  Why ?
(g) Using <tscreen> inside a <descrip> resets the indenting.  I
    presume this is very hard to fix.
(h) The existence of a paragraph break after <descrip> entries is
    unpredictable.

8. There was one oddity with the HTML formatting: my section headings
come out with the following paragraph attached.  Interestingly, I can
see from the HTML that is generated that it has spotted the end of the
heading, but it has only put the </A> there and not the </H2>.

I hope noone minds me making these comments.  I'm trying to be helpful
and constructive by supplying bug reports :-).

Thanks,
Ian.

Attached: the patch I made to the DTD to generate that error message,
and then my uuencoded gzipped source file (sorry, but it's 16K
uncompressed).

--- /usr/lib/linuxdoc-sgml/dtd/linuxdoc.dtd	Fri Apr  5 01:45:51 1996
+++ /usr/src/linuxdoc-sgml-1.5/lib/dtd/linuxdoc.dtd	Sun Jun  2 00:49:33 1996
@@ -4,7 +4,7 @@
       modified from QWERTZ.DTD by Tom Gordon -->

 <!entity % emph
-	" em|it|bf|sf|sl|tt|cparam " >
+	" em|var|it|bf|sf|sl|tt|cparam " >

 <!entity % index "idx|cdx" >

@@ -65,6 +65,7 @@

 <!usemap pmap p>
 <!element em - - (%inline)>
+<!element var - - (%inline)>
 <!element bf - - (%inline)>
 <!element it - - (%inline)>
 <!element sf - - (%inline)>

---

From: [email-masked] (Greg Hankins)
Date: Tue, 4 Jun 1996 22:01:29 -0400 (EDT)

> effort to fix, so I'm causing the bug system to CC the linuxdoc-sgml

All of these problems are unfortunately not Debian specific.  These are
all problems with Linuxdoc-SGML, and all are good candidates to be fixed.

Greg

--
Greg Hankins ([email-masked])  |  Georgia Institute of Technology
Computing and Networking Services          |  College of Computing, room 213
+1 404 894 6609                            |  Atlanta, GA 30332-0280
<A HREF="http://www.cc.gatech.edu/staff/h/Greg.Hankins/">Greg Hankins</A>
finger [email-masked] for PGP key