[Doc-SIG] [ANNOUNCE] SantisimaInquisicion

[David Ascher]

On Fri, 26 Nov 1999, Manuel Gutierrez Algaba wrote:

> http://www.ctv.es/USERS/irmina/SantisimaInquisicion/AutoDeFe.html> 

> There you can see clearly two examples,... please let me know 
> if this is not enough.

I understand the concept of markup.  Your markup is basically TeX.  Fine
for TeX documents, but why in the world do you expect Python users who are
used to 

  def foo():
     print 'a'

to suddenly like

  \newcommand{\indexCextension}{\index{Cextension}\index{extension}}

and why do you think they would even consider adding it to their code?
What is the benefit to them?  You need to show the *end-result* of
indexing, which means hyperlinked TOC's, pretty HTML pages, etc.

Warning: rant ahead.

Generally, I think that the DOC-sig spends too much time arguing about
specific markups and trendy technology (sorry, I'm getting really
frustrated at the XML LPHBTSP (that's 'alphabet soup' without vowels), and
not enough with the marketing aspect.  

*If the problem is to encourage average Python coders to markup their
docs*, then you need to make it simple *and Python-like*.  Define a
Pythonic syntax (e.g what Jim Fulton uses in the StructuredText.py
module), provide a CGI script which has a "PUT" button which will take a
marked-up .py file, creates a hyperlinked TOC for that module, snazzy HTML
pages and whatnot, automatically add said module to some centralized
repository of 'cool documented modules', and folks *will* learn the
markup.  Especially if you provide a few modules which show examples of
the markup and show how trivial it is.

On the other hand, if you put up a page which makes Python code look more
like TeX or XML, why in the world do you expect people to bother?

POD, Javadoc, and Autoduck work because they do 90% of the job with about
4 minute of learning.  That is *all* you can expect of 95% of the
programmers out there.  Go for the biggest bang for the buck.

Enough with the rant.  Back to normal DOC-SIG business.

--david