[PYTHON DOC-SIG] Structured documentation syntax

[Ka-Ping Yee]

Skip Montanaro wrote:
> That was my thought also.  I believe the "official" way to
> distinguish URLs in otherwise plain ASCII text is with a
> URL: prefix, as in:
>
>      <URL:http://www.python.org/>

It is, but (as i said in response to Ken M.) i thought we
were talking about the hyperlinked *text*, not the URL.

Jim Fulton wrote:
> One could say:
> 
>    blah blah blah spam [42] blah blah
> 
>    ....
> 
> .. [42] http://..
> 
> Where "[42]" gets highlighted. Which I would fine more readable
> as text and just as readable as hypertext.

This is exactly what i had in mind when i suggested [], as
this kind of usage is fairly common practice.  Sometimes the
brackets contain numbers, sometimes small identifiers like
[ROSSUM96], or the author can choose to just [use the flow]
of text.

Robin Friedrich wrote:
> OK now where getting somewhere. Does anyone volunteer to
> hack something up to try out? ;-)

Sorry, but i thought gendoc already implemented this?  It
looks like all you'd have to do is change a couple of lines
in docregex.py.

Line 86 defines hypertext_regex as:

    regex.compile('\([ \t\n]\)\"\([^"\n]*\)\"' + endm)
                              ^^           ^^
                    make that \[    and    \]

and line 90 defines hyperdef_word as:

    hyperdef_word = '"\\([^"\n]*\\)"'
                     ^             ^
          make that \[    and     \]

Or am i missing something?

Unfortunately, i can't test this out because whenever i
run 'gendoc', i always get

    Traceback (innermost last):
      File "./gendoc", line 2, in ?
        import ni
      File "/usr/local/lib/python1.4/ni.py", line 435, in ?
        install()
      .
      .
      .
      File "./__init__.py", line 1, in ?
        path = __.__path__[0]
    TypeError: unsubscriptable object

I would like to see 'gendoc' in action, so if someone
knows what's going wrong here, please let me know.
(I'm using a recently-downloaded release 0.6.)

By the way, can i put in a plug for RE_SYNTAX_AWK
here?  They would be an awful lot easier to read, what
with all the parentheses you don't have to backslash.


Ping

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

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