How to use Whitespace.

[Gregory Leblanc <GLeblanc cu-portland edu>]

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

After finishing my example on tag minimization, I realized that
another big part of the reason that the markup wasn't readable was
whitespace.  The code below looks pretty good in emacs sgml mode, but
looks pretty horrible in Outlook (doing work on finding the totally
stupid things that MS did so that Miguel can fix them in Evolution). 
I've slid things over so that they start at the edge of the page, but
everything else is the same as Example 3 in my last episode.  Almost,
everything, I changed the example number, and added a close tag for
sect2.  

EXAMPLE 1

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

If you take the time to be careful about reading this, it's not bad
at all, and quite workable in a highlighting editor.  However, this
isn't always possible, so below I've made some changes so that its
easier to read.

EXAMPLE 1

<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
"0" as 
         an interval is a <emphasis>really</emphasis> bad
idea.</para></para>
         </note></listitem>
      </varlistentry>
   </variablelist>
</sect2>

I couldn't decide which way looked best, so here is a step between
the original and where I stopped.  There are no lines longer than 80
characters, including whitespace.  I have this erie feeling that mail
clients and servers are going to mangle this royally.  :-/  If it
looks like hell, it's not my fault.  Anyway, this one is a bit easier
to use.  Since in these "lists", there is only 1 listitem, it works
out ok.  For most other circumstances, it probably wouldn't look
quite as good.  I've got another example below.


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 "0" as an interval is a 
            <emphasis>really</emphasis> bad
idea.</para></note></para>
         </listitem>
      </varlistentry>

   </variablelist>
</sect2>

I might actually have been a little over-zealous on my use of
whitespace here, but it is pretty clear which elements go where. 
When I got everything into this last format, I realized that I'd
screwed up which end tags I put where and fixed it.  Perhaps I wasn't
paying close enough attention, or perhaps I just read the tags wrong
in going from </> to </endtag>, but however it happened, I fixed it
easiest here.  Anyway, enjoy!
	Greg

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/AwUBOI9rrpLW/u8jW+lnEQJUpQCdHdiaJFGRADdcBwhZRnHzkzBqQJAAoNDh
54QK1/IW+C6XDcoWPmyDze6R
=50Wl
-----END PGP SIGNATURE-----