Make the separator for the :guilabel: role a configurable character

[kai687]

Is your feature request related to a problem? Please describe.

With #6738, the separator character 'TRIANGULAR BULLET' is not escaped anymore for unicode capable latex engines. Unfortunately, this depends on the font having this character. I use latex_engine = 'xelatex' and the Adobe Source Sans font family which does not have this character.

Describe the solution you'd like

I would like a configuration option to override the default character.

Describe alternatives you've considered

I currently use this code snippet in my conf.py:

def setup(app):
    '''
    modify the `menuselection` role to replace the default character
    `TRIANGULAR BULLET` with `RIGHTWARDS ARROW` as the font that we use
    does not have this character.
    '''
    from docutils.parsers.rst import roles
    from sphinx.roles import GUILabel

    class CustomMenu(GUILabel):
        def run(self):
            self.text = self.text.replace('-->', '\N{RIGHTWARDS ARROW}')
            return super().run()

    roles.register_local_role('menuselection', CustomMenu())

which works as I want, but it feels like a hack.

[tk0miya]

It seems there are one problem and one request. First is about unicode and fonts (refs: #6738). And another one is to make separator configurable.

For former one, it might be revert #6835 partially. @jfbu What do you think?

Next, for another one, I feel too much to add a new configuration. But I'm okay to override via constant. For example, I imagine you can do it with following code.

# in conf.py
from sphinx.roles import MenuSelection

MenuSelection.BULLET_CHARACTER = '\N{RIGHTWARDS ARROW}'

Does this help you?

[kai687]

Yes, I think, it would indeed help.

[tk0miya]

I just post #7016 for latter one. As commented in PR, it is not a public interface. But I think it might not be changed.

[kai687]

Thank you very much.

[tk0miya]

Now I merged #7016 . So latter problem will be resolved in next release.

[CendioOssman]

This default choice is also an issue if you use rst2pdf as the PDF builder. Since ‣ is not in the default PDF font set you get those replaced by ■, which isn't particularly helpful.

Rather than having to override this everywhere, perhaps a more compatible default can be chosen? With PDF in mind, the available symbols would basically be Zapf Dingbats:

https://en.wikipedia.org/wiki/Zapf_Dingbats

U+27A4: ➤ Could perhaps be an acceptable alternative?