diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml')
| -rw-r--r-- | nixpkgs/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml | 144 |
1 files changed, 0 insertions, 144 deletions
diff --git a/nixpkgs/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml b/nixpkgs/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml deleted file mode 100644 index 079c80060576..000000000000 --- a/nixpkgs/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml +++ /dev/null @@ -1,144 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" 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 xml:id="sec-writing-docs-building-the-manual"> - <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"><literal>nixos/doc/manual</literal></link> - subdirectory of the Nixpkgs repository. - </para> - <para> - You can quickly validate your edits with <literal>make</literal>: - </para> - <programlisting> -$ cd /path/to/nixpkgs/nixos/doc/manual -$ nix-shell -nix-shell$ make -</programlisting> - <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> - <programlisting> -nix-build nixos/release.nix -A manual.x86_64-linux -</programlisting> - <para> - When this command successfully finishes, it will tell you where - the manual got generated. The HTML will be accessible through the - <literal>result</literal> symlink at - <literal>./result/share/doc/nixos/index.html</literal>. - </para> - </section> - <section xml:id="sec-writing-docs-editing-docbook-xml"> - <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. Here is an example of Pandoc invocation to convert - GitHub-Flavoured MarkDown to DocBook 5 XML: - </para> - <programlisting> -pandoc -f markdown_github -t docbook5 docs.md -o my-section.md -</programlisting> - <para> - Pandoc can also quickly convert a single - <literal>section.xml</literal> 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 xml:id="sec-writing-docs-creating-a-topic"> - <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: - </para> - <itemizedlist> - <listitem> - <para> - The NixOS - <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link> - element is in <literal>nixos/doc/manual/manual.xml</literal>. - It includes several - <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link> - which are in subdirectories. - </para> - </listitem> - <listitem> - <para> - Store the topic file in the same directory as the - <literal>part</literal> to which it belongs. If your topic is - about configuring a NixOS module, then the XML file can be - stored alongside the module definition <literal>nix</literal> - file. - </para> - </listitem> - <listitem> - <para> - If you include multiple words in the file name, separate the - words with a dash. For example: - <literal>ipv6-config.xml</literal>. - </para> - </listitem> - <listitem> - <para> - Make sure that the <literal>xml:id</literal> value is unique. - You can use abbreviations if the ID is too long. For example: - <literal>nixos-config</literal>. - </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> - </section> - <section xml:id="sec-writing-docs-adding-a-topic"> - <title>Adding a Topic to the Book</title> - <para> - Open the parent XML file and add an <literal>xi:include</literal> - element to the list of chapters with the file name of the topic - that you created. If you created a <literal>section</literal>, you - add the file to the <literal>chapter</literal> file. If you - created a <literal>chapter</literal>, you add the file to the - <literal>part</literal> file. - </para> - <para> - If the topic is about configuring a NixOS module, it can be - automatically included in the manual by using the - <literal>meta.doc</literal> attribute. See - <xref linkend="sec-meta-attributes" /> for an explanation. - </para> - </section> -</chapter> |