[DOC-SIG] Documentation formats

[Jim Fulton]

Paul Prescod wrote:
> 
> Guido van Rossum wrote:
> > I think that SGML is not fit to be typed by humans

I agree alot.

I also think TeX and it's variants are not fit to be typed
by humans.

> Hundreds of thousands of HTML page authors would be surprised to hear
> you say that!

I wouldn't be surprized.  That doesn't make Guido's statement incorrect.
 
I'm putting my $0.02 in response to this message for no particular
reason.  It seemed like as good a place as any. :-)

 - With regard to doc strings, I think it is *very* important
   that they be very readable in raw form.  I think that one can
   go a long way with tools like structured text to produce reasonably
   rich output while retaining readability of source text.

   This was discussed at length in the early days of the DOC sig. 
   I'm sure the archives contain this discussion.
   
 - With regard to Python manuals and documentation not generated from 
   docstrings, I have another suggestion.  I don't know for sure that
   this suggestion is viable, or if someone has suggested this before.

   IMO in an ideal world, people would author documentation in a modern
   word processor like Frame or Word and people could share
   documentation files using some neutral format.  I don't know if
   such a neutral format exists, although I seem to remember that at
   one point, Frame had a tool for working with SGML in Framemaker.
   I don't know what happened with that tool, but if it is still around, 
   maybe people who hate editing SGML could use Frame or some other
format
   that supports SGML and other folks could hack SGML or use tools that
   convert between their favorite editing environment and SGML.

Jim

-- 
Jim Fulton            jim@digicool.com
Technical Director    540.371.6909                Python Powered!
Digital Creations     http://www.digicool.com/    http://www.python.org/

_______________
DOC-SIG  - SIG for the Python Documentation Project

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