[Doc-SIG] PEP-0216

[Ken Manheimer]

Well, it's remarkable to see StructuredText really considered after all
this time.  I'm sorry that i probably won't have time to do more than
kibitz.

Moshe wrote:

> At the moment, there are problems with ST-NG, which I've already
> written about in a previous e-mail.

Which i understand to be:

| Current questions about ST-NG:
|    - Does it support proper escaping of meta-characters? If I want to
|      type *, or ', can I?

Not as it stands.  We will need for it to do so sometime soon, to
interoperate with, eg, conversion back from other formats (eg, xml) to
StructuredText.  What we haven't done is arrive at a representation
for escaping that conforms to the StructuredText principle of being
"natural" when viewed in source form, as well as when rendered.  (This
is a very central principle, and i think one that can enable
StructuredText to be used to transcend the impedence mismatch between
rendered and source text.)

One idea i'm toying with is to have (") double quotes escape simple
constructs they contain.  This is obvious for, eg, the code
construct::

   One expresses code snippets by containing text within single
   quotes, like "'def halting_test(code):'".

For me, at least, it makes sense in the raw text passage.  I think
there would be a problem with, eg, code that contains double quotes.
Perhaps it's ok to have them bind tightly, and use them closer
together::

   One expresses code snippets by containing text within single
   quotes, like "'"def halting_test(code):"'".

A bit ugly, but i think the intention is apparent and credible.

Likewise, for bullets::

  "*" A non-bullet sentence following an asterisk.

  Some names in foreign languages can have funny characters, like !xabu
  and "*"dingbop"*"

(Note - i *believe* that *example* text - blocks introduced by a paragraph
ending in a '::' - should have all ST interpretation disabled, so the
above examples would show the double quotes as well as the things they are
quoting - if the double quote convention existed.)

In any case, it will take some coding to implement some escape mechanism.

|    - Does my proposal about Python symbols identified as [<type>:<symbol>]
|      make sense? How hard would it be to extend the current code to
|      do just that?

I don't understand the question, and don't have the time to follow
back a second level of indirection to track down your proposal.  (And
i don't think i'll have time to do the legwork to investigate, if i
*did* understand the question:-(  )

|    - What high level rules do we wish to impose on each docstring? In
|      particular, how to document methods that don't exist? (E.g.,
|      __getattr__ or instance variables that look like methods)

I also don't quite understand this intent of this question, but i
suspect it's not a StructuredText issue, per se.  ?

Ken
klm@digicool.com