[Doc-SIG] Use cases for inline directive references

[Alan Jaffray]

I'm playing fast and loose with the hypothetical directive names
and syntax; this is just intended to get the ideas across.


Objects
-------
Inline directive references may be used to associate ambiguous text
with a unique object identifier.

For example, many sites may wish to implement an inline user directive::

    |Michael| and |Jon| are our widget-wranglers.

    .. |Michael| user:: mjones
    .. |Jon|     user:: jhl

Depending on the needs of the site, this may be used to index the document
for later searching, to hyperlink the inline text in various ways (mailto,
homepage, mouseover Javascript with profile and contact information, etc),
or to customize presentation of the text (include username in the inline
text, include an icon image with a link next to the text, make the text
bold or a different color, etc).

The same approach can be used in documents which frequently refer to a
particular type of objects with unique identifiers but ambiguous common
names.  Movies, albums, books, photos, court cases, and laws are a few
that come to mind for me. ::

    |The Transparent Society| offers a fascinating alternate view
    on privacy issues.

    .. |The Transparent Society| book:: isbn=0738201448

Classes or functions, in contexts where the module or class names are
unclear, are another possibility::

    4XSLT has the convenience method |runString|, so you don't have to
    mess with DOM objects if all you want is the transformed output.

    .. |runString| function:: module=xml.xslt class=Processor


Images
------
Images are a common use for inline directive references::

    West led the |H| 3, covered by dummy's |H| Q, East's |H| K, 
    and trumped in hand with the |S| 2.

    .. |H| image:: src=/images/heart.png height=11 width=11
    .. |S| image:: src=/images/spade.png height=11 width=11

    * |Red light| means stop.
    * |Green light| means go.
    * |Yellow light| means go really fast.

    .. |Red light|    image:: src=red_light.png
    .. |Green light|  image:: src=green_light.png
    .. |Yellow light| image:: src=yellow_light.png

    | -><- | is the official symbol of POEE_.

    .. | -><- | image:: discord.png
    .. _POEE: http://www.poee.org/


Styles
------
Inline directive references may be used to associate inline text with an
externally defined presentation style::

    Even |the text in Texas| is big.

    .. |the text in Texas| style:: big

The style name may be meaningful in the context of some particular output
format (CSS class name for HTML output, LaTeX style name for LaTeX, etc),
or may be ignored for other output formats (often for plain text).

Interpreted text is unsuitable for this purpose because the set of style
names cannot be predefined - it is the domain of the content author, not
the author of the parser and output formatter - and there is no way to
associate a stylename argument with an interpreted text style role.
Also, it's desirable to use the same mechanism for styling blocks::

    .. style:: motto
       At Bob's Underwear Shop, we'll do anything to get in your pants.

    .. style:: disclaimer
       All rights reversed.  Reprint what you like.


Templates
---------
Inline markup may be used for later processing by a template engine.
For example, a Zope author might write ::

    Welcome back, |name|!

    .. |name| tal:: replace user/getUserName

and get the ZPT output ::

    Welcome back, <span tal:replace="user/getUserName">name</span>!

which Zope would then transform to something like ::

    Welcome back, David!

during a session with an actual user.


Substitution
------------
Inline directive references may be used for simple macro substitution.
This may be appropriate when the replacement text is repeated many times
throughout one or more documents, especially if it may need to change
later.  A short example is unavoidably contrived::

    |RST| is a little annoying to type over and over, especially when
    writing about |RST| itself, and spelling out the bicapitalized word
    |RST| every time isn't really necessary for |RST| source readability.
    
    .. |RST| replace:: reStructuredText_
    .. _reStructuredText: http://structuredtext.sourceforge.net/

Substitution is also appropriate when the replacement text cannot be
represented using other inline constructs, or is obtrusively long::

    But still, that's nothing compared to a name like |j2ee-cas|.

    .. |j2ee-cas| replace::
       .. link:: http://developer.java.sun.com/developer/earlyAccess/j2eecas/
          the Java`TM`:super: 2 Platform,
          Enterprise Edition Client Access Services