[DOC-SIG] Library reference manual debate
Sun, 23 Nov 1997 05:54:28 +1100
At 09:56 21/11/97 -0500, Frank wrote:
> > I am continually seeking information -- being
> > a Python newbie -- and I'm having a LOT of trouble finding it.
> This is a problem. If you can tell us what you're looking for and
>how you went about the search (esp. what you tried first), we can see
>about improving the situation. But that's hard to do without the
>feedback, especially for those of us who've been at it a few years.
Yes. I agree. It is why I -- a newbie -- am talking a lot
at the moment. I know from experience how beneficial it is
to get feedback from newbies, having been on the other side of
What happens is: I read all the doco and know
what I can do, but forget the details of how to do it.
Then, when I want to do it:
1) I do not know the names of the things I need,
like attribute names, module names, class names
2) I do not remember _where_ i read the info:
was it in the tutorial?
was it in the ref manual?
in the lib manual? Which module? Which section?
did i get it from Mark Lutz book?
from reading the python source code
from reading C source code
from the USENET news?
I think this situtation could be improved by hyperlinking
_all_ the documents together. I'm not sure.
The Tcl/Tk manual seems slightly easier to use as a manual ---
but then it is hard for me to say, since I'be been using
tcl for around a year (not a newbie anymore)
I really think excellent progress is being made writing
documentation. I tend to think we need more of it, before
organising it better. In academia, this is called
a "literature survey". :-)
I have a tool that scans the whole Python library (as installed)
and parses it into a TixTree. So I can open and close
subtrees of *.py files. If the module is well structured,
I get a beautiful outline of what it does.
The software works for .c files too.
I am finding that this tool is _telling_ me how comments
have to be structured. It suggests a system wide index
can be generated dynamically. It would be nice to
put _hooks_ into the module doco to the corresponding
html pages. That would enable
a) browsing the library and hyperlinking to the doco
b) generating some doco from the library
I'm hoping this additional way of looking at the system
will help me learn where eveything is and how it fits
>1. Providing revisions to the Library Reference as they become
>2. An online knowledgebase of HOW-TO articles, FAQs, and the like
> needs to be available. This could be updated in a more continuous
> fashion, with distribution packages produced in a similar way to
> the primary documentation packages.
Sounds like a good mix!
>The problem with using HTML as the
>canonical format for the Library Reference is that it is
>insufficiently structure. While HTML 4.0 might allow the structure to
>be imposed using CLASS=<???> attributes all over the place, that would
>require custom verification software to be written; this should be
>avoided if at all possible.
This sounds right: I plan to build a documentation
and software database -- I will generate the web site from it,
but I will also cut books and articles from it.
I don't think _any_ format has "enough structure".
That's why I'm programming Python instead.
> My expectation is that the Library Reference project needs to be
>done first, primarily because the problem is better understood and we
>have more concrete notions about what should be done about it.
Well, I have a suggestion/question/idea.
One of the things I can do very easily in C++ is use
indented // comments to present block structure.
If I understand correctly, this won't work with
Python # comments because they're not parsed.
I am wondering if there could be a language token
equivalent to "#" which _was_ parsed:
doc the rest of this line is a heading
doc this is a subheading
doc here are the methods
doc init method
I use two space indents (for reasons of print publication).
I have found that the tixTree representation of the above
structure very useful in C++.
But I have found that python modules are uglier because the doco
isn't parsed in a suitable way, so I can't use it to control
the tree view.
John Skaller email: email@example.com
snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia
DOC-SIG - SIG for the Python Documentation Project
send messages to: firstname.lastname@example.org
administrivia to: email@example.com