[Doc-SIG] Reworking Explicit Markup
David Goodger
goodger@users.sourceforge.net
Fri, 19 Oct 2001 16:47:55 -0400
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