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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
<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.
</para>
<para>
You can quickly validate your edits with <command>make</command>:
</para>
<screen>
$ cd /path/to/nixpkgs/nixos/doc/manual
$ make
</screen>
<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>
<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
<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>
|