Appendix B. Contributing to the NetBSD guide

Table of Contents

B.1. Sending contributions
B.2. XML/DocBook template

There is an interest for both introductory and advanced documentation on NetBSD: this is probably a sign of the increased popularity of this operating system and of a growing user base. It is therefore important to keep adding new material to this guide and improving the existing text.

Whatever your level of expertise with NetBSD, you can contribute to the development of this guide. This appendix explains how, and what you should know before you start.

If you are a beginner and you found this guide helpful, please send your comments and suggestions to . For example, if you tried something described here and it didn't work for you, or if you think that something is not clearly explained, or if you have an idea for a new chapter, etc: this type of feedback is very useful.

If you are an intermediate or advanced user, please consider contributing new material to the guide: you could write a new chapter or improve an existing one.

Whatever you choose to do, don't start working before having contacted us, in order to avoid duplicating efforts.

B.1. Sending contributions

The sources for the NetBSD guide can be found in CVS under htdocs/docs/guide.

If you want to contribute some material to the guide you have several options, depending on the amount of text you want to write. If you just want to send a small fix, the easiest way to get it into the guide is to send it as a diff to the existing sources to via e-mail, although you should feel free to send any small changes or suggestions there as well.

If you plan to write a substantial amount of text, such as a section or a chapter, you can choose among many formats:

  • XML/DocBook; this is the preferred format. If you choose to use this format, please get the guide sources and use them as a template for the indentation and text layout, in order to keep the formatting consistent.

  • text; if the formatting is kept simple, it is not difficult to convert text to XML format.

  • other formats are also accepted if you really can't use any of the previous ones.

B.2. XML/DocBook template

For the guide I use a formatting style similar to a program. The following is a template:

<chapter id="chap-xxxxx">
  <title>This is the title of the chapter</title>

  <para>
    This is the text of a paragraph.  This is the text of a paragraph.
    This is the text of a paragraph.  This is the text of a paragraph.
    This is the text of a paragraph.
  </para>

  <!-- ============================================================= -->

  <sect1>
    <title>This is the title of a sect1</title>

    <para>
      This is the text of a paragraph.  This is the text of a paragraph.
      This is the text of a paragraph.  This is the text of a paragraph.
      This is the text of a paragraph.
    </para>

    <!-- ........................................................... -->

    <sect2>
      <title>This is the title of a sect2</title>

      <para>
	A sect2 is nested inside a sect1.
      </para>
    </sect2>

  </sect1>

  <!-- ============================================================= -->

  <sect1>
    <title>This is the title of another sect1</title>

    <para>
      An itemized list:
      <itemizedlist>
	<listitem>
	  <para>
	    text
	  </para>
	</listitem>
	<listitem>
	  <para>
	    text
	  </para>
	</listitem>
      </itemizedlist>
    </para>

  </sect1>
</chapter>

The defaults are:

  • two spaces for each level of indentation

  • lines not longer than 72 characters.

  • use separator lines (comments) between sect1/sect2.