[Doc-SIG] [ANNOUNCE] SantisimaInquisicion

[Manuel Gutierrez Algaba]

On Fri, 26 Nov 1999, David Ascher wrote:

> 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 

It happens that TeX documents are the easiest structure to represent
things, apart from raw .txt  A basically TeX markup is just 
the easiest markup. 

> 
>   def foo():
>      print 'a'

This example is too simple , it gots almost no info at all , 
perhaps : \indexbasicdeffunction
(\index{basic}\index{def}\index{function} )
after doing this , anyone searching  for basic things, or for
definitions of for functions may find the piece of code you've done,
your WORK is PROFITABLE now. That piece of CODE IS VALUABLE for 
the rest of community.

> 
> to suddenly like
> 
>   \newcommand{\indexCextension}{\index{Cextension}\index{extension}}
> 
> and why do you think they would even consider adding it to their code?
The answer is the same than: "why do you documentate?"
- To understand what you are doing: If you put \indexCextension,
in that very same word you're resuming the whole functionality
of a piece of code,
- you can have your internal vocabulary inside
your program, so you can browse by different concepts and how they've
been implemented, although this is fairly advanced yet.
- people can understand or join into their databases the information
you've provided. That is, documentation is that thing used for the 
people to understand what others have done.

> What is the benefit to them?  You need to show the *end-result* of
> indexing, which means hyperlinked TOC's, pretty HTML pages, etc.

The *end-result* is Sacramental.html stuff and the rest. But that's
*ONLY* one representation, more than enough, I think for most 
of the cases. It can be prettier but I've showed the most basic .

> 
> Warning: rant ahead.

Warning: more SantisimaInquisicion propaganda 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.  

Me too, that's why I'm proposing the most simple stuff, I think.

> *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

The question is stupid markup is going to encourage anything:
Imagine this :

# name   inter
# param list
# param list
def inter(a,b):
    res = []
    for i in a:
        if i in b:
           res.append(i)

Do you think many people are encourage to behave C-ish with python
code. And what kind of info that provides : there's a inter function
, and it has two parameters, but that SAYS NOTHING AT ALL about 
the function itself, so it's useless for anybody searching for
a list intersection function!

> Pythonic syntax (e.g what Jim Fulton uses in the StructuredText.py

Pythonic syntax for a C-ish idea, python deals with functionality
and no with type rubbish.

> markup.  Especially if you provide a few modules which show examples of
> the markup and show how trivial it is.

I've provided the examples, if people don't do it, it's just because
they're too lazy, the marking system I propose can't be easier...

> 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?

Regretfully, a bit a collateral damages to the code has to be done
to the code, even so, TeEncontreX damages are not too much, a few 
words or lines, here and there. In fact, TeEncontreX markup is the
one that needs less  writting ( by far) and in the most free form ( by
far ),it's rather painfully to be strict , it sounds to me java-ish.
Python is ( by far ) the less strict language I know, in fact,
tight syntax /indent of python is the only (unnoticed) thing, after
wards you enjoy of full power of overloadings eval(), map...
Python is not Java, it's much much more different than it seems at
first sight. Python deserves something strict in the syntax ( \jiji
\indexlkjljk),  flexible in the use ( you can use the indexes you
want, you can place them wherever and whenever you like! ) and 
that deals with the real problem: the problem with DOC is to know
what the CODE is DOING, not their params, functions. The important
thing is the WHAT, let be the HOW for java or for C. 


Regards/Saludos
Manolo
www.ctv.es/USERS/irmina    /TeEncontreX.html   /texpython.htm
 /SantisimaInquisicion/index.html 

  That, that is, is. That, that is not, is not. That, that is, is not that, that is not. That, that is not, is not that, that is.