summaryrefslogtreecommitdiff
path: root/support/textoolspro/textoolspro.tex
blob: e08058965c0958cfd6679679793f5ab9dee5bc7a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
% 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}