Code change:
Contributors working on improving the nixpkgs manual would be redirected to the . This section is not up-to-date with all the syntax features supported by , forcing contributors to look for use examples over the whole manual. The same markdown syntax is used to write and generate the NixOS manual. However, this manual does not make any mention of the supported syntax. This makes it hard to contribute to the NixOS manual with relative isolation from the nixpkgs manual. Update in Nixpkgs manual to include reference material and examples on all the syntax features supported by . Link in Nixos manual for completion. [x] remove references to in the . : [x] remove references to in the . [x] add a redirecting to the syntax section in . [x] add reference to lack of support for [x] add reference to support [x] add reference to support [x] add reference to support [x] add reference to support [x] add reference to support [x] add reference to support [x] add reference to support [x] add reference to support () () )

Related discussion:
text: 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`. <del> ## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml} For general information on how to write in DocBook, see [DocBook 5: The Definitive Guide](https://tdg.docbook.org/tdg/5.1/). 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 [](#sec-emacs-docbook-xml). [Pandoc](https://pandoc.org/) 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: ```ShellSession 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 too difficult. In this case, submit your documentation updates in a [GitHub Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will handle the conversion to XML for you. ## Creating a Topic {#sec-writing-docs-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`](https://tdg.docbook.org/tdg/5.0/book.html) element is in `nixos/doc/manual/manual.xml`. It includes several [`parts`](https://tdg.docbook.org/tdg/5.0/book.html) 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 {#sec-writing-docs-adding-a-topic} Open the parent CommonMark file and add a line 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 [](#sec-meta-attributes) for an explanation. </del>