[Doc-SIG] On David Ascher's Rant

[Manuel Gutierrez Algaba]

On Sat, 27 Nov 1999, David Ascher wrote:

> On Sat, 27 Nov 1999, Manuel Gutierrez Algaba wrote:
> 
> > My proposal is so flexible that it could live with any other marking.
> 
> Manuel, I am somewhat at a loss as to what your proposal is.  Can you
> describe it more precisely, without beliefs such as "it's more powerful"
> or "This is much better" but rather with a precise definition of exactly
> what it is you're proposing?  Just looking at the website doesn't really
> help me at least.  
> 
> Are you proposing:
> 
>   1) a markup syntax (e.g. \newcommand vs <NEWCOMMAND> vs ...)?
>   2) a set of tags (e.g. function, extensionmodule, usenetpost, ...)?
>   3) something else?
> 
> I gather that all documents can be indexed with your system, and that you
> do not intend to propose a specific set of indexing 'keywords'.  That
> seems to fly in the face of decades if not hundreds of years of prior art
> which shown the success of domain-specific keyword lists. Can you try
> again, please, without hyperbolae?

Hyperbolae are needed when you can't explain anything and then
you try to win the hearts instead the minds. In this email I won't
mention "simple", "easier" nor "better" nor "best". I'll explain
plainly the idea.

The current situation in python world is this:
- We have humans
- We have doc
- We have code

There's a relationship among humans-doc :
Humans want to poke information from docs, in fact, they need the
information to produce code, mainly. Because of that, code has got 
some kind of frozen information ( the one the coder used for building
it ).
There's a relationship among code-doc:
Code can be seen as a thing that may help to produce new code or 
to understand new code/code, the code itself is a special kind of 
doc. 

It's obvious that code can produce new code, but for that we need
usually the esence (the doc) of what that code does. We need that
esence because IMO code is just an implementation of an information,
even in a high level programming language, that code keeps personal
preferences or solutions. Those preferences are things like:

def inter(a,b):
   result = []
   for i in a:
      if i in b:
         result.append()
   return result

There're almost 20 versions of this code, using filter, map, 
default params, using dicts... For a very specific "idea"/info
( intersection of two list) we can have 20 versions of it. 

If I doc this function properly ala "javadoc", truly I have 
info about "one implementation" of an idea.But obviously when reusing
code we need two things: look for implementations of the idea we
have and adapt it to our code. The idea we are looking for is far
more important than the implementation itself, the implementation
may be adapted, and in the case of python, the implementation
of an idea ( params, code itself) is not so obscure to need a strong
doc support ( think about assembler or prolog or perl). 

Perhaps, you agree now with me in :
- that code is basically "frozen implementations" of ideas/info
- OO programming involves frequent reuse of code, frequent reuse
of ideas.
- it's important to deal with ideas
- we can't leave details of implementation for later

Once we've identified our main target: ideas
 ( how to reuse and handle)
the question is how to do it ?

Well, I say: If this code :

class....
    bla...
    bla....
    bla....

is the implementation of an idea, let's mark it explicitly with:
<#idea_A>

Once we've marked it we now see if that solves our question:
"how to reuse and handle ?"

Can I reuse and handle the idea of that code that has been marked
with <#idea_A>? 
This involves :
- is idea_A the idea I'm looking for?
   If yes: then it works
   If not but it's a similar idea (sorry If I tend to overuse
latin words, similar=very close)

Then the question is now "what is a similar idea to another?"
It seems, that similar (very close) implies that the ideas group
themselves into groups.

Let's think about it, let's think about a example with sockets :

socket, asyncronous, buffering, internet, CGI, server, telnet port,
RFC, timeout...

Apparently some ideas involve more basic ideas ( telnet port  for
example), but It seems that basically those ideas are widely general
and single-meaning. Is there any field whose ideas are not widely general
or single-meaning? Well, fortunately, we're not talking about
philosophy but about technical ideas.
Can you identify clearly ideas in the code? Lots of times, I guess.
But even in those cases that they're not clear or are not very
general ideas then It may happen:
- you're considering implementation information, not the idea that
that code implements
- your code solves a non common idea, but even so, that idea
will be related with any more common idea. 

If you've got this far, you see I'm talking about relationship
among ideas, not about code. Fred and Paul worry about those
relationships, they can be many, they could not be clear.

But even so, we won't know until we have the ideas , until we have
the problem. Then and even if that problem can't be properly solved
We'll have a library of ideas, spread over FAQ, USENET, code, HOWTO,
..., ready to be searched/compared/handled. Library of ideas
mean simply a library of doc/code ready to be used to generate 
new code.

Is going people to mark their code? Is it worth the effort ?

I guess, they're not. In fact, you can express a 
broad idea  with five lines of doc or with a single <#idea>, this
is valid for general ideas. But this requires a change in the mind
of people: - concise, direct, high-level. 

It's the same how is this done !
It's the same \indexbla than <#bla>

It's the same if somebody writes \indexsocket or \indexport
or  \indexcomms. We can relate each other, afterwards.

\indexsocket \indextelnet \indexexpect

is the same that:

\indextelnetexpect

We can have tools that unite different notations.

See this as a pyramid, the higher you are the less space there's. 

Is this "indexing" ? No, I use indexes and it seems indexing,
but It's a kind of Plato-python-world-building. Libraries of ideas,
not libraries of implementations.

It don't think it's a good idea to impose a "limited set of 
keywords", let people express freely, because in fact, in the field
we're working (high level ideas ) there's not too much space left.
Freedom in this level means "expressing" not "confusion".

Of course, "my idea" involves www-web pages ftp , pages of written
books,.... anything. This is like modern art, people like XVIII century
paintings because they can understand it, but modern art is richer
in concepts and information. Is people ready? If they're ready, the
place is here: python-world.

But, I'm rather pesimistic, people is lazy and brute. 

I can't give a list of all the possible ideas, nor give the
relationships... look at TeEncontreX ( the most basic implementation
of that "pyramid") it's easy to handle/search, I guess so. If
it'd be 10 times bigger it wouldn't be much harder to handle, but
it'd carry 10 times more info !!

My idea is a kind of "inverse-video" of Yahoo, and improved of 
course. 

Sorry , for the hyperbolae :) :P

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

  Life can be so tragic -- you're here today and here tomorrow.