<< Back to man.ChinaUnix.net

Appendix B. Contributing to the NetBSD guide

Table of Contents

B.1. Translating the guide
B.1.1. What you need to start a translation
B.1.2. Writing XML/DocBook
B.2. Sending contributions
B.3. XML/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 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.

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 us, 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 or to write to the mailing list. There are several possible scenarios:

  • someone else is already working on a translation into your language; you could probably help him.

  • nobody is currently working on a translation into your language, but some chapters have already been translated and you can translate the remaining chapters.

  • you start a new translation. Of course you don't need to translate all the guide: this is a big effort, but if you start translating one or two chapters it'll be a good starting point for someone else.

Even if a translation is already available, it is always necessary to keep it up to 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 short, all you need is:

  • the guide sources. They are part of “htdocs”, check it out from (anonymous) CVS like you would check out “src” or “pkgsrc” as described in Chapter 26, Obtaining sources by CVS.

  • a text editor, such as vi or emacs.

Important

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

B.1.2. Writing XML/DocBook

In order to translate the guide you don't need to learn XML/DocBook; get the XML/DocBook sources of the NetBSD guide 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.xml, in your editor.

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

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

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

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

When you write the translation please use the same indentation and formatting style of the original text. See Section B.3, “XML/DocBook template” for an example.

One problem that you will probably face when writing the DocBook text is that of national characters (e.g. accented letters like “è”). You can use these characters in your source document but it's preferable to replace them with XML 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 your 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, Getting started with XML/DocBook 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 your patches and sources to and we'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 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:

  • 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.3. 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.