commit c9139dfa1a001e32baa6fea9c9373d80c83e39e9 · pyrox.dev/nixpkgs

+4

doc/Makefile

···

       6
       6
        
       # NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh).

     

       7
       7
        
       # TODO: Remove raw-attribute when we can get rid of DocBook altogether.

     

       8
       8
        
       pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute

     

       9
       9
       +
       # Not needed:

     

       10
       10
       +
       # - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)

     

       9
       11
        
       pandoc_flags = --extract-media=$(pandoc_media_dir) \

     

       10
       12
        
       	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \

     

       13
       13
       +
       	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \

     

       14
       14
       +
       	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \

     

       11
       15
        
       	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \

     

       12
       16
        
       	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart

     

       13
       17

+23

doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua

···

       1
       1
       +
       --[[

     

       2
       2
       +
       Converts Code AST nodes produced by pandoc’s DocBook reader

     

       3
       3
       +
       from citerefentry elements into AST for corresponding role

     

       4
       4
       +
       for reStructuredText.

     

       5
       5
       +
       

     

       6
       6
       +
       We use subset of MyST syntax (CommonMark with features from rST)

     

       7
       7
       +
       so let’s use the rST AST for rST features.

     

       8
       8
       +
       

     

       9
       9
       +
       Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage

     

       10
       10
       +
       ]]

     

       11
       11
       +
       

     

       12
       12
       +
       function Code(elem)

     

       13
       13
       +
         elem.classes = elem.classes:map(function (x)

     

       14
       14
       +
           if x == 'citerefentry' then

     

       15
       15
       +
             elem.attributes['role'] = 'manpage'

     

       16
       16
       +
             return 'interpreted-text'

     

       17
       17
       +
           else

     

       18
       18
       +
             return x

     

       19
       19
       +
           end

     

       20
       20
       +
         end)

     

       21
       21
       +
       

     

       22
       22
       +
         return elem

     

       23
       23
       +
       end

+36

doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua

···

       1
       1
       +
       --[[

     

       2
       2
       +
       Converts AST for reStructuredText roles into corresponding

     

       3
       3
       +
       DocBook elements.

     

       4
       4
       +
       

     

       5
       5
       +
       Currently, only a subset of roles is supported.

     

       6
       6
       +
       

     

       7
       7
       +
       Reference:

     

       8
       8
       +
         List of roles:

     

       9
       9
       +
           https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html

     

       10
       10
       +
         manpage:

     

       11
       11
       +
           https://tdg.docbook.org/tdg/5.1/citerefentry.html

     

       12
       12
       +
         file:

     

       13
       13
       +
           https://tdg.docbook.org/tdg/5.1/filename.html

     

       14
       14
       +
       ]]

     

       15
       15
       +
       

     

       16
       16
       +
       function Code(elem)

     

       17
       17
       +
         if elem.classes:includes('interpreted-text') then

     

       18
       18
       +
           local tag = nil

     

       19
       19
       +
           local content = elem.text

     

       20
       20
       +
           if elem.attributes['role'] == 'manpage' then

     

       21
       21
       +
             tag = 'citerefentry'

     

       22
       22
       +
             local title, volnum = content:match('^(.+)%((%w+)%)$')

     

       23
       23
       +
             if title == nil then

     

       24
       24
       +
               -- No volnum in parentheses.

     

       25
       25
       +
               title = content

     

       26
       26
       +
             end

     

       27
       27
       +
             content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')

     

       28
       28
       +
           elseif elem.attributes['role'] == 'file' then

     

       29
       29
       +
             tag = 'filename'

     

       30
       30
       +
           end

     

       31
       31
       +
       

     

       32
       32
       +
           if tag ~= nil then

     

       33
       33
       +
             return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')

     

       34
       34
       +
           end

     

       35
       35
       +
         end

     

       36
       36
       +
       end

+29

doc/build-aux/pandoc-filters/myst-reader/roles.lua

···

       1
       1
       +
       --[[

     

       2
       2
       +
       Replaces Str AST nodes containing {role}, followed by a Code node

     

       3
       3
       +
       by a Code node with attrs that would be produced by rST reader

     

       4
       4
       +
       from the role syntax.

     

       5
       5
       +
       

     

       6
       6
       +
       This is to emulate MyST syntax in Pandoc.

     

       7
       7
       +
       (MyST is a CommonMark flavour with rST features mixed in.)

     

       8
       8
       +
       

     

       9
       9
       +
       Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point

     

       10
       10
       +
       ]]

     

       11
       11
       +
       

     

       12
       12
       +
       function Inlines(inlines)

     

       13
       13
       +
         for i = #inlines-1,1,-1 do

     

       14
       14
       +
           local first = inlines[i]

     

       15
       15
       +
           local second = inlines[i+1]

     

       16
       16
       +
           local correct_tags = first.tag == 'Str' and second.tag == 'Code'

     

       17
       17
       +
           if correct_tags then

     

       18
       18
       +
             -- docutils supports alphanumeric strings separated by [-._:]

     

       19
       19
       +
             -- We are slightly more liberal for simplicity.

     

       20
       20
       +
             local role = first.text:match('^{([-._+:%w]+)}$')

     

       21
       21
       +
             if role ~= nil then

     

       22
       22
       +
               inlines:remove(i)

     

       23
       23
       +
               second.attributes['role'] = role

     

       24
       24
       +
               second.classes:insert('interpreted-text')

     

       25
       25
       +
             end

     

       26
       26
       +
           end

     

       27
       27
       +
         end

     

       28
       28
       +
         return inlines

     

       29
       29
       +
       end

+25

doc/build-aux/pandoc-filters/myst-writer/roles.lua

···

       1
       1
       +
       --[[

     

       2
       2
       +
       Replaces Code nodes with attrs that would be produced by rST reader

     

       3
       3
       +
       from the role syntax by a Str AST node containing {role}, followed by a Code node.

     

       4
       4
       +
       

     

       5
       5
       +
       This is to emulate MyST syntax in Pandoc.

     

       6
       6
       +
       (MyST is a CommonMark flavour with rST features mixed in.)

     

       7
       7
       +
       

     

       8
       8
       +
       Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point

     

       9
       9
       +
       ]]

     

       10
       10
       +
       

     

       11
       11
       +
       function Code(elem)

     

       12
       12
       +
         local role = elem.attributes['role']

     

       13
       13
       +
       

     

       14
       14
       +
         if elem.classes:includes('interpreted-text') and role ~= nil then

     

       15
       15
       +
           elem.classes = elem.classes:filter(function (c)

     

       16
       16
       +
             return c ~= 'interpreted-text'

     

       17
       17
       +
           end)

     

       18
       18
       +
           elem.attributes['role'] = nil

     

       19
       19
       +
       

     

       20
       20
       +
           return {

     

       21
       21
       +
             pandoc.Str('{' .. role .. '}'),

     

       22
       22
       +
             elem,

     

       23
       23
       +
           }

     

       24
       24
       +
         end

     

       25
       25
       +
       end

+5

doc/contributing/contributing-to-documentation.chapter.md

···

       52
       52
        
       

     

       53
       53
        
         This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).

     

       54
       54
        
       

     

       55
       55
       +
       - []{#ssec-contributing-markup-inline-roles}

     

       56
       56
       +
         If you want to link to a man page, you can use ``{manpage}`nix.conf(5)```, which will turn into {manpage}`nix.conf(5)`.

     

       57
       57
       +
       

     

       58
       58
       +
         This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.

     

       59
       59
       +
       

     

       55
       60
        
       - []{#ssec-contributing-markup-admonitions}

     

       56
       61
        
         **Admonitions**, set off from the text to bring attention to something.

     

       57
       62

+6 -1

nixos/doc/manual/md-to-db.sh

···

       12
       12
        
       # TODO: Remove raw-attribute when we can get rid of DocBook altogether.

     

       13
       13
        
       pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute

     

       14
       14
        
       pandoc_flags=(

     

       15
       15
       -
         # media extraction and diagram-generator.lua not needed

     

       15
       15
       +
         # Not needed:

     

       16
       16
       +
         # - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)

     

       17
       17
       +
         # - media extraction (was only required for diagram generator)

     

       18
       18
       +
         # - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)

     

       19
       19
       +
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua"

     

       20
       20
       +
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua"

     

       16
       21
        
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua"

     

       17
       22
        
         -f "commonmark${pandoc_commonmark_enabled_extensions}+smart"

     

       18
       23
        
         -t docbook