pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-writing-documentation">
6
7<title>Writing NixOS Documentation</title>
8
9<para>
10 As NixOS grows, so too does the need for a catalogue and explanation
11 of its extensive functionality. Collecting pertinent information
12 from disparate sources and presenting it in an accessible style
13 would be a worthy contribution to the project.
14</para>
15
16<section>
17<title>Building the Manual</title>
18<para>
19 The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
20 <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
21 subdirectory of the Nixpkgs repository. If you make modifications to
22 the manual, it's important to build it before committing. You can do
23 that as follows:
24
25 <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
26</para>
27
28<para>
29 When this command successfully finishes, it will tell you where the
30 manual got generated. The HTML will be accessible through the
31 <filename>result</filename> symlink at
32 <filename>./result/share/doc/nixos/index.html</filename>.
33</para>
34</section>
35
36<section>
37<title>Editing DocBook XML</title>
38
39<para>
40 For general information on how to write in DocBook, see
41 <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">
42 DocBook 5: The Definitive Guide</link>.
43</para>
44
45<para>
46 Emacs nXML Mode is very helpful for editing DocBook XML because it
47 validates the document as you write, and precisely locates
48 errors. To use it, see <xref linkend="sec-emacs-docbook-xml"/>.
49</para>
50
51<para>
52 <link xlink:href="http://pandoc.org">Pandoc</link> can generate
53 DocBook XML from a multitude of formats, which makes a good starting
54 point.
55
56 <example xml:id="ex-pandoc-xml-conv">
57 <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
58 <screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
59 </example>
60
61 Pandoc can also quickly convert a single
62 <filename>section.xml</filename> to HTML, which is helpful when
63 drafting.
64</para>
65
66<para>
67 Sometimes writing valid DocBook is simply too difficult. In this
68 case, submit your documentation updates in a <link
69 xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
70 Issue</link> and someone will handle the conversion to XML for you.
71</para>
72</section>
73
74<section>
75<title>Creating a Topic</title>
76
77<para>
78 You can use an existing topic as a basis for the new topic or create a topic from scratch.
79</para>
80
81<para>
82Keep the following guidelines in mind when you create and add a topic:
83
84<itemizedlist>
85 <listitem><para>
86 The NixOS <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
87 element is in <filename>nixos/doc/manual/manual.xml</filename>.
88 It includes several
89 <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
90 which are in subdirectories.
91 </para></listitem>
92
93 <listitem><para>
94 Store the topic file in the same directory as the <tag>part</tag>
95 to which it belongs. If your topic is about configuring a NixOS
96 module, then the XML file can be stored alongside the module
97 definition <filename>nix</filename> file.
98 </para></listitem>
99
100 <listitem><para>
101 If you include multiple words in the file name, separate the words
102 with a dash. For example: <filename>ipv6-config.xml</filename>.
103 </para></listitem>
104
105 <listitem><para>
106 Make sure that the <tag>xml:id</tag> value is unique. You can use
107 abbreviations if the ID is too long. For example:
108 <varname>nixos-config</varname>.
109 </para></listitem>
110
111 <listitem><para>
112 Determine whether your topic is a chapter or a section. If you are
113 unsure, open an existing topic file and check whether the main
114 element is chapter or section.
115 </para></listitem>
116
117</itemizedlist>
118
119</para>
120</section>
121
122<section>
123<title>Adding a Topic to the Book</title>
124
125<para>
126 Open the parent XML file and add an <varname>xi:include</varname>
127 element to the list of chapters with the file name of the topic that
128 you created. If you created a <tag>section</tag>, you add the file to
129 the <tag>chapter</tag> file. If you created a <tag>chapter</tag>, you
130 add the file to the <tag>part</tag> file.
131</para>
132
133<para>
134 If the topic is about configuring a NixOS module, it can be
135 automatically included in the manual by using the
136 <varname>meta.doc</varname> attribute. See <xref
137 linkend="sec-meta-attributes"/> for an explanation.
138</para>
139
140</section>
141
142
143
144
145
146
147</chapter>