Subject: PROPOSAL: Indentation style and other nits
To: None <netbsd-docs@NetBSD.org>
From: Rui Paulo <rpaulo@NetBSD.org>
List: netbsd-docs
Date: 07/16/2005 19:00:41
Hi,
we have some tips in the NetBSD guide for indentation, but those currently
apply only to the NetBSD guide. Since we don't have no rules for defining,
I propose that we should define some.
My proposal consists in:
* spaces for each level of indentation
* lines not longer than 76 characters (I think you don't have to
follow this rule entirely, but just don't pass the 80 columns
margin).
* <para>text</para>, not:
<para>
text
</para>
This results in <p>\n text\n </p> in the HTML file, I don't
think it is completly okay to have it, but correct me if I'm wrong.
* don't break <ulink>'s -- if needed they can overcome the 72 columns
eg:
<entry><ulink url="../Releases/formal-&release.latest.major;/">&release.latest;</ulink></entry><entry>stable</entry>
* now that Klaus committed it, don't forget to use a proper
<webpage id>
* don't use <ulink>'s for the cvsweb, see
http://mail-index.netbsd.org/www-changes/2005/07/16/0001.html
* use docbook CALS model, not <td><tr>, etc. (see Ports/index.xml)
* if you want a table without title, use <informaltable>
* as you probably know, <programlisting>'s can't be broken easily.
As an example:
<programlisting>DRIVETYPE ide
CYLINDERS 16384
HEADS 16
SECTORS 63
ACCESS "/root/vmware/win2000/disk.mbr" 0 63
ACCESS "/dev/rwd0e" 63 8193087
ACCESS "/dev/rwd0f" 8193213 4176837
</programlisting>
(note the indentation of the start of the tag, and I think there
is no problem about putting the tag in the other line)
* examples: htdocs/Documentation/wscons/index.xml,
Documentation/vmware.xml, Documentation/kernel/programming.xml
You may ask: why worth the trouble? Pretty simple: if you want to diagnose
some problem is easier; if you don't have a browser, reading the XML should
be easy; if you want to modify the XML, it will be easier with proper
indentation.
This is just a proposal. If I forgot something or you think something I
said is wrong, please reply. :)
-- Rui Paulo