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
|
<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>
|