nixos docs: format =)
This commit is contained in:
Graham Christensen
@@ -3,157 +3,147 @@
|
||||
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>
|
||||
|
||||
<title>Writing NixOS Documentation</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>
|
||||
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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
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>
|
||||
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">
|
||||
<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>
|
||||
<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>
|
||||
|
||||
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
|
||||
<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>
|
||||
Issue</link> and someone will handle the conversion to XML for you.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Creating a Topic</title>
|
||||
|
||||
<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>
|
||||
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>
|
||||
Keep the following guidelines in mind when you create and add a topic:
|
||||
<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>
|
||||
|
||||
<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
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
Reference in New Issue
Block a user