Re: [Docutils-users] Syntax for parameters for roles?

[Guenter M. <mi...@us...>]

On 2016-02-29, Oleksandr Gavenko wrote:

...

> RST have regular syntax for block level elements:

>   .. contents:: My TOC
>      :local:
>      :depth: 1

> But I can't find relevant mentioning about support of parameters by roles:

>   http://docutils.sourceforge.net/docs/ref/rst/directives.html
>   http://docutils.sourceforge.net/docs/ref/rst/roles.html
>   http://docutils.sourceforge.net/docs/ref/doctree.html

> I think about exploiting finite number of parameters so it is possible
> just to register necessary amount of roles.

Currently, there is no support for role parameters when using a role.

You can, however define custom roles (eventually inheriting from a base
role). 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#role


With most roles, the ":class:" option can be used to set a "classes"
attribute. By default, a classes attribute equalling the role name is given
to instances of custom roles.

See the reStructuredText Interpreted Text Roles document for details.
http://docutils.sourceforge.net/docs/ref/rst/roles.html

Specific base roles may support other options and/or directive content.
This is, e.g., recommended for inline code highlighting::

For example, the following creates a LaTeX-specific "latex" role:

.. role:: latex(code)
   :language: latex
   
http://docutils.sourceforge.net/docs/ref/rst/roles.html#code   



>================================================================

> Also I don't understand if additional parameters to directive will be
> accessible from Python RST parser for inline substitution, like:

>   This is a |myref|.

>   .. |myref| data:: TEXT
>      :attr1: val1, val2
>      :attr2: no
>      :attrn: http://.../...

This is only supported for a limited set of optins of some directives for
substitution__ :

image
  directive argument and options also supported in a
  substitution (with special values for align)
  http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
  
unicode
  options trim, rtrim, ltrim
  
date
  optional argument (date format)

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions


Günter