pyrox.dev
nixos-manual: Add a chapter about writing documentation
It's more about the practical side of DocBook-wrangling than anything
else.
+1
nixos/doc/manual/development/development.xml
+1
nixos/doc/manual/development/development.xml
···
14
<xi:include href="sources.xml" />
15
<xi:include href="writing-modules.xml" />
16
<xi:include href="building-parts.xml" />
17
+
<xi:include href="writing-documentation.xml" />
18
<xi:include href="building-nixos.xml" />
19
<xi:include href="nixos-tests.xml" />
20
<xi:include href="testing-installer.xml" />
+147
nixos/doc/manual/development/writing-documentation.xml
+147
nixos/doc/manual/development/writing-documentation.xml
···
···
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>
82
+
Keep 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>