Subject: PROPOSAL: Indentation style and other nits
To: None <>
From: Rui Paulo <>
List: netbsd-docs
Date: 07/16/2005 19:00:41
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
	* <para>text</para>, not:
	  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
		<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
	* 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

	  (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

This is just a proposal. If I forgot something or you think something I
said is wrong, please reply. :)

		-- Rui Paulo