[DISC] Add `{proof}` as new role

[najuzilu]

I think we should add {proof} as a new role to "replace" the current role which is {proof:ref} . Technically, the two would be interchangeable, similarly to how {math:numref} and {eq} roles are interchangeable.

In addition to this, I think we should also support the following placeholders:

• %s, {number}: int or '' if nonumber == True
• {title}: str or '' if no title was provided

What do others think? @mmcky @AakashGfude @jstac

[jstac]

Just my two cents, but I wish {eq} was {eqref}, analogous to \eqref in LaTeX. As the zen of Python says, explicit is better than implicit. So I like to see the word "ref" there to know that it's a reference.

Hence I favor {proof:ref} over {proof}.

For the other suggestions, is this in response to some unmet need?

I like the philosophy of @choldgraf --- wait until people request features and then solicit PRs or add them as requested.

[mmcky]

I am also in favour of {proof:ref} as it binds to other {proof:<option>} more clearly and makes reading the source markdown easier in my view.

Can you give an example re: placeholders?

[najuzilu]

Here are three examples of how one could use placeholders when referencing labels through proof:ref:

• {proof:ref}`some text %s <label>` where %s will return the number of the node
• {proof:ref}`some text {number} <label>` where {number} will return the number of the node
• {proof:ref}`{title} <label>` where {title} will return the title of the node

The figure directive has similar placeholders (see docs).

I'm more than happy to follow @jstac's suggestion and wait until there's a need for supporting the placeholders.

[mmcky]

oh I see -- that's a nice idea.