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>
This commit is contained in:
Alejandro Sanchez Medina 2023-10-30 13:17:47 +00:00 committed by Silvan Mosberger
parent b23ce8c1ed
commit a63b9c15c9
3 changed files with 80 additions and 64 deletions

View file

@ -71,6 +71,11 @@ If you **omit a link text** for a link pointing to a section, the text will be s
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
#### HTML
Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
#### Roles #### Roles
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json). If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
@ -265,6 +270,79 @@ You, as the writer of documentation, are still in charge of its content.
_Default:_ the output path's hash. _Default:_ the output path's hash.
``` ```
#### Examples
To define a referenceable figure use the following fencing:
```markdown
:::{.example #an-attribute-set-example}
# An attribute set example
You can add text before
```nix
{ a = 1; b = 2;}
```
and after code fencing
:::
```
Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
Though this is not shown in the rendered documentation on nixos.org.
#### Figures
To define a referencable figure use the following fencing:
```markdown
::: {.figure #nixos-logo}
# NixOS Logo
![NixOS logo](./nixos_logo.png)
:::
```
Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`.
Though this is not shown in the rendered documentation on nixos.org.
#### Footnotes
To add a foonote explanation, use the following syntax:
```markdown
Sometimes it's better to add context [^context] in a footnote.
[^context]: This explanation will be rendered at the end of the chapter.
```
#### Inline comments
Inline comments are supported with following syntax:
```markdown
<!-- This is an inline comment -->
```
The comments will not be rendered in the rendered HTML.
#### Link reference definitions
Links can reference a label, for example, to make the link target reusable:
```markdown
::: {.note}
Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
:::
[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
```
This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
#### Typographic replacements
Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
## Getting help ## Getting help
If you need documentation-specific help or reviews, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on your pull request. If you need documentation-specific help or reviews, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on your pull request.

View file

@ -1,6 +1,6 @@
# Contributing to this manual {#chap-contributing} # Contributing to this manual {#chap-contributing}
The [DocBook] and CommonMark sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository. The sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.
This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup). This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).
You can quickly check your edits with the following: You can quickly check your edits with the following:

View file

@ -7,7 +7,7 @@ worthy contribution to the project.
## Building the Manual {#sec-writing-docs-building-the-manual} ## 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) [`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
subdirectory of the Nixpkgs repository. 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 When this command successfully finishes, it will tell you where the
manual got generated. The HTML will be accessible through the `result` manual got generated. The HTML will be accessible through the `result`
symlink at `./result/share/doc/nixos/index.html`. 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.