docutils-users

[Docutils-users] Syntax for parameters for roles?

[Oleksandr G. <gav...@gm...>]

Most feature rich competitor to RST syntax is AsciiDoc and it has regular
syntax for passing additional parameters to macros::

  http://asciidoc.org/asciidoc.css-embedded.html#_macros

For block level syntax looks like:

  [quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
  ____________________________________________________________________
  As he spoke there was the sharp sound of horses' hoofs and
  grating wheels against the curb, followed by a sharp pull at the
  bell. Holmes whistled.
  ...
  ____________________________________________________________________

For inline::

  image::images/logo.png[scaledwidth="75%",alt="Company Logo"]

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.

================================================================

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://.../...

-- 
http://defun.work/

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