diff options
Diffstat (limited to 'nixos/doc/manual/development/writing-documentation.xml')
| -rw-r--r-- | nixos/doc/manual/development/writing-documentation.xml | 278 |
1 files changed, 140 insertions, 138 deletions
diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml index 59a287717acb..8ecdd1c770f2 100644 --- a/nixos/doc/manual/development/writing-documentation.xml +++ b/nixos/doc/manual/development/writing-documentation.xml @@ -3,145 +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> -<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>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. + </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> + +<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> + <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 +<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 + 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> - - - - - - + </para> + </section> </chapter> |