Subject: Re: Some comments
From: [email-masked] (Matt Welsh)
To: Linux Documentation Project writers <[email-masked]>
Date: Mon, 5 Dec 1994 00:39:20 -0500

[email-masked] (Al Longyear) writes:
> Matt suggested reamining it to the PPP-HOWTO. I don't really object to this
> name, however, it really is a FAQ. 

Yes, but people have learned (I think) to associate the name "HOWTO"
with subject documents about Linux  which are available from a certain
place with various formats. FAQs can be seen as a subset of HOWTOs,
of course... but what HOWTO really means is the set of documents which 
the LDP writes and we maintain in this way.

At any rate, if you folks want to change the Linuxdoc-SGML format to 
accomodate things which aren't there, let's do it. As I said I can't
maintain it much at this time, but can pass it off to someone else.
I'd like to not make changes which aren't backwards-compatible, but
that doesn't exclude any new features or formats, of course.

I just realized that there are four negatives in that sentence... I hope
that makes sense. :)

Maybe we could use a <question> and <answer> format for FAQs (which
would make the system more attractive to other FAQ maintainers),
and a <table> format of some kind. The only problem with tables is that
they're tough to do in HTML, but some Perl munging could turn it
into a table to be displayed with <pre>. 

You may have noticed that SGML has some very strict parsing rules, and
we loosen almost all of them to make documents easier to write. I'm thinking
it would be easier in the long run to rewrite the "parser" in Perl.
(I like Perl because it's easier to debug than awk or lexx/yacc programs.)
We don't need real parsing; in fact you could do the translation almost
on the fly. For Linuxdoc nearly every tag (<foo>, </foo>) is mapped
directly to a language element in TeX, HTML, or groff. All we have
is a lookup table such as
	<em>	"{\em"
	</em>	"}"

And so forth. This would really simplify how the system works and let
us adapt the syntax of the formatting language to our needs... getting
rid of all the general SGML features that we don't use (and try to
avoid). For example, "$" can be mapped directly from our parser;
it's harder to get SGML to do that because some characters can't be 
used with "short mappings" (which are used for single-character translations).

The short and short of it is, our docs aren't structured the way SGML
documents were meant to be; we don't explicitly start and end
paragraph sections, for example. Unless it looks like a huge job it might
be easier to do away with the (almost broken) SGML parser and do it
ourselves.

What do you think?