[DOC-SIG] Library reference manual debate

[John Skaller]

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

        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?
                the FAQ?
                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
together.

>1.  Providing revisions to the Library Reference as they become
>    available.  

>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
            class aclass
              doc here are the methods
                doc init method
                  def __init__

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.

Comments??
-------------------------------------------------------
John Skaller    email: skaller@zip.com.au
		http://www.zip.com.au/~skaller
		phone: 61-2-6600850
		snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia



_______________
DOC-SIG  - SIG for the Python Documentation Project

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