Re: Documentation templates and references

[Gregory Leblanc <gleblanc cu-portland edu>]

Telsa Gwynne wrote:
> 
> 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.

Coming from doing a lot of programming on an Apple IIc, I do these by
default, and I have to agree that they're generally good practices.  I
don't ever use tag minimization, it doesn't save much work, and it makes
things impossibly hard to read.  

> 
> 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?

Well, other than it being an invalid identifier, no.  I'm pretty sure
that Davenport never had anything to do with 3.1, they moved DocBook to
Oasis much eariler than that.

> 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.

I'm surprised that it did anything at all with that identifier in
there.  You might take a peek at your catalog files to see what DTDs you
have on your system, so that you know immediately from looking at a
source SGML file whether or not you can do anything with it.  

> 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.</></></></></>
>      </>
>    </>


Putting multiple </> tags together is a REALLY bad practice, how is one
supposed to know what they appply to?  A general rule for tag
minimization (if you use it at all) is use it ONLY for short inline
elements, not for things like <section>.  

> 
> 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.

After both of us ranting, we have one small section of the
templates/authors guide written!  Thanks Telsa!  Depending on how busy I
get today, I can try to write up two or three paragraphs on tag
minimization.  I'll take some of the material here, reference this
archived message, and some borrow some more material from what Norm has
to say about this in his book.

> 
> 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!

After compiling it a couple of months ago, I'm waiting on Evolution.  Go
Gnome-mailer!  Documentation is good, but only if you can read it. 
Perhaps the SGML source just hasn't been updated in a while (although
that means that the content probably hasn't been updated either).
	Greg