[DOC-SIG] Re: [PSA MEMBERS] [XML] Notes on the Tutorial's markup

[Fred L. Drake]

raf writes:
 > Literate programming is essential, though, if you want any hope of the
 > documentation matching the implementation.

  While I think literate programming is an interesting, valid, and
useful approach, I don't think that it is "essential", as you assert.
It is *possible* to produce effective and accurate documentation
separately from the source code, and also possible to produce
incorrect documentation using literate programming techniques.  How
many times have you found code that doesn't match the comments and
docstrings which accompany the executable statements?  This has
certainly proven to be a problem in every large project I've had to
read the code for, and is very easy to have happen in a highly dynamic 
environment.  I think it safe to say that Python qualifies for that,
especially for those of us using it in research.

 > When python code is written, the docstrings must be there, but they could
 > be stripped out when 'installing' the module, just as the code is
 > 'stripped out' when producing the documentation.

  I find that I use docstrings primarily when attempting to understand 
code; I don't actually use it often in a running interpreter.  Perhaps 
as more development environments become available this will change,
but I'm not sure that the docstrings should be the sole or primary
source of documentation.  An environment which incorporates external
reference material through a well-designed hypertext model would go a
long way to providing the kind of support I'd like to see, but the
whole thing would need to be suitable for large projects before I'd
find it usable at all.  So my inclination is to support structured
documentation as a separate but accessible component of the system;
multiple forms of access can be provided to support multiple needs.


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

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