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.
+
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.
+
+
+
+
+
+
+
+
+
+
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml
index 544e4a1076f4..bcaa8b8df3d8 100644
--- a/nixos/modules/services/editors/emacs.xml
+++ b/nixos/modules/services/editors/emacs.xml
@@ -43,9 +43,10 @@
Installing <application>Emacs</application>
- Emacs can installed in the normal way for Nix (see ). In addition, a NixOS
- service can be enabled.
+ Emacs can be installed in the normal way for Nix (see
+ ).
+ In addition, a NixOS service
+ can be enabled.
@@ -564,6 +565,55 @@ services.emacs.install = true;
<RET> nixos-rebuild <RET>.
+
+
+ Editing DocBook 5 XML Documents
+
+ Emacs includes nXML,
+ a major-mode for validating and editing XML documents.
+ When editing DocBook 5.0 documents, such as
+ this one,
+ nXML needs to be configured with the relevant schema, which is
+ not included.
+
+
+
+ To install the DocBook 5.0 schemas, either add
+ pkgs.docbook5 to
+ environment.systemPackages (NixOS), or run
+ nix-env -i pkgs.docbook5
+ (Nix).
+
+
+
+ Then customize the variable rng-schema-locating-files to include ~/.emacs.d/schemas.xml and put the following text into that file:
+
+ nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)
+
+
+
+
+
+
+
+]]>
+
+
+
+