Merge pull request #17622 from rvl/nixos-manual-writing-documentation

Add documentation about writing NixOS documentation

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

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>

nixos/modules/services/editors/emacs.xml

@@ -43,9 +43,10 @@
     <title>Installing <application>Emacs</application></title>
 
     <para>
-      Emacs can installed in the normal way for Nix (see <xref
-      linkend="sec-package-management" />). In addition, a NixOS
-      <emphasis>service</emphasis> can be enabled.
+      Emacs can be installed in the normal way for Nix (see
+      <xref linkend="sec-package-management" />).
+      In addition, a NixOS <emphasis>service</emphasis>
+      can be enabled.
     </para>
 
     <section>
@@ -564,6 +565,55 @@ services.emacs.install = true;
       &lt;RET&gt; nixos-rebuild &lt;RET&gt;.</literal>
     </para>
   </section>
+
+  <section xml:id="sec-emacs-docbook-xml">
+    <title>Editing DocBook 5 XML Documents</title>
+    <para>
+      Emacs includes <link
+      xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,
+      a major-mode for validating and editing XML documents.
+      When editing DocBook 5.0 documents, such as
+      <link linkend="book-nixos-manual">this one</link>,
+      nXML needs to be configured with the relevant schema, which is
+      not included.
+    </para>
+
+    <para>
+      To install the DocBook 5.0 schemas, either add
+      <varname>pkgs.docbook5</varname> to
+      <varname>environment.systemPackages</varname> (<link
+      linkend="sec-declarative-package-mgmt">NixOS</link>), or run
+      <literal>nix-env -i pkgs.docbook5</literal>
+      (<link linkend="sec-ad-hoc-packages">Nix</link>).
+    </para>
+
+    <para>
+      Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file:
+      <example xml:id="ex-emacs-docbook-xml">
+        <title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
+        <programlisting language="xml"><![CDATA[
+<?xml version="1.0"?>
+<!--
+  To let emacs find this file, evaluate:
+  (add-to-list 'rng-schema-locating-files "~/.emacs.d/schemas.xml")
+-->
+<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
+  <!--
+    Use this variation if pkgs.docbook5 is added to environment.systemPackages
+  -->
+  <namespace ns="http://docbook.org/ns/docbook"
+             uri="/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
+  <!--
+    Use this variation if installing schema with "nix-env -iA pkgs.docbook5".
+  <namespace ns="http://docbook.org/ns/docbook"
+             uri="../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
+  -->
+</locatingRules>
+]]></programlisting>
+    </example>
+  </para>
+
+  </section>
 </section>
 
 </chapter>