Return-Path: owner-LDP-L@cornell.edu
Received: from listproc.mail.cornell.edu (LISTPROC.MAIL.CORNELL.EDU [132.236.56.14]) by keos.Helsinki.FI (8.6.9/H46) with SMTP id IAA26878 for <LARS.WIRZENIUS@CS.HELSINKI.FI>; Thu, 17 Nov 1994 08:23:33 +0200
Received: from host ([127.0.0.1]) by listproc.mail.cornell.edu with SMTP id <90665-6>; Thu, 17 Nov 1994 00:54:24 -0500
Received: from cornell.edu ([132.236.56.6]) by listproc.mail.cornell.edu with SMTP id <91283-7>; Wed, 16 Nov 1994 22:58:12 -0500
Received: from cornell.edu (PHQUERY) by cornell.edu with cornell-phquery id <372759-5>; Wed, 16 Nov 1994 22:58:04 -0500
Received: from thialfi.cs.cornell.edu ([128.84.254.220]) by cornell.edu with SMTP id <372752-5>; Wed, 16 Nov 1994 22:57:53 -0500
Received: from CLOYD.CS.CORNELL.EDU by thialfi.cs.cornell.edu (5.67/I-1.99G)
	id AA17438; Wed, 16 Nov 94 22:57:51 -0500
Received: from THOKK.CS.CORNELL.EDU by cloyd.cs.cornell.edu (5.67/I-1.99F)
	id AA01348; Wed, 16 Nov 94 22:57:59 -0500
Received: by thokk.cs.cornell.edu (5.67/N-0.13aa)
	id AA01266; Wed, 16 Nov 94 22:57:48 -0500
Message-Id: <9411170357.AA01266@thokk.cs.cornell.edu>
Date: 	Wed, 16 Nov 1994 22:57:48 -0500
Reply-To: LDP-L@cornell.edu
Sender: owner-LDP-L@cornell.edu
From: mdw@CS.CORNELL.EDU (Matt Welsh)
To: Linux Documentation Project writers <LDP-L@cornell.edu>
Subject: Some comments
X-To: ldp-l@cornell.edu
X-PH: V4.1@cornell.edu (Cornell Modified) 
X-Mailer: Mail User's Shell (7.2.0 10/31/90)
X-Listprocessor-Version: 7.01 -- ListProcessor by CREN
Content-Length: 3448
Status: RO
X-Status: 

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

