Help: Manual links with custom text
As discussed !7873 (merged) when an RST file has :manual:
reference with custom text it is rendered with a monospace font.
Personally, I'd prefer to see in monospace font links to the particular man page (e.g., cmake(1)
) but custom text (e.g., :manual:'build system <cmake-buildsystem(7)>'
) better readable with "normal" font.
In the mentioned MR, there was a commit to replace :manual:
with :doc:
. I totally agree that it is harder to write and error-prone but easier to read the rendered docs ;-)
Nowadays CMake docs have:
$ grep -E -nir --exclude-dir={.git,build} ':manual:`[^`]+ <.*\([17]\)>`' * | wc -l
288
times where :manual:
used w/ custom text (most of the time it's generator expressions text). A bit more generic grep
shows that some other roles also use the custom text:
$ grep -E -nir --exclude-dir={.git,build} ':(manual|command|prop.*):`[^`]+ <[^>]+>`' * | wc -l
353
I propose modifying the Utilities/Sphinx/cmake.py
and adding one/some more roles. I see the following three options here:
- Add
:manlink:
(or any better name :) role to be used for links with custom text:This is the link to :manual:`cmake(1)` and this is the same :manlink:`with custom text <cmake(1)>`.
:manual:
is used with custom text. - Add
:man:
role to use with "short" (and rendered monospace) links:This is the link to :man:`cmake(1)` and this is the same :manual:`with custom text <cmake(1)>`.
:manual:
is used w/o custom text. - Since the docs have other than
:manual:
links with custom text, it's possible to add smth like:auto:
(or any better name :) to be used instead of links to man/prop/command:This is the link to :manual:`cmake(1)` and this is the same :auto:`with custom text <cmake(1)>`. It's possible to reference an :auto:`arbitrary CMake command <message>` or e.g., :auto:`target property <prop_tgt:CXX_STANDARD>`.
Having a different role it's gonna be easy to add CSS rules to the cmake.css
to render 'em whatever we like style.
@brad.king What do you think?
P.S. I can make an MR for this.