From 4908d7bf205e2687eb53fc5de4bef0b7c3f8282e Mon Sep 17 00:00:00 2001 From: Rodney Lorrimar Date: Tue, 9 Aug 2016 21:24:04 +0100 Subject: [PATCH] nixos-manual: Add a chapter about writing documentation It's more about the practical side of DocBook-wrangling than anything else. --- nixos/doc/manual/development/development.xml | 1 + .../development/writing-documentation.xml | 147 ++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 nixos/doc/manual/development/writing-documentation.xml diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 2983c76c770b..108967d287be 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -14,6 +14,7 @@ NixOS. + 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 @@ + + +Writing NixOS Documentation + + + 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. + + +
+Building the Manual + + The DocBook sources of the are in the + nixos/doc/manual + 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: + + nix-build nixos/release.nix -A manual.x86_64-linux + + + + When this command successfully finishes, it will tell you where the + manual got generated. The HTML will be accessible through the + result symlink at + ./result/share/doc/nixos/index.html. + +
+ +
+Editing DocBook XML + + + For general information on how to write in DocBook, see + + DocBook 5: The Definitive Guide. + + + + 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 . + + + + Pandoc can generate + DocBook XML from a multitude of formats, which makes a good starting + point. + + + Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML + pandoc -f markdown_github -t docbook5 docs.md -o my-section.md + + + Pandoc can also quickly convert a single + section.xml to HTML, which is helpful when + drafting. + + + + Sometimes writing valid DocBook is simply too difficult. In this + case, submit your documentation updates in a GitHub + Issue and someone will handle the conversion to XML for you. + +
+ +
+Creating a Topic + + + You can use an existing topic as a basis for the new topic or create a topic from scratch. + + + +Keep the following guidelines in mind when you create and add a topic: + + + + The NixOS book + element is in nixos/doc/manual/manual.xml. + It includes several + parts + which are in subdirectories. + + + + Store the topic file in the same directory as the part + to which it belongs. If your topic is about configuring a NixOS + module, then the XML file can be stored alongside the module + definition nix file. + + + + If you include multiple words in the file name, separate the words + with a dash. For example: ipv6-config.xml. + + + + Make sure that the xml:id value is unique. You can use + abbreviations if the ID is too long. For example: + nixos-config. + + + + 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. + + + + + +
+ +
+Adding a Topic to the Book + + + Open the parent XML file and add an xi:include + element to the list of chapters with the file name of the topic that + you created. If you created a section, you add the file to + the chapter file. If you created a chapter, you + add the file to the part file. + + + + If the topic is about configuring a NixOS module, it can be + automatically included in the manual by using the + meta.doc attribute. See for an explanation. + + +
+ + + + + + +