[PYTHON DOC-SIG] Structured documentation syntax

[Robin Friedrich]

|> Date: Thu, 12 Sep 1996 23:52:11 +0900
|> From: Ka-Ping Yee <s-ping@orange.cv.tottori-u.ac.jp>
|> 
|> 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.
|> 
...
|> Or am i missing something?

I was refering to the internal reference scheme Jim had in mind.
The external reference scheme is implimented and works fine.
And yes, the above trivial change with make the delimiters brackets
rather that quotes. This seems to be the consensus so it'll change
in the next release. (or in your local copy)

|> 
|> 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.)
|> 
OK this is a symptom of trying to run the gendoc script in
place. It needs to be moved somewhere in your $PATH.
The make install would do this, but you have to have GNU make:-(
The gendoc directory should be in your PYTHONPATH.
The gendoc script should be in your PATH.


|> 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.

Plug away:-)

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

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