[Doc-SIG] a wish list

[Manuel Gutierrez Algaba]

On Mon, 8 Nov 1999, Fred L. Drake, Jr. wrote:

> Manuel,
>   I did actually take a moment to look at it, but I wasn't really sure 
> what you were doing.
>   In response to your more recent note here, I took another look.  I
> downloaded the complete Unix package, and I'm still not quite sure
> what's going on.  (The code is hard to read for those of us who don't
> know Spanish; sorry.)
>   Can you explain precisely what you're advocating be done?  I'm sure
> it can be explained on a Web page if you'd rather add it to your
> TeEncontreX site for everyone who looks there, or in a message here,
> whichever makes more sense for you.

Well, sorry, I was definetely sure that AnalizaToo.py was quite
readable... Anyway if you're  interested in, I can translate it.
Anyway, the core of my proposal is not the programm but the data.
The code is just a "formatter" of the data. All this stuff about
data has a heavy theoretical base.

Let's take a look at a typical article of Too.tex ( my database):
....
\jiji
 1. How do I change the section headings such that the section number
 does not appear in boldface? Or make the section number and
 the section header to be unbolded?
\jaja
\indexlayout \indexsection
titlesec.sty or sectsty.sty.
\jiji     
...
Consider \jiji as delimitors of an article, and \jaja delimitor
of parts of an article. 
\indexlayout is saying that the article is about "text layout".
As any concept may be related directly to many other concepts I
mark this relationship thus:
\newcommand{\indexlayout}{\index{layout}\index{decorations}
\index{adornos}}

So I basically attribute the articles with keywords. Another
example:
\jiji
\indexnumeracion
\indexalphanumeric
\indexfootnote
 Can footnote markers be something other than arabic
numerals?

\jaja
Yes, \renewcommand{\thefootnote}{\alph{footnote}}
  or \Alph, or \roman, or \Roman, or \fnsymbol
This is a general prescription for changing the formatting of one of
LaTeX's counters: you redefine \thecounter.

\jiji   

The idea of keywords is not new. But what's not so new, is what 
happens when we try to put many keywords in small pieces of information
and then we glue all that information. 
As almost any piece of information is very rich ( the example
above holds inf about numbering, footnotes and arabics), then
the reunion usually have many contact points, ie, imagine that many
articles may speak about footnotes (as a main subject or secondary).
So if we eventually want to information about footnotes, we'll
have a large collection of related stuff. And that collection
will be rather significant of the footnote itself. Let's take
a look of an example:
(sorry again, if you don't understand...
 Articulo = article, estos son los articulos disponibles
these are the available articles,
adornos = decoration = stuff to make things prettier )

 Estos son los articulos disponibles
   Articulo 11: adornos decorations secsty titlesec layout
   Articulo 32: hrule adornos decorations
   Articulo 39: altura decorations book.sty adornos baseline
   hbox height cuadro
   Articulo 48: adornos decorations rcs
   Articulo 72: adornos decorations final_linea end_of_line
   Articulo 73: adornos figure decorations
   Articulo 79: adornos margins decorations
   Articulo 112: space adornos decorations tabular
   Articulo 134: adornos decorations book cleardoublepage
   Articulo 138: adornos decorations caption
   Articulo 144: adornos decorations space textheight 

Just watching this, you can learn about the term "decoration".
It's something related to space, textheight, book.sty, hrule,
hbox... It'd may happen that you could get almost a definition
of it ! Well, this scheme lets you refine your search (imagine
if you are trying to get some kind of effect in LaTeX), just
browsing by the article that is closer to your wishes ( textheight,
titlesec), and to learn more about concepts related to "decoration".

But, this is just "one scheme" (the one provided by AnalizaToo.py).
 With
the very same Too.tex(database)
and if it were big enough you could say:
I'd like you to make a book about "decoration in LaTeX",and these
are the rules
1 I want to a description about general concepts
2 I want it from the more general to the specific item
3 The more general is "book","space",....

Please, remember than currently Too.tex is a collection of USENET/mailing
lists articles, but even so. You'd get a document, whose articles
would be "sorted" by your rules. Remember too, that we'd need 
an article labelled with general_concepts, and decoration.

Imagine, now python doc (that apparently is very different 
from USENET posts)(ref.tex):

...

It is also possible to create anonymous functions (functions not bound
to a name), for immediate use in expressions.  This uses lambda forms,
described in section \ref{lambda}.  Note that the lambda form is
merely a shorthand for a simplified function definition; a function
defined in a ``\keyword{def}'' statement can be passed around or
assigned to another name just like a function defined by a lambda
form.  The ``\keyword{def}'' form is actually more powerful since it
allows the execution of multiple statements.
\indexii{lambda}{form}     
...
Imagine that I attribute this with:
\indexanonymous \indexlambda \indexdefinition \indexdef

Imagine that I've attributed this too(tut.tex):

expression.  Semantically, they are just syntactic sugar for a normal
function definition.  Like nested function definitions, lambda forms
cannot reference variables from the containing scope, but this can be
overcome through the judicious use of default argument values, e.g.

\begin{verbatim}
def make_incrementor(n):
    return lambda x, incr=n: x+incr
\end{verbatim}        

\indexlambda \indexexample \indexvarscope

Well, simply with these attributions we can have ALL this combinations:
- If we want to search by lambda, we'd have:
lambda example varscope
anonymous lambda definition def

So  the reader would guess: ah an example of lambda, and the definition
of lambda!
- If we want to search by def, we'd have:
...
anonymous lambda definition def
....
...
So, he'd know all the ways of defining functions, def, lambda,
recursive, class messages...

So the information we wrote for 'lambda' would be reused for the 
people who wants information about defining information.

- If we want info about var scopes , then we have:
.....
lambda example varscope 
.....
Just imagine all the stuff of scopes here.

You can see easily that all the existing information could be put
from dozens different points of views, and that examples, USENET,
definitions, tutorials may cooperate to give a global complete 
information about any subject.

Now, let's think about XML, it basically reflects the structure
of information. Now I wonder if it'd be better to know what information
are we talking about, if we had 10000 chunks of attributed information
( whose value is great ), we could know which are the possible
structures (combinations of those chunks).

Sorry, if you expected a description of the algorithm (analizatoo.py),
quite "irrelevant" I think, here what really matters is information.

Anyway if you want further information or translation , just say it.

I can't think of any other easier, faster and more powerful way
for reusing existing "as is" information, as this.

Imagine a very large set of chunks of information, sharing and 
grouping ... Is that XML? Is better? Is XML a subset, a hard-wire
of certain scheme of some groups of chunks of information?
 
Regards/Saludos
Manolo
-------------
My addresses / mis direcciones: 
a="www.ctv.es/USERS/irmina"
b=[("Lritaunas Peki Project", ""),
   ("Spanish users of LaTeX(en Espanyol)", "/pyttex.htm" ),
   ("page of drawing utility for tex ", "/texpython.htm" ),
   ("CrossWordsLand","/cruo/cruo.html")
   ]
for i in b:
  print i[0],":", a+i[1]

  Reality is nothing but a collective hunch. -- Lily Tomlin