Table of Contents
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 <www@NetBSD.org>.
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.
If you want to translate the guide the first thing to do is,
as already said, to contact <www@NetBSD.org> or to
write to the <netbsd-docs@NetBSD.org> 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.
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.
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.
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:
load the english source of the current chapter,
ap-contrib.xml, in
your editor.
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>
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>
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
“è”.
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! è è
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 <www@NetBSD.org>
and we'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 <www@NetBSD.org>
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.
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.