diff options
author | Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com> | 2023-10-30 13:17:47 +0000 |
---|---|---|
committer | Silvan Mosberger <silvan.mosberger@tweag.io> | 2024-01-25 16:33:35 +0100 |
commit | a63b9c15c9d81cebb9cedc0c7fe767e3ce9589ae (patch) | |
tree | 6acfb7fdb11b3ccba414aab283393218448d1f36 /nixos/doc/manual/development/writing-documentation.chapter.md | |
parent | b23ce8c1edb4c5e7df99840b0141998bff911b77 (diff) |
doc: Update manuals bespoke syntax
doc: add figure definition to bespoke syntax reference doc: add example definition to bespoke syntax reference doc: add footnote definition to beskpoke syntax reference The usage of footnotes in the manuals is not the one documented in markdown-it-py: https://python-markdown.github.io/extensions/footnotes/ doc: add inline comment definition to beskpoke syntax reference doc: add typographic replacements to beskpoke syntax reference doc: Fix rendering of bespoke syntax reference doc: remove references to DocBook in the NixOS manual doc: add entry on lack of HTML support doc: Minor improvement doc: update typographic replacements entry in beskpoke syntax reference doc: add link reference definitions to beskpoke syntax reference doc: fix footnote definition in beskpoke syntax reference doc: Minor improvements from code review Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
Diffstat (limited to 'nixos/doc/manual/development/writing-documentation.chapter.md')
-rw-r--r-- | nixos/doc/manual/development/writing-documentation.chapter.md | 64 |
1 files changed, 1 insertions, 63 deletions
diff --git a/nixos/doc/manual/development/writing-documentation.chapter.md b/nixos/doc/manual/development/writing-documentation.chapter.md index 3d9bd318cf339..2e9dffd22ba8b 100644 --- a/nixos/doc/manual/development/writing-documentation.chapter.md +++ b/nixos/doc/manual/development/writing-documentation.chapter.md @@ -7,7 +7,7 @@ worthy contribution to the project. ## Building the Manual {#sec-writing-docs-building-the-manual} -The DocBook sources of the [](#book-nixos-manual) are in the +The sources of the [](#book-nixos-manual) are in the [`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the Nixpkgs repository. @@ -29,65 +29,3 @@ 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 {#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. |