[PYTHON DOC-SIG] Re: New Module StructuredText

[Ka-Ping Yee]

Jim Fulton wrote:
> 
> I've added logic so that paragraphs that end with '::' and that have
> subparagraphs introduce sample code.  This was necessary becaus it
> sometimes doesn't make sense to end the introductory paragraph with the
> word 'example'.  I propose that this be incorporated into gendoc.

This is a cool idea.

What about "variables" in documentation?  For instance,
you may want to describe an HTTP URL as

    http://<host>:<port>/<path>

In HTML you would use the <var> tag for this.

The common text usage, i believe, is to use <angle brackets> as i
have done above, and the common print rendering is italic.  This
is a fairly often-used element in technical documentation.

Do you expect people to just use *emphasis* for this?  Or could i
suggest using <angle brackets> specifically for descriptive
names that take the place of other things?


Ping
       3B Computer Engineering, Waterloo (on exchange in Tottori, Japan)
http://www.lfw.org/math/ brings math to the Web as easy as <se>?pi?</se>

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================