On the use of tag minimizations in DocBook

[Gregory Leblanc <GLeblanc cu-portland edu>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

	Tag minimizations should be avoided if at all possible.  The
advantages of tag minimization are few, and the benefits of NOT using
them far outweigh these comforts.  Below are three examples, each
using a different ammount of tag minimization, followed by a short
explanation of what's good/bad about each.  I'm not going to make any
whitespace changes here, although I'll use the same example SGML for
the whitespace example.

This first one is stolen from the Balsa.sgml file in Balsa version
0.6.0.  

EXAMPLE 1

   <sect2 id="cfgtab-mail-servers">
     <title>Mail Servers</>

     <para>This page lets you specify how you get remove POP3 mail,
send mail, etc.</>

     <variablelist>
       <varlistentry><term>Remote Mailbox
Servers</><listitem><para>These are POP3 servers that you recieve
       email from. The three buttons let you create, modify, and
remove records. POP3 mailboxes
       will not show up in the mailbox list.</></></>

       <varlistentry><term>Local Mail
Directrory</><listitem><para>This is the directory that Balsa
       will scan looking for mail folders.</></></>

       <varlistentry><term>Remote SMTP Server</><listitem><para>If
your computer is not equipped with sendmail
       or you do not wish to use it, select this radio button and
enter a hostname to contact via
       SMTP.</></></>

       <varlistentry><term>Local Mail User
Agent</><listitem><para>Balsa will attempt to use sendmail to
       send mail. Unfortunately, you cannot specify the command to
execute right now.</></></>

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

As you can see, with a bit of work, it's possible to understand where
the elements start and end, but just from looking at this, it's not
so obvious.  If I open this file in an editor with decent syntax
highlighting capabilities (emacs with psgml, others), it's much
easier to read, but I still have to count the number of tags that are
open and closed.  Definately not the best SGML that I've ever seen,
but it seems to work (mostly).

EXAMPLE 2

   <sect2 id="cfgtab-mail-servers">
     <title>Mail Servers</>

     <para>This page lets you specify how you get remove POP3 mail,
send mail, etc.</>

     <variablelist>
       <varlistentry><term>Remote Mailbox
Servers</><listitem><para>These are POP3 servers that you recieve
       email from. The three buttons let you create, modify, and
remove records. POP3 mailboxes
       will not show up in the mailbox
list.</para></listitem></varlistentry>

       <varlistentry><term>Local Mail
Directrory</><listitem><para>This is the directory that Balsa
       will scan looking for mail
folders.</para></listitem></varlistentry>

       <varlistentry><term>Remote SMTP Server</><listitem><para>If
your computer is not equipped with sendmail
       or you do not wish to use it, select this radio button and
enter a hostname to contact via
       SMTP.</para></listitem></varlistentry>

       <varlistentry><term>Local Mail User
Agent</><listitem><para>Balsa will attempt to use sendmail to
       send mail. Unfortunately, you cannot specify the command to
execute right now.</para></listitem></varlistentry>

       <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.</para></para></note></listitem></varlistentry>
     </variablelist>

Well, I changed the tags on this one a bit, adding end tags to a lot
of elements.  I left a few elements without end tags, because they
were close enough together to be obvious (only a couple of words in
any tag), and all of the other tags were closed.  This is a bit
easier to read with a syntax highlighting editor, but that's always
going to be the case with markup.  This one is certainly acceptable,
although perhaps not quite ideal.

EXAMPLE 3

   <sect2 id="cfgtab-mail-servers">
     <title>Mail Servers</title>

     <para>This page lets you specify how you get remove POP3 mail,
send mail, etc.</para>

     <variablelist>
       <varlistentry><term>Remote Mailbox
Servers</term><listitem><para>These are POP3 servers that you recieve
       email from. The three buttons let you create, modify, and
remove records. POP3 mailboxes
       will not show up in the mailbox
list.</para></listitem></varlistentry>

       <varlistentry><term>Local Mail
Directrory</term><listitem><para>This is the directory that Balsa
       will scan looking for mail
folders.</para></listitem></varlistentry>

       <varlistentry><term>Remote SMTP
Server<term/><listitem><para>If your computer is not equipped with
sendmail
       or you do not wish to use it, select this radio button and
enter a hostname to contact via
       SMTP.</para></listitem></varlistentry>

       <varlistentry><term>Local Mail User
Agent</term><listitem><para>Balsa will attempt to use sendmail to
       send mail. Unfortunately, you cannot specify the command to
execute right now.</para></listitem></varlistentry>

       <varlistentry><term>Check Mail Automatically
Every...</term><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</emphasis> bad
idea.</para></para></note></listitem></varlistentry>
     </variablelist>

All of the end tags are included in this example.  As you can see,
the changes between Example 3 and Example 3 are fairly minimal.  This
is the easiest, and in my opinion, best, form to have DocBook in,
with regards to tag minimization.  If you're comfortable with using
tag minimizations, feel free to use them as in Example 2, but please
try to stay away from things like Example 1.  


I'll send my Whitespace post in another message a little later today.
	Greg

P.S.  I'm going to put a license on this, for safe keeping.  We'll
have to put this together as something nicer for the thing that I'm
calling an "authors guide" at some point.  First let's get some
content, then somebody can put it together.

This message is Copyright (c) 2000 by Gregory Leblanc.

This message may be reproduced in whole or in part, without fee,
subject to the following restrictions: 

The copyright notice above and this permission notice must be
preserved complete on all complete or partial copies 
Any translation or derived work must be approved by the author in
writing before distribution. 
Small portions may be reproduced as illustrations for reviews or
quotes in other works without this permission notice if proper
citation is given. 

Exceptions to these rules may be granted for academic purposes: Write
to the author and ask. These restrictions are here to protect us as
authors, not to restrict you as learners and educators.

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 6.5.1 for non-commercial use <http://www.pgp.com>

iQA/AwUBOI9XBJLW/u8jW+lnEQIGrwCggll6K6OYCMb4BUIVMxUHT2LhgfcAoI+p
OmVS2jQj6Lcn+MZwaoZt2wW9
=L6yz
-----END PGP SIGNATURE-----