DocBook reader: add support for citerefentry #7433
Conversation
4b8f12d to
fc6b489
Compare
|
I could also add support for converting this AST back to DocBook. And support for rST syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage |
|
Actually, rST parses as Edit: Done that. |
|
Is this element specific to man pages? That certainly isn't clear from the documentation. |
|
As far as I was able to tell, it was originally intended for referring to UNIX manual pages, either part of the same DocBook document as
These days, As per the Processing expectations section of But I do not see much of a difference between reference and manual pages so it makes sense to me to use |
|
Thanks for the info. Somehow it doesn't seem right to me to emit such a rST-specific AST element. Nothing else in he DocBook reader parses into something with class <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>could become Code ("",["citerefentry"],[]) "nix.conf(5)"unless it's important to be able to access the volume number as an attribute. |
|
Yeah, that’s what I had at the start but I liked being able to unify stuff. But I guess we can keep it distinct and use Lua filter when converting between from DocBook to rST. function Code(elem)
elem.classes = elem.classes:map(function (x)
if x == 'citerefentry' then
elem.attributes['role'] = 'manpage'
return 'interpreted-text'
else
return x
end
end)
return elem
endI considered keeping the |
Originally intended for referring to UNIX manual pages, either part of the same DocBook document as refentry element, or external – hence the manvolnum element. These days, refentry is more general, for example the element documentation pages linked below are each a refentry. As per the *Processing expectations* section of citerefentry, the element is supposed to be a hyperlink to a refentry (when in the same document) but pandoc does not support refentry tag at the moment so that is moot. https://tdg.docbook.org/tdg/5.1/citerefentry.html https://tdg.docbook.org/tdg/5.1/manvolnum.html https://tdg.docbook.org/tdg/5.1/refentry.html For greater interoperability, the produced AST matches rST syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage That is intended for manual pages but I do not see much of a difference between reference and manual pages so it makes sense to me to use role=manpage. Especially since this will likely cover the vast majority of uses.
|
It would be nice if pandoc could preserve semantics between formats that support it but yeah, these special classes are not very nice representation. Opened #7437 where it produces |
|
Resolved in #7437. |
For referencing UNIX manual pages https://docbook.org/tdg/en/html-ng/citerefentry.html