Plan for docutils 0.21 release

[chrisjsewell]

docutils version 0.21cr1 has just been pre-released (https://pypi.org/project/docutils/0.21rc1/), with the plan to release 0.21 proper in ~two weeks (thanks @grubert!)

For changes see: https://docutils.sourceforge.io/HISTORY.html#changes-since-0-21-rc1
(you may notice me and @AA-Turner are mentioned as contributors 😁)

We already test against the HEAD of docutils and, from a quick look at the changelog, nothing jumps out at me as requiring any change to sphinx.
So perhaps it is just a case, of changing docutils>=0.18.1,<0.21 allow 0.21?
If so:

1. Should this be done only in the next major sphinx release (8.x)?
2. Should we drop support for docutils 0.18 and is there any "compatibility" code to remove?

cc @sphinx-doc/developers

[picnixz]

Personally, I don't mind it. However, even if we do change the requirement, we still don't have a PyPi release so... I'm not sure it would help a lot. But yes, I'd prefer making it in the next major version (just to be on the safe side).

There is some portion of the code that is 0.18 specific because of a bug in 0.18 and 0.18.1 (but not in 0.17 and not in 0.19) in sphinx.util.du19_footnotes. Otherwise, I think that between 0.18 and 0.19 there are not much differences so it should be fine. However, since I never checked this personally, I cannot say for sure that we will be incompatible for some reasons.

[grubert]

if you test against the HEAD there is nothing ahead and this frees me from maintaining a test setup of sphinx ... many thanks dropping 3.8 support and manpage output for references is in discussion but these should not harm anyone ... right? thanks

…

On Wed, 27 Mar 2024 at 01:53, Chris Sewell ***@***.***> wrote: docutils version 0.21cr1 has just been pre-released, with the plan to release 0.21 proper in ~two weeks (thanks @grubert <https://github.com/grubert>!) For changes see: https://docutils.sourceforge.io/HISTORY.html#changes-since-0-21-rc1 (you may notice me and @AA-Turner <https://github.com/AA-Turner> are mentioned as contributors 😁) We already test against the HEAD of docutils and, from a quick look at the changelog, nothing jumps out at me as requiring any change to sphinx. So perhaps it is just a case, of changing docutils>=0.18.1,<0.21 allow 0.21? If so: 1. Should this be done only in the next major sphinx release (8.x)? 2. Should we drop support for docutils 0.18 and is there any "compatibility" code to remove? cc @sphinx-doc/developers <https://github.com/orgs/sphinx-doc/teams/developers> — Reply to this email directly, view it on GitHub <#12209>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHEYA6D6J76ONHAWKTBBATY2IDBDAVCNFSM6AAAAABFJ6AIFSVHI2DSMVQWIX3LMV43ASLTON2WKOZSGIYDSNRQGA2TGNI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[picnixz]

dropping 3.8 support and manpage output for references is in discussion

We don't really care about 3.8 support since we've already dropped it on our side, but do you mean that there won't be any reference nodes for manpage? (or am I misunderstanding something?)

[grubert]

there is no output for reference nodes from the manpage writer ... before 0.21 never was ... no one complained, i had the question, how to typeset url-references in roff, open for long time, no one cared currently i choose to render in <> brackets in the writer .UR/.UE macros are only good for terminals supporting OSC8 escape sequence and ... long story there .MT/.ME "mailto" macros too and ... we might get a better idea if the thing is out ... i hope cheers

…

On Wed, 27 Mar 2024 at 12:38, Bénédikt Tran ***@***.***> wrote: dropping 3.8 support and manpage output for references is in discussion We don't really care about 3.8 support since we've already dropped it on our side, but do you mean that there won't be any reference nodes for manpage? (or am I misunderstanding something?) — Reply to this email directly, view it on GitHub <#12209 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHEYA2445R7YR4XPIOMMT3Y2KOQZAVCNFSM6AAAAABFJ6AIFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRSGU2TSNZUGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[picnixz]

there is no output for reference nodes from the manpage writer ... before
0.21
never was ... no one complained,
i had the question, how to typeset url-references in roff, open for long
time, no one cared

Oh I wasn't aware of that! we recently added this in Sphinx #12108 so I think we will continue supporting OSC8 (at least for Sphinx). I didn't work directly on the manpage builder but I don't know the effects if you remove the visit_references from the Translator class upstream (or if you choose to ignore it completely and leave an empty body method). AFAICT, currently visit_references seems to use \fI and \fP for such nodes. I'm not an expert for that area but I think if we handle references nodes ourselves in our custom writer, it should be fine, right?

By the way, is there a way to detect whether a terminal supports OSC 8 programatically or not? because if there is one, it would help us.

[grubert]

as far as i understand sphinx overwrites visit_reference, but i did not see overwriting depart_reference might be necessary as 0.21 changes these two

…

On Wed, 27 Mar 2024 at 13:58, Bénédikt Tran ***@***.***> wrote: there is no output for reference nodes from the manpage writer ... before 0.21 never was ... no one complained, i had the question, how to typeset url-references in roff, open for long time, no one cared Oh I wasn't aware of that! we recently added this in Sphinx #12108 <#12108> so I think we will continue supporting OSC8 (at least for Sphinx). I didn't work directly on the manpage builder but I don't know the effects if you remove the visit_references from the Translator class upstream (or if you choose to ignore it completely and leave an empty body method). AFAICT, currently visit_references seems to use \fI and \fP for such nodes. I'm not an expert for that area but I think if we handle references nodes ourselves in our custom writer, it should be fine, right? By the way, is there a way to detect whether a terminal supports OSC 8 programatically or not? because if there is one, it would help us. — Reply to this email directly, view it on GitHub <#12209 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHEYAZBGMGNQU45F4RA7DTY2KX43AVCNFSM6AAAAABFJ6AIFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRSG4YDKMJUGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[grubert]

hei

On Wed, 27 Mar 2024 at 13:58, Bénédikt Tran ***@***.***> wrote: By the way, is there a way to detect whether a terminal supports OSC 8 programatically or not? because if there is one, it would help us.

i used man macros .UR/.UE as formatting elements in the manpage writer for references but did not see the URI in my test output (sanbox/manpage) and on console in man -Tps one gets URI and linktext (mandoc -Thtml renders UR/UE to hyperlinks) when piping to "nroff -man " output to a file i see OSC8 ESC]8;; but the terminal does not show the URI so i switched back (for now) to the output one gets from mandoc for .UR/.UE, putting <> around the URI for details i usually ask branden as he is maintainer on groff and in close contact with the mandoc maintainer man supports several devices not only terminals, therefore i am more into letting man do the OSC8 things if man thinks it is a terminal ... which as i understood is not easy to tell all the best e

…

— Reply to this email directly, view it on GitHub <#12209 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHEYAZBGMGNQU45F4RA7DTY2KX43AVCNFSM6AAAAABFJ6AIFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRSG4YDKMJUGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>