Subject: Some comments
From: [email-masked] (Matt Welsh)
To: Linux Documentation Project writers <[email-masked]>
Date: Wed, 16 Nov 1994 22:57:48 -0500

First of all, this list has moved to a new list-server; from what
]I understand it's transparent to you folks but just FYI.

Also, there are a few bugs in Linuxdoc-SGML, I know. I hope
that someone can tackle them once and for all. The major things
are:
        1) Some inconsistencies with &num; &dollar; and other
           special characters. I'm all for preprocessing the source
           before sending it to format to change # to &num; and
           so on. 

	   Folks, you MUST format your SGML HOWTOs and run
	   LaTeX/nroff/etc. on them before sending them to me.
	   I can't tell you how many times someone forgot to use &num;
	   to get `#'. TeX dies when you do this! I have to edit
	   the SGML source by hand to locate the problem. It's a real
	   mess. For now, try your best to fix these things before
	   sending the source to me; it makes my life easier.
	   In the future, let's think of ways to get around having
	   to use &num; &dollar; and so forth for most characters.
	   (&amp; etc. will have to stay.) There *is* a way to
	   have a "short map" in the SGML DTD which does this
	   conversion for you automatically, and it works for a 
	   number of characters already. See if you can nail the rest,
	   or preprocess them out.

	2) You can't use "." on the beginning of a line. Not even
	   in <verb>. nroff thinks that you're trying to use
	   a request. I have tried to get around this in a number
	   of ways, haven't been successful. Thought that I could
	   prepend spaces in the source when I find a "." at
	   the beginning of the line; the SGML formatter
	   gets rid of these before sending to nroff. 
	   One idea is to have a new character, &null; ,
	   which gets converted to " " or just "" in all 
	   target formats. This would prevent that pass-thru problem.

	3) Problems with section headings being too long; they get
	   tro be mysteriously "wrapped" at least in the nroff
	   conversion. Look at the Ftape-HOWTO (not your fault, Kai!
	   Just an example of where it happens). 

	4) Various sundry HTML conversion problems; now mostly fixed?
	   Problems with 8-bit chars and html2html? I haven't tried
	   this but have heard about it. 

	5) nroff leaves a lot of whitespace at the end of the document;
	    this is easy to fix with an ugly Perl script that I have.
	    That script sahould be part of the postprocess for nroff
	    in ASCII mode.

Please, bring up your comments/complaints/bugs about Linuxdoc-SGML;
I want to get these things addressed and soon! The system works
but is mostly based on an older experimental SGML parser, and a lot
of other code that I didn't write but have been preprocessing/postprocessing
around problems in. It might be best to come up with a simple Perl tool which 
does the parsing and translation for *just our format*. In that way
we get around the whole general idea of the SGML which is made
to use "any" DTD ; that's why we have all of that &num; garbage
floating around. I'd like to strip down the system and customize it for
the task at hand. Generally, we have a system where 

<tag>

gets translated into something different based on the target
format. Of course you also need an "end tag" for everything;
the current system does a lot of implicit end-tags at
newlines, etc. We could write something like this from scratch, I think,
and it would work much better and be easier to maintain (although
more restricted, in some sense).

Comments?
mdw