diff options
author | Jörg Thalheim <joerg@higgsboson.tk> | 2016-10-09 13:39:08 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2016-10-09 13:39:08 +0200 |
commit | da5c0220aa42e8bde1664463d8b1d2bebc861714 (patch) | |
tree | c0eaa6f787133e7aebad2cde8918e09e6a17044a /nixos/doc/manual/development | |
parent | a3ec0f1593b508e259bb20b3fe185f0f397e41c0 (diff) | |
parent | 4908d7bf205e2687eb53fc5de4bef0b7c3f8282e (diff) | |
download | nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.tar nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.tar.gz nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.tar.bz2 nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.tar.lz nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.tar.xz nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.tar.zst nixlib-da5c0220aa42e8bde1664463d8b1d2bebc861714.zip |
Merge pull request #17622 from rvl/nixos-manual-writing-documentation
Add documentation about writing NixOS documentation
Diffstat (limited to 'nixos/doc/manual/development')
-rw-r--r-- | nixos/doc/manual/development/development.xml | 1 | ||||
-rw-r--r-- | nixos/doc/manual/development/writing-documentation.xml | 147 |
2 files changed, 148 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 7f8a50809b2b..b0364b346577 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -14,6 +14,7 @@ NixOS.</para> <xi:include href="sources.xml" /> <xi:include href="writing-modules.xml" /> <xi:include href="building-parts.xml" /> +<xi:include href="writing-documentation.xml" /> <xi:include href="building-nixos.xml" /> <xi:include href="nixos-tests.xml" /> <xi:include href="testing-installer.xml" /> diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml new file mode 100644 index 000000000000..59a287717acb --- /dev/null +++ b/nixos/doc/manual/development/writing-documentation.xml @@ -0,0 +1,147 @@ +<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. If you make modifications to + the manual, it's important to build it before committing. You can do + that as follows: + + <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen> +</para> + +<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> |