nixos-manual: Add a chapter about writing documentation

It's more about the practical side of DocBook-wrangling than anything
else.
This commit is contained in:
Rodney Lorrimar 2016-08-09 21:24:04 +01:00
parent 3de354c73d
commit 4908d7bf20
2 changed files with 148 additions and 0 deletions

View file

@ -14,6 +14,7 @@ NixOS.</para>
<xi:include href="sources.xml" />
<xi:include href="writing-modules.xml" />
<xi:include href="building-parts.xml" />
<xi:include href="writing-documentation.xml" />
<xi:include href="building-nixos.xml" />
<xi:include href="nixos-tests.xml" />
<xi:include href="testing-installer.xml" />

View file

@ -0,0 +1,147 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-writing-documentation">
<title>Writing NixOS Documentation</title>
<para>
As NixOS grows, so too does the need for a catalogue and explanation
of its extensive functionality. Collecting pertinent information
from disparate sources and presenting it in an accessible style
would be a worthy contribution to the project.
</para>
<section>
<title>Building the Manual</title>
<para>
The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
subdirectory of the Nixpkgs repository. If you make modifications to
the manual, it's important to build it before committing. You can do
that as follows:
<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
</para>
<para>
When this command successfully finishes, it will tell you where the
manual got generated. The HTML will be accessible through the
<filename>result</filename> symlink at
<filename>./result/share/doc/nixos/index.html</filename>.
</para>
</section>
<section>
<title>Editing DocBook XML</title>
<para>
For general information on how to write in DocBook, see
<link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">
DocBook 5: The Definitive Guide</link>.
</para>
<para>
Emacs nXML Mode is very helpful for editing DocBook XML because it
validates the document as you write, and precisely locates
errors. To use it, see <xref linkend="sec-emacs-docbook-xml"/>.
</para>
<para>
<link xlink:href="http://pandoc.org">Pandoc</link> can generate
DocBook XML from a multitude of formats, which makes a good starting
point.
<example xml:id="ex-pandoc-xml-conv">
<title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
</example>
Pandoc can also quickly convert a single
<filename>section.xml</filename> to HTML, which is helpful when
drafting.
</para>
<para>
Sometimes writing valid DocBook is simply too difficult. In this
case, submit your documentation updates in a <link
xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
Issue</link> and someone will handle the conversion to XML for you.
</para>
</section>
<section>
<title>Creating a Topic</title>
<para>
You can use an existing topic as a basis for the new topic or create a topic from scratch.
</para>
<para>
Keep the following guidelines in mind when you create and add a topic:
<itemizedlist>
<listitem><para>
The NixOS <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
element is in <filename>nixos/doc/manual/manual.xml</filename>.
It includes several
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
which are in subdirectories.
</para></listitem>
<listitem><para>
Store the topic file in the same directory as the <tag>part</tag>
to which it belongs. If your topic is about configuring a NixOS
module, then the XML file can be stored alongside the module
definition <filename>nix</filename> file.
</para></listitem>
<listitem><para>
If you include multiple words in the file name, separate the words
with a dash. For example: <filename>ipv6-config.xml</filename>.
</para></listitem>
<listitem><para>
Make sure that the <tag>xml:id</tag> value is unique. You can use
abbreviations if the ID is too long. For example:
<varname>nixos-config</varname>.
</para></listitem>
<listitem><para>
Determine whether your topic is a chapter or a section. If you are
unsure, open an existing topic file and check whether the main
element is chapter or section.
</para></listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Adding a Topic to the Book</title>
<para>
Open the parent XML file and add an <varname>xi:include</varname>
element to the list of chapters with the file name of the topic that
you created. If you created a <tag>section</tag>, you add the file to
the <tag>chapter</tag> file. If you created a <tag>chapter</tag>, you
add the file to the <tag>part</tag> file.
</para>
<para>
If the topic is about configuring a NixOS module, it can be
automatically included in the manual by using the
<varname>meta.doc</varname> attribute. See <xref
linkend="sec-meta-attributes"/> for an explanation.
</para>
</section>
</chapter>