[Doc-SIG] Documentation tool

[Robin Friedrich]

Mark Hammond wrote:
> We could just view some of the tags as being a coincidence they are
> similar to HTML...
> 
> The particular tool I use happens to use "<" for tag delimiters, and
> shares one or 2 with HTML (B and I being about it).  Apart from that
> it is not at all like HTML.
> 
> Mark.

The problem I see cropping up is people thinking that <B>words</B> implies
full HTML (people never read the instructions). It's a real slippery slope
that I wanted to avoid. If you're only going to have two or three tag out of
the HTML then it shouldn't matter that they are same or not since you are not
adopting the bulk of the markup.  Next people will want <UL> <LI> support, and
then ... yada yada.

Oh and I can see someone arguing that <STRONG> should be supported instead/as
well as <B> because it's the proper abstract tag. Whoops, slipped on that ice again!

"""I'm typing along in my neat little doc string and I want to note that
*itemA* relates to *itemB*  only on the first Monday of the month as
documented in [RFC 4981]. 

.. [RFC 4981] http://www.w3c.org/mystical/magic.html
"""

or

"""I'm typing along in my neat little doc string and I want to note that
<I>itemA</I> relates to <I>itemB</I>  only on the first Monday of the month as
documented in <A HREF="http://www.w3c.org/mystical/magic.html">RFC 4981</A>. 
"""

Hmmm.  I'm sorry I still prefer the former.

-Robin