Appendix B. Contributing to the NetBSD guide

Table of Contents
B.1 Translating the guide
B.2 Sending contributions
B.3 SGML/DocBook template

There is a 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 stuff.

Whatever your level of expertise with NetBSD, you can contribute to the development of this guide. This appendix explains how you can contribute to the NetBSD guide 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 me. 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.

If you have some spare time, you could translate the guide into another language.

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

B.1 Translating the guide

If you want to translate the guide the first thing to do is, as already said, to contact me or to write to the mailing list. There are several possible scenarios:

Even if a translation is already available, it is always necessary to keep it up do date with respect to the master version when new material is added or corrections are made: you could become the mantainer of a translation.

B.1.1 What you need to start a translation

In order to translate the guide you must get the guide sources. Send an e-mail to me and I'll send you the latest sources, makefiles, etc.

In short, all you need is:

  • the guide sources

  • a text editor, such as vi or emacs.

Note: don't start working with HTML or other formats: it will be very difficult to convert you work to SGML/DocBook, the format used by the NetBSD guide.

B.1.2 Writing SGML/DocBook

In order to translate the guide you don't need to learn SGML/DocBook: get the SGML/DocBook sources and work directly on them, in order to reuse the existing format (i.e. tags) in your work. For example, to translate the previous note, you would do the following:

  1. load the english source of the current chapter, ap-contrib.sgml, in your editor.

  2. find the text of the previous note. You will see something like:

    <note>
      <para>
        don't start working with HTML or other formats:
        it will be very difficult to convert you work
        to SGML/DocBook, the format used by the NetBSD
        guide.
      </para>
    </note>
    
  3. add your translation between the tags, after the english version. The text now looks like this:

    <note>
      <para>
        don't start working with HTML or other formats:
        it will be very difficult to convert you work
        to SGML/DocBook, the format used by the NetBSD
        guide.
        your translation goes here
        your translation goes here
        your translation goes here
      </para>
    </note>
    
  4. delete the four lines of english text between the tags leaving your translation.

    <note>
      <para>
        your translation goes here
        your translation goes here
        your translation goes here
      </para>
    </note>
    

When you write the translation please use the same indentation and formatting style of the original text. See Section B.3 for an example.

One problem that you will probably face when writing the DocBook text is that of national characters (eg. accented letters like "è"). You can use these characters in your source document but it's preferable to replace them with SGML entities. For example, "è" is written as "&egrave;". Of course this makes your source text difficult to write and to read; the first problem, writing, can be solved using a good editor with macro capabilities. Vi and emacs, which are very popular choices, both have this feature and you can map the accented keys of you keyboard to generate the required entities automatically. For example, for vi you can put a line like the following in your .exrc file:

map! è &egrave;

Appendix C explains how to install the software tools to generate HTML and other formats from the DocBook sources. This is useful if you want to check your work (i.e. make sure you didn't inadvertedly delete some tag) or to see what the output looks like, but it is not a requirement for a translation. If you don't want to install the software tools, send me the sources and I'll check them and create the various output formats.

B.2 Sending contributions

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 it to send it to me via e-mail. If you plan to write a substantial amount of text, such as a section or a chapter, you can choose among many formats:

B.3 SGML/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: