[Docutils-develop] Re: Unifying roles and inline directives

[Felix W. <Fel...@gm...>]

Mikolaj Machowski wrote:

> Probably not. In-line directives are giving much less clutter in text.

In some cases they do, in some cases not.  IMO the user should be the
one to decide.

For example, you can include an image like this::

    .. image:: foo.png

A user once asked me, "how do I put two images next to each other"?  I
told him he could do it this way::

    .. |foo| image:: foo.png
    .. |bar| image:: bar.png

    |foo| |bar|

However, the meaning of this syntax is difficult to understand by
someone who is not used to reading marked up text.  For example, you
need to understand that "|foo|" and "|bar|" are arbitrarily chosen
identifiers and that a substitution happens.  I would have much
preferred to tell the user to use this::

    :image:`foo.png` :image:`bar.png`

That's shorter and does not involve the substitution concept.

>>     The biohazard sign (:image:`biohazard.png`) ...
>
> What with more complex paths to images?

If they get too long, you still can use substitutions.  But for
inserting an image "biohazard.png" it's much shorter to use the role
syntax.

> In-line directives (substitutions) are much readable in txt form.

Sometimes they are, but sometimes they are too eloquent.  I'm not
suggesting that the substitution syntax be removed, I'm suggesting that
both substitution and role syntax can be used.

> As a user I don't see any real advantages to your proposal.  Probably
> it has some advantages for backend (Python) structure

Yes, it has, definitely.  (David, want me to show code?)

>> * The align=top/middle/bottom feature is removed from the image
>>   directive (because it's only used in inline context, for the image
>>   role).
>
> IMO it should be removed anyway. For HTML it is purely presentation
> aspect and should be handled by CSS - :class: in reST.  No place in
> content.  Similar for LaTeX.

It's certainly at the edge of being presentational, but I don't think we
have enough of a reason to remove it.  Existing documents are relying on
it, after all.

>> * The syntax of raw substitutions changes from ::
>>
>>      .. |foo| raw:: html
>>
>>         <br />
>>
>>   to ::
>>
>>      .. |foo| raw:: <br />
>>         :format: html
>
> Separation of reST syntax and export specific code is better readable.
> Also with long raw fragments it will be bad.

You can still use multi-line raw code, FWIW.

Should be allow for role content, maybe?  That way we could maintain
compatibility.  If the raw role has contents, the argument is used as
the format.  So you could still write::

    .. |foo| raw:: html

       <br />

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR