[Doc-SIG] Reworking Explicit Markup

[David Goodger]

Tony J Ibbs (Tibs) wrote:
> I'm less sanguine than he about the ease of remembering what can't go at
> the beginning of a comment, although I suppose "magic" allows::
> 
>     .. Remember: http://www.python.org/ is a really neat site.
> 
> to be a comment because of the trailing text?

No. It's not a hyperlink target because there's no leading underscore, and
it's not a directive because there's only one colon after "Remember". And
it's obviously not a footnote. Therefore it's a comment.

I'm not troubled by the possibility of writing a comment that gets
recognized as something else. On the one hand, comments should be rare
beasts. On the other hand, they're an advanced feature; anybody who uses
comments ought to understand how to avoid the other constructs.

> Could one could also do::
> 
>     Useful languages for this purpose include Tcl__,
>     Python__, Perl__ and Sather__ - but irrespective
>     of practicality, Python_ will always be my first
>     love.
> 
>     __ http://www.sometcl.resource/
>     .. _python:
>     __ http://www.python.org/
>     __ http://www.perl.org/
>     __ http://www.sather.org/
> 
> as an alternative?

I see no reason why not. Yes, it follows naturally.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net