[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Authors guide material

I wrote up a couple of things for the Gnome list because somebody was
griping about the docs that came with Balsa (a gnome-based mailer).  Each
has clips from the file Balsa.sgml, with some comments and modifications.  I
think that things similar to this would be well suited for the Authors
Guide.  Now that I've written a couple of sections/articles/chapters, other
people will give me ideas of the other guidelines that we need, and/or start
writing some themselves.  I wrote this up in plain text, because that's the
best format for email.  If there were to go into out Authors Guide, they
should be Docbook-ized.
	Greg

Gregory Leblanc               A+ Certified Technician
Concordia University          http://www.cu-portland.edu
Network Support Specialist    gleblanc@cu-portland.edu
--- Begin Message --- 
!!!!!WARNING!!!!!
This message contained an electronic signature.
The message was intentionally routed past virus checking systems.
The message or attachment may contain a virus. USE CAUTION.
!!!!!WARNING!!!!!
2
--- Begin Message --- 
-----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-----


-- 
        FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq
         To unsubscribe: mail gnome-doc-list-request@gnome.org with 
                       "unsubscribe" as the Subject.
--- End Message ---
--- End Message ---
--- Begin Message --- 
!!!!!WARNING!!!!!
This message contained an electronic signature.
The message was intentionally routed past virus checking systems.
The message or attachment may contain a virus. USE CAUTION.
!!!!!WARNING!!!!!
2
--- Begin Message --- 
-----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-----


-- 
        FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq
         To unsubscribe: mail gnome-doc-list-request@gnome.org with 
                       "unsubscribe" as the Subject.
--- End Message ---
--- End Message ---