[Doc-SIG] Re: Documenting Python, Take 2

[Fred L. Drake, Jr.]

I said:
 >   I understand the need for F2-->F1, but why F1-->F2?  It certainly
 > could not be general unless F1 is heavier than I imagine.  Please
 > provide the rationale for the F1-->F2 requirement.

uche.ogbuji@fourthought.com writes:
 > My thinking was that some users would appreciate the concise form in their 
 > distro for quick reference without weighing doen their modules (and memory 
 > foot-print) with the heavyweight F1.

  I don't understand.  Are you saying someone is likely to want to
create the "heavy" format and then generate the "light" format for
distribution?  It sounds like they should be using the light format to 
author and be done with it.

 > No.  F2 in my mind is not user-friendly.  I'm talking about something that 
 > converts "@param" to "parameter" with some salsa and bean dip tossed in to 
 > make it all palatable.

  I'd say F2 is author-friendly, esp. if augmented with information
from the parse tree by a reasonable tool.  It's not *reader* friendly; 
the result of processing the stuff has that job, and that's not
interesting at the moment (I don't think); the tools do that work,
once written.
  I must confess, at the moment I'm almost entirely concerned with
authoring rather than presentation.  The issues are how much needs to
be explicitly marked (regardless of syntax), the amount that has to be 
learned and typed to mark information (what I call the "weight" of the 
markup), and how much information is actually useful once marked.
Over-estimating value is painful because it turns away authors.

 > Then let's just leave off that bit.  Of course, if we use Docbook,
 > making man pages should be no great endeavor.

  *Generating* the man page isn't a great endeavor in any case;
deciding how much to put there is hard (one class? function? method?
module?).  That's what committees are for!  ;-)

  (This all said, I'm still way behind with the Doc-SIG mail, but I am 
digging into it.)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives