Re: Documentation templates and references

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote:
> If these templates already exist, where are they?
... 
> Perhaps we should have (1) a simple template with just the basic tags
> which people use most, and then (2) a more complete GDP reference document
> which lists the proper markups, nomenclature, etc.

If these templates come to pass, may I make a small suggestion?
I realise that people on virtual consoles or people who limit their
windows to 25 lines from top to bottom will hate me for this, but
hear me out.

Please can we suggest that
	(a) Ending tags with </> is a bad idea unless it's clearly
    obvious exactly what it refers to at first glance. Really clearly
    obvious. 
        (b) Lines should try to avoid being more than eighty characters
    long before a carriage return.
        (c) Use lots of whitespace.

I was trying to compile the tarball of Balsa today. Not CVS or anything,
just the "./configure; make; make install" one. It finally barfed for
obscure reasons, but an initial problem I hit was that db2html 
produced over 200 errors and gave up, aborting the make. I had a
poke at the balsa.sgml file to see what had happened. For some
reason, db2html didn't like this at the top:

<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.1//EN" []>

Does anyone see any problems that are obvious there? Is it case-
sensitive or something? I was confused. In the end, I altered the 
"Davenport" to "OASIS" and it removed 95% of the errors. In a fit 
of enthusiasm I decided to remove the rest of the errors. The usual 
"this tag shouldn't be here, this tag doesn't have a start tag, you 
can't have a sect2 starting here" stuff was there. And when I looked,
parts of it looked like this:

       <varlistentry><term>Check Mail Automatically
Every...</><listitem><para>If selected, Balsa will connect
       to your POP3 servers at the given interval and check for mail.
<note><para>Using &quot;0&quot; as
       an interval is a <emphasis>really</> bad idea.</></></></></>
     </>
   </>

One of those </>s was superfluous and removing that, and putting 
a </sect2>, elsewhere fixed a lot of it. But it took -ages-! I found
it extremely hard to work out which </> referred to which tag. I 
ended up having to fill in almost all the end-tags and reformat it
to use about three times the screen space to know where I was -- but 
I really think it was more legible.

Is this something I just have to get used to, or what? It put me
right off using </> for anything, because it gave me a headache
trying to work backwards through seven endtags on the trot.

But that's why I suggest that too many </> tags are bad! They're
hard for new folk, at the very least. It's like counting brackets
or something.

I suppose I should note that it did at least have documentation,
mind you :) And if I could get it to compile, I'd likely be glad
about having the documentation to read!

Telsa