[Docutils-users] [Feature/Bug] If a role content is empty, it's never called?

[Anil Lakhman]

Hi,

I'm not subscribed to the mailing list, please CC me if possible on the
issue.

I have filed a github issue here replicating the issue:

https://github.com/sphinx-doc/sphinx/issues/2562

Basically, If I add a custom role and pass an empty string within the
backticks, the role is never called, so I don't have a chance to show a
warning or error message. For example the :download: role shows a warning
message if we pass an empty string or space within the backticks.

Am I missing something or is this not possible? (I'm using sphinx)

Here it is in code:


Say I have the following role which converts an icon role into an inline
font awesome icon:

# e.g: Create an inline <span class="fa fa-rocket fa-2x"></span>def
icon_role(role, rawtext, text, lineno, inliner, options={},
content=[]):
options.update({'classes': ["fa-" + x for x in text.split(",")]})
options['classes'].append('fa')
set_classes(options)
node = nodes.inline(**options)
return [node], []
# ... add it - Note i'm using sphinx hence `app`

app.add_role('icon', icon_role)

# Now I use it like so:
:icon:`rocket,2x`

#= <span class="fa fa-rocket"></span>

Issue

# Now say I forget to pass through some text or empty space
# (accidently deleted, forget I had it, etc..)
:icon:`` # No text
:icon:` ` # Space empty text

#= :icon:``
#= :icon:` `

# Notice how it just outputs the role raw, it doesn't seem to even
call `icon_role`
# so I don't have a chance to check the value (and throw a warning)

If the content with backticks is empty, I would like to decide what to do
with the role (output a empty node, throw a warning, place a default icon).

Am I missing something?

The :download: role does this, but I'm finding it confusing as to who it's
implemented. It throws the following error if you pass an empty string.

# Throws an error: WARNING: Inline literal start-string without end-string.
:download:``

# Just outputs the raw role text (I don't have a chance to do anything)
:icon:``

Any Ideas?


You can also reply to this github ticket on sphinx:


https://github.com/sphinx-doc/sphinx/issues/2562


Any help would be very much appreciated! - This could be an excellent
feature for validation, if it doesn't exist already.


Thanks!

[Guenter Milde]

Post by Anil Lakhman
Hi,
I'm not subscribed to the mailing list, please CC me if possible on the
issue.
https://github.com/sphinx-doc/sphinx/issues/2562
Basically, If I add a custom role and pass an empty string within the
backticks, the role is never called, so I don't have a chance to show a
warning or error message.

This is the same for standard roles::

das ist `interpreted`

das ist ` ` nichts

becomes ::

<paragraph>
das ist
<title_reference>
interpreted
<paragraph>
das ist ` ` nichts

and is a consequence of the ``rST inline markup recognition rules`__

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules

Post by Anil Lakhman
For example the :download: role shows a warning
message if we pass an empty string or space within the backticks.

Really? Then parsing happens somehow differently from Docutils
implementation of rst.

Post by Anil Lakhman
Am I missing something or is this not possible? (I'm using sphinx)

...

Post by Anil Lakhman
# Now say I forget to pass through some text or empty space
# (accidently deleted, forget I had it, etc..)
:icon:`` # No text
:icon:` ` # Space empty text
#= :icon:``
#= :icon:` `
# Notice how it just outputs the role raw, it doesn't seem to even
call `icon_role`
# so I don't have a chance to check the value (and throw a warning)
If the content with backticks is empty, I would like to decide what to do
with the role (output a empty node, throw a warning, place a default icon).
Am I missing something?
The :download: role does this, but I'm finding it confusing as to who it's
implemented. It throws the following error if you pass an empty string.
# Throws an error: WARNING: Inline literal start-string without end-string.
:download:``

Does this really happen with

:download:``

It usually happens if there is no end string (and also nothing else), e.g.

:math:`

but not with

:funny:` more text

Post by Anil Lakhman
# Just outputs the raw role text (I don't have a chance to do anything)
:icon:``

Yes, this is not recognized as rST markup (just like e.g. ::

x*y* or :math:` x+2 `

)

I am afraid this is an issue to stay, as it concerns defines rST rules.
You may file an enhancement ticket for recognition of
:something:`` or :something` ` but there is no chance of a quick fix
unfortunately.

Günter



------------------------------------------------------------------------------
Mobile security can be enabling, not merely restricting. Employees who
bring their own devices (BYOD) to work are irked by the imposition of MDM
restrictions. Mobile Device Manager Plus allows you to control only the
apps on BYO-devices by containerizing them, leaving personal data untouched!
https://ad.doubleclick.net/ddm/clk/304595813;131938128;j
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to