% If you don't know how to handle a .tex file, do this :
% This is documentation file for textoolspro ( tex tools for the
% programmer ).
% latex textoolspro.tex
% xdvi textoolspro.dvi
% See dvips man page if you want it in postscript
% I don't supply postscripts because they're usually huge.

\documentclass[10pt,a4paper]{article}
\begin{document}
\title{Documentation and examples of sectioner.py 1.0 \\
boxerer.py 1.0 and miarticle.cls}
\author{ Manuel Gutierrez Algaba \\ irmina@ctv.es \\ http://www.ctv.es/USERS/irmina/texpython.htm }
\date{ January 1999 }
\maketitle

\section{Copyright issues}
boxerer.py, sectioner.py, miarticle.cls  and its documentation ( this text and the sources 
of tex drawings included in it) are copyrighted by Manuel
Gutierrez Algaba 1999 and you are free 
to  use, modify , copy and distribute it under the 
condition that
you include this notice ad in it.

\section{Introduction}
This document explains all the details for the user of boxerer.py,
sectioner.py and miarticle.cls

\subsection{boxerer.py }
When I wrote boxerer.py there wasn't any automated utility for
doing input-output-function boxes. Of course, you can write them
directly in \LaTeX. But boxerer.py has
two major advantages, it's easier to use and it's faster to 'write'.
Besides it can be used as an interface by CASE programs.
The kinds of available drawings are good for:
\begin{itemize}
\item Expressing the internal structure of large pieces of code, resembling their inner and overall structure. 
\item Expressing the interfaces of modules or functions ,that is,
expressing modules and functions as black boxes.
\end{itemize}

And this is an utility written in python. 
\begin{verbatim}
http://www.python.org
\end{verbatim}

I imagine that it could be written in \TeX { }but It's 3 times easier
to use python. And what's more important \TeX{ }programmers have a
model , if they want to do the translation. \\ Another point, the
python code  could be improved \ldots 

And, it generates tex code. So if you want it in postscript, gif
or whatever, use the programs dvi, gs or grab directly from a 
window!

\subsection{sectioner.py and miarticle.cls}
When I wrote sectioner.py there wasn't any automated utility for
handling relative sectioning in \LaTeX / \TeX, or I didn't know
anything about it. Of course, you can write traditional sections in
 \LaTeX. But sectioner.py has several major advantages:
\begin{itemize}
\item It's easier to use because you don't need to know if you are in a section, subsection, \ldots, you just go up or go down a level.
\item {It's more abstract. You don't need to take any decision about
the class of the document ( article, report, letter, miarticle, \ldots), this is done when you filter the tex source through sectioner.py.
This , somehow, follows the true spirit of \TeX:
\begin{quote}
To pay attention to logical design.
\end{quote}
\item { It allows a greater structuration and modularity of \LaTeX code, see details below~\ref{structure_of_sectioner}. }}
\item { You are still compatible with \LaTeX, because you can flatten
your sources of sectioner-\LaTeX into pure \LaTeX (using sectioner.py), and nobody would
never know you used it. }
\end{itemize}

And this is an utility written in python. 
\begin{verbatim}
http://www.python.org
\end{verbatim}

I imagine that it could be written in \TeX { }but It's 8 times easier
to use python. And what's more important \TeX{ }programmers have a
model , if they want to do the translation. \\ Another point, the
python code  could be improved \ldots 


\section{ How to use it}

\subsection{Using boxerer.py }
Always use a ``from boxerer import * `` at the beginning of your
python code.
\subsubsection{Using the class 'included'}
This  piece of python code illustrates the full capabilities 
of included, basically, you can put lot of structured stuff in
it, this is very good, when you program has got very rich in
terms of modularity and information.
This code
\begin{verbatim}
r0 = ("men\\_prin.py",None,"Here it's the main menu is defined")
r1 = ("Graphic representation", [("tkinter.py",None,
                                  "Main calling module"),r0],
                                  "Graphic interfases with the user, mainly")
r2 = ("Structures of the languages(grammar)", None)
r3 = ("Configuration", [("Database of words",None),
		        ("Labels",None)])
i = included(("Lritaunas Peki",[r1,r2,r3],
             " This programm aims to teach \
vocabulary and grammar of different languages."))
f = open("result.tex","w")
i.genera(f)
f.close()
\end{verbatim}
generates this:
\input{result.tex}

As you notice, what it generates is \LaTeX code, it can be included
in a figure, or not, as you please.

\subsubsection{Using the class 'inputoutputfunction'}
This  piece of python code illustrates the full capabilities 
of inputoutputfunction, basically, you say what are inputs,
what are outputs, and what are functions and that's all. The generated code can be inserted directly or it can be put in a figure.
If it's included directly ,then it's a good idea to insert
a \verb|\newline| after and before the \verb|\input| command, otherwise,
it can be messed with the text below it.
This code
\begin{verbatim}
example2=inputoutputfunction('taxman',
"This is your best friend, who helps you when you earn too much")
example2.do_inputs(["Your income","Your properties","The Law"])
example2.do_outputs(["Your taxes","Your fines",
                     "Historical information"])
example2.do_functions(["Compute your taxes","Check your lies",
			  "Send you to prison","Bribery"])
example2.generate_latex_code("result2.tex",200)
\end{verbatim}
generates fig~\ref{fig:input1}

\begin{figure}
\caption{Input-output-function figure}
\label{fig:input1}
\input{result2.tex}
\end{figure}

When you don't want to put its outputs(for example) then you
got a figure as  fig~\ref{fig:input2}
\begin{figure}
\caption{Input-output-function figure, without outputs}
\label{fig:input2}
\center{
\input{result3.tex}}
\end{figure}

Besides, if you put
\begin{verbatim}
example2=inputoutputfunction('taxman',
"This is your best friend, who helps you when you earn too much",
'es')
\end{verbatim}
,then it generates the labels in Spanish. 

\subsection{Using sectioner.py}
This program is a small revolution in the \LaTeX--world, I think.
Let's take a look at a sectioner-\LaTeX\ code:
\\
\begin{minipage}[l]{300 pt }
\small
\begin{verbatim}
\documentclass[10pt]{miarticle}
\begin{document}
\n 
Lritaunas Peki Documentation
Lritaunas Peki is a programm for learning languages.

\+ 
Structure of the Code

\+
Graphic user interfaces
\+
Ideas
Basically, you must think about it as a nested layers of metawidgets.
So we can reuse the code.
\n
Python mega widgets
This is a nice library of megawidgets, that supports scrollbars,
multiple entries, dialogs...
\+
My meta widgets.
Trying to isolate GUI from tk and from Pmw(python megawidgets) I
wrote a higher set of widgets.

\+
Specialized metawidgets
This widgets are those really used in the GUI, they're composites
of my meta widgets, and they make calls to the structures of
the core code~\ref{lookupindictionaries}


\-2
\n
What you really see in your screen
Blah, blah

\-2


/minput{strucincode.tex}

\n
And yeah more blah
Blah , and blah

\end{document}
\end{verbatim}
\end{minipage}
\\
Well, as you notice, \verb|\sections| have been replaced by \verb|\n,\+ or \-|.
The line below a \verb|\n,\+ or \-| is the title of the (sub)section
or whatever. There's no binding with the style of the document,
if you replace miarticle by report, then the sectioning of report
style will be used. The only thing you musn't forget is that the title of it {\large CAN BE ONLY IN THE NEXT LINE TO THE  \verb|\n,\+ or \-|}.

The  \verb|\+2 or \-3 | things say you go two levels up or down.
And the \verb|\n| stays at the same level.

And the last thing is \verb|/minput{strucincode.tex}| , this includes
more code in sectioner--\LaTeX style. As a matter of fact, all this
story about sectioner is that it's better for modularity, look at 
this: 
\\
\begin{minipage}[l]{300 pt }
\small
\begin{verbatim}
\n
Structures used

\+
Dictionaries
\+ 
Functions
\+ 
Lookups
\label{lookupindictionaries}
This is probably one of the most used flavors.. blah, blah

\-3

\end{verbatim}
\end{minipage}
\\
As you may notice , \verb|\-3| makes that all that module is 
encapsulated, in terms of sectioning. Depending where you include
it , you got sections, subsubsections, or paragraphs, or whatever.
And you can use labels, because, sectioner is just a filter, 
when it finishes its work, you got pure \LaTeX, code. Of course
you can nest to the level you want ( if your style allows it).
\label{structure_of_sectioner}

\subsubsection{ How to call to sectioner.py}
\begin{verbatim}
python sectioner.py method inputfile outputfile
\end{verbatim}
method can be: manolo ( for miarticle.cls), article or report.
inputfile would be highnest.tex in this case, and outputfile whatever
you want.
As a example lets take a look at the output ( I wrote o.tex as outputfile):
\\
\begin{minipage}[l]{300 pt }
\small
\begin{verbatim}
\documentclass[10pt]{miarticle}
\begin{document}
\part{Lritaunas Peki Documentation}
Lritaunas Peki is a programm for learning languages.

\section{Structure of the Code}

\subsection{Graphic user interfaces}
\subsubsection{Ideas}
Basically, you must think about it as a nested layers of metawidgets.
So we can reuse the code.
\subsubsection{Python mega widgets}
This is a nice library of megawidgets, that supports scrollbars,
multiple entries, dialogs...
\sssection{My meta widgets.}
Trying to isolate GUI from tk and from Pmw(python megawidgets) I
wrote a higher set of widgets.

\ssssection{Specialized metawidgets}
This widgets are those really used in the GUI, they're composites
of my meta widgets, and they make calls to the structures of
the core code~\ref{lookupindictionaries}


\subsubsection{What you really see in your screen}
Blah, blah



\section{Structures used}

\subsection{Dictionaries}
\subsubsection{Functions}
\sssection{Lookups}
\label{lookupindictionaries}
This is probably one of the most used flavors.. blah, blah


\section{And yeah more blah}
Blah , and blah

\end{document}
\end{verbatim}
\end{minipage}

\subsubsection{About miarticle.cls}
It's a good style when you require more than 7 levels of nesting.
It has a small bug, it says some warning when compiling. Press Return
twice and forget it. 

\subsection{Sources of help}
Well, the best you can do is to take a look at the end of boxerer.py
and sectioner.py
where you can see how boxerer generates the draws and how sectioner filter. 
Secondly, you should take a look at the source of this document,
that is: less  textoolspro.tex 

The figures are included using a simple \verb|\input| command.


\section{ Caveats and bugs}
Boxerer has no bugs. Sectioner has no bugs, miarticle has that
nasty warning about that number ( forget it). Even so, there'll
be some bugs.

\section{Bye bye}
I hope this documentation helps you to use these utilities. It's not
difficult and greatly profitable.
And if you want to get similar drawings or improve some of them
just take a look at the code, once you get accostumed to it , you'll
find it quite logical.

\end{document}