1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" 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 xml:id="sec-writing-docs-building-the-manual">
<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"><literal>nixos/doc/manual</literal></link>
subdirectory of the Nixpkgs repository.
</para>
<para>
You can quickly validate your edits with <literal>make</literal>:
</para>
<programlisting>
$ cd /path/to/nixpkgs/nixos/doc/manual
$ nix-shell
nix-shell$ make
</programlisting>
<para>
Once you are done making modifications to the manual, it’s
important to build it before committing. You can do that as
follows:
</para>
<programlisting>
nix-build nixos/release.nix -A manual.x86_64-linux
</programlisting>
<para>
When this command successfully finishes, it will tell you where
the manual got generated. The HTML will be accessible through the
<literal>result</literal> symlink at
<literal>./result/share/doc/nixos/index.html</literal>.
</para>
</section>
<section xml:id="sec-writing-docs-editing-docbook-xml">
<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. Here is an example of Pandoc invocation to convert
GitHub-Flavoured MarkDown to DocBook 5 XML:
</para>
<programlisting>
pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
</programlisting>
<para>
Pandoc can also quickly convert a single
<literal>section.xml</literal> 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 xml:id="sec-writing-docs-creating-a-topic">
<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:
</para>
<itemizedlist>
<listitem>
<para>
The NixOS
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
element is in <literal>nixos/doc/manual/manual.xml</literal>.
It includes several
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
which are in subdirectories.
</para>
</listitem>
<listitem>
<para>
Store the topic file in the same directory as the
<literal>part</literal> to which it belongs. If your topic is
about configuring a NixOS module, then the XML file can be
stored alongside the module definition <literal>nix</literal>
file.
</para>
</listitem>
<listitem>
<para>
If you include multiple words in the file name, separate the
words with a dash. For example:
<literal>ipv6-config.xml</literal>.
</para>
</listitem>
<listitem>
<para>
Make sure that the <literal>xml:id</literal> value is unique.
You can use abbreviations if the ID is too long. For example:
<literal>nixos-config</literal>.
</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>
</section>
<section xml:id="sec-writing-docs-adding-a-topic">
<title>Adding a Topic to the Book</title>
<para>
Open the parent XML file and add an <literal>xi:include</literal>
element to the list of chapters with the file name of the topic
that you created. If you created a <literal>section</literal>, you
add the file to the <literal>chapter</literal> file. If you
created a <literal>chapter</literal>, you add the file to the
<literal>part</literal> file.
</para>
<para>
If the topic is about configuring a NixOS module, it can be
automatically included in the manual by using the
<literal>meta.doc</literal> attribute. See
<xref linkend="sec-meta-attributes" /> for an explanation.
</para>
</section>
</chapter>
|
