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.
If you want to translate the guide the first thing to do is, as already said, to contact me or to write to the [email protected] 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 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.
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.
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:
load the english source of the current chapter, ap-contrib.sgml, in your editor.
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>
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>
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 "è". 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! è è
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.
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:
SGML/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 SGML format.
HTML; handwritten HTML (i.e. written with a text editor) is preferred over automatically generated HTML because it is easier to convert. There is no real advantage in using HTML except that it gives a better idea of you want your text to look like. Another small benefit is that the HTML text probably already contains the required entities for accented characters, etc.
other formats are also accepted if you really can't use any of the previous ones.
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.