commit ce6b1a4f8f9cbbb7fd2d1c637bcc39fff1ef49df · pyrox.dev/nixpkgs

+71 -1
doc/contributing/contributing-to-documentation.chapter.md
···

       1
       1
        
       # Contributing to this documentation {#chap-contributing}

     

       2
       2
        
       

     

       3
       3
       -
       The DocBook sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository.

     

       3
       3
       +
       The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to [Markdown](#sec-contributing-markup).

     

       4
       4
        
       

     

       5
       5
        
       You can quickly check your edits with `make`:

     

       6
       6
        
       

     
···

       22
       22
        
       ```

     

       23
       23
        
       

     

       24
       24
        
       If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.

     

       25
       25
       +
       

     

       26
       26
       +
       ## Syntax {#sec-contributing-markup}

     

       27
       27
       +
       

     

       28
       28
       +
       As per [RFC 0062](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

     

       29
       29
       +
       

     

       30
       30
       +
       Additionally, the following syntax extensions are currently used:

     

       31
       31
       +
       

     

       32
       32
       +
       - []{#ssec-contributing-markup-anchors}

     

       33
       33
       +
         Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).

     

       34
       34
       +
       

     

       35
       35
       +
         It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:

     

       36
       36
       +
       

     

       37
       37
       +
         ```markdown

     

       38
       38
       +
         ## Syntax {#sec-contributing-markup}

     

       39
       39
       +
         ```

     

       40
       40
       +
       

     

       41
       41
       +
       - []{#ssec-contributing-markup-anchors-inline}

     

       42
       42
       +
         **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).

     

       43
       43
       +
       

     

       44
       44
       +
         They are defined using a hybrid of the link syntax with the attributes syntax known from headings, called [bracketed spans](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/bracketed_spans.md):

     

       45
       45
       +
       

     

       46
       46
       +
         ```markdown

     

       47
       47
       +
         - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.

     

       48
       48
       +
         ```

     

       49
       49
       +
       

     

       50
       50
       +
       - []{#ssec-contributing-markup-admonitions}

     

       51
       51
       +
         **Admonitions**, set off from the text to bring attention to something.

     

       52
       52
       +
       

     

       53
       53
       +
         It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):

     

       54
       54
       +
       

     

       55
       55
       +
         ```markdown

     

       56
       56
       +
         ::: {.warning}

     

       57
       57
       +
         This is a warning

     

       58
       58
       +
         :::

     

       59
       59
       +
         ```

     

       60
       60
       +
       

     

       61
       61
       +
         which renders as

     

       62
       62
       +
       

     

       63
       63
       +
         > ::: {.warning}

     

       64
       64
       +
         > This is a warning.

     

       65
       65
       +
         > :::

     

       66
       66
       +
       

     

       67
       67
       +
         The following are supported:

     

       68
       68
       +
       

     

       69
       69
       +
           - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)

     

       70
       70
       +
           - [`important`](https://tdg.docbook.org/tdg/5.0/important.html)

     

       71
       71
       +
           - [`note`](https://tdg.docbook.org/tdg/5.0/note.html)

     

       72
       72
       +
           - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)

     

       73
       73
       +
           - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)

     

       74
       74
       +
       

     

       75
       75
       +
       - []{#ssec-contributing-markup-definition-lists}

     

       76
       76
       +
         [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:

     

       77
       77
       +
       

     

       78
       78
       +
         ```markdown

     

       79
       79
       +
         pear

     

       80
       80
       +
         :   green or yellow bulbous fruit

     

       81
       81
       +
       

     

       82
       82
       +
         watermelon

     

       83
       83
       +
         :   green fruit with red flesh

     

       84
       84
       +
         ```

     

       85
       85
       +
       

     

       86
       86
       +
         which renders as

     

       87
       87
       +
       

     

       88
       88
       +
         > pear

     

       89
       89
       +
         > :   green or yellow bulbous fruit

     

       90
       90
       +
         >

     

       91
       91
       +
         > watermelon

     

       92
       92
       +
         > :   green fruit with red flesh

     

       93
       93
       +
       

     

       94
       94
       +
       For contributing to the legacy parts, please see [DocBook: The Definitive Guide](https://tdg.docbook.org/) or the [DocBook rocks! primer](https://web.archive.org/web/20200816233747/https://docbook.rocks/).