List of changes we would like to upstream?

[jdillard]

Is there a list of changes to Docutils we would like to try to work on and potentially upstream to Docutils?

I bring this up because I thought it would be nice to have nested markup (at least in my use case of using substitutions in hyperlinks): sphinx-doc/sphinx#489

Which lead me to this page: https://docutils.sourceforge.io/docs/dev/todo.html

Should we break that page up in to a series of issues on a repo somewhere in this org? Once the issue are created and "staged", they could be moved to the appropriate repo: https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/transferring-an-issue-to-another-repository

[brechtm]

Should we break that page up in to a series of issues on a repo somewhere in this org? Once the issue are created and "staged", they could be moved to the appropriate repo: https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/transferring-an-issue-to-another-repository

I would avoid creating a huge list of things we'll probably never get to 😄. If you want to start work on a particular bugfix/feature, I'd suggest simply creating a new issue in reStructuredText/docutils to collect information and discuss the implementation. Perhaps it would be good idea to enable discussions on that project as well to allow for extended discussion?

I bring this up because I thought it would be nice to have nested markup (at least in my use case of using substitutions in hyperlinks): sphinx-doc/sphinx#489

I understand this is a particularly hairy feature to add. I'm personally not convinced of the value of this, but I have to admit I haven't given this much thought yet. My gut feeling is that if you need nested inline markup, you're perhaps doing direct styling instead of semantic tagging, which you probably should avoid.

For example, if you want something to appear bold and italic in the output, you should introduce a new role describing the semantics of this markup, e.g. :stronger: and apply the styling using a stylesheet. This of course ignores cases where you want to apply a role to a substring of a string with another role applied, so I'm not sure how useful that advice is in practice. We should try to come up with some use cases and see how these can be handled without nested inline markup.

The particular example you linked to above can be achieved, albeit rather unwieldy, like this:

.. |bbb| replace:: **banana**

.. |somelink| replace:: aaa |bbb| ccc
.. _somelink: http://www.python.org

|somelink|_

EDIT Note that while nested inline markup is not possible in reStructuredText, I think you can represent it in a docutils document tree. Therefore, you could define a custom role that implements it. This could work with existing builders, provided they support nested inline markup (the HTML and rinohtype builders do, AFAIK). For example:

Here is some :nested:`*nested **inline** markup*`.

This could be expanded to (pseudoxml):

<paragraph>
    Here is some
    <emphasis>
        nested
        <strong>
            inline
        markup

Of course, you would be responsible for properly parsing whatever is inside that nested content, but you are free to limit what is supported.