% If you don't know how to handle a .tex file, do this :
% latex consdiag.tex
% xdvi consdiag.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}
\usepackage{times}
\usepackage{texdraw}
\begin{document}
\title{Documentation and examples of consdiag.py version 1.0}
\author{ Manuel Gutierrez Algaba, irmina@ctv.es }
\date{ December 1998 }
\maketitle

\section{Copyright issues}
consdiag.py 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}
When I wrote this program there wasn't any automated utility for
drawing Rumbaugh OO boxes. Of course, you can use xfig or any
other drawing program for this purpose. But this utility has
two major advantages, It's easier to use and it's faster to 'draw'.
On the other hand, the kinds of available drawings are limited to:
\begin{itemize}
\item isolated classes
\item trees (and just trees, no graphs :( ) of classes related by their inheritances
\item simple associations of classes 
\end{itemize}

It's not much , but...


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 10 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, I've duplicated code in several
parts, because I thought the classes were really different each other,
\ldots, in the end, they've resulted to be very similar in the
way they work.


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!

\section{ How to use it}
\subsection{Using it in a python code }
Just use a ``from consdiag import * ``
and this piece of python code ( for example).
In drawing3.tex is kept the following \TeX { } instructions that generates the
drawing ~\ref{fig:second}:
\begin{verbatim}
c = a_simple_class()
c.do_name_clase('person')
c.do_attributes(['name' , 'sex', 'money', 'health', 
			    'hobbies', 'dreams'])
c.do_functions(['dream', 'love', 'play soccer', 'diving'])
c.index_of_class(3)

c.do_lines()
c.generate_latex_code('drawing3.tex')

\end{verbatim}
\subsection{Sources of help}
Well, the best you can do is to take a look at the end of consdiag.py
where you can see how it generates the draw. 
Secondly, you should take a look at the source of this document,
that is: less consdiag.tex 
Two important details:
\begin{itemize}
\item 
 Don't forget to include the command: \verb|\usepackage{texdraw}|
at the start of your document 
\item 
The figures are included using a simple \verb|\input|
 command.
\end{itemize}


And that's all.

\section{Some examples of it}
\subsection{ A simple class}
The most basic figure you can face when dealing with OO classes is
a simple class, with some attributes. And that's what you can see
in figure~\ref{fig:first}. 
\begin{figure}
%\vspace{3in}
\caption{Single figure}
\label{fig:first}
\input{drawing1.tex}
\end{figure}

\subsection{ A simple class with long names}
Let's see what happens to figure~\ref{fig:first} when you want to
include a really long attribute. If you were working with a 
traditional drawing utility, you would have to redraw all the box.
But with this utility no. That's what you got (figure~\ref{fig:second}).
So, this utility is starting to pay, isn't it?

\begin{figure}
%\vspace{3in}
\caption{Single figure with long names}
\label{fig:second}
\input{drawing2.tex}
\end{figure}

\subsection{ A simple class with attributes and mark of cardinality }
Well, it's time to see a class at its full extent. A class may have 
functions, and it may be included in more than one drawing. In
 that case a mark of cardinality ( a number that says how many
times that class has been drawn ) is shown. An example of such 
a class is what you can see at figure~\ref{fig:third}. In this case
the cardinality is 3.
This is figure is done with the python code: 
\begin{verbatim}
c = a_simple_class()
c.do_name_clase('person')
c.do_attributes(['name' , 'sex', 'money', 'health', 
			    'hobbies', 'dreams'])
c.do_functions(['dream', 'love', 'play soccer', 'diving'])
c.index_of_class(3)

c.do_lines()
c.generate_latex_code('drawing3.tex')

\end{verbatim}
 

\begin{figure}
%\vspace{3in}
\caption{Single figure with attributions, functions and marks}
\label{fig:third}
\input{drawing3.tex}
\end{figure}

\subsection{ Inheritances examples}
Well, till now, it's a very simple program, let's face a more
interesting example. A inheritance of classes. figure~\ref{fig:fourth}

\begin{figure}
%\vspace{3in}
\caption{Simple inheritance }
\label{fig:fourth}
\input{drawing4.tex}
\end{figure}
This is achieved typesetting : 
\begin{verbatim}
    c = a_simple_class()
    c.do_name_clase('person')
    c.do_attributes(['name' , 'sex', 'money', 'health', 
		    'hobbies', 'dreams'])
    c.do_functions(['dream', 'love', 'play soccer', 'diving'])

    c.do_lines()
    d = a_simple_class()
    d.do_name_clase('work')
    d.do_attributes(['salary' , 'post',
		    'labor union', 'productivity', 'qualifications',
		     'capabilities'])
    d.do_functions(['work', 'strike', 'be ill', 'be fired'])

    d.do_lines()
    e = union_derivation()
    e.add_union(c,d)
    e.generate_latex_code('drawing4.tex')

\end{verbatim}
Easy, uh ? :)

But much more complex drawings are also easy to do as shows ~\ref{fig:fifth} , this is a picture of a mother class that has several
daughter classes. 

\emph{ Regretfully, it IS \large NOT possible (right now) to inheritate 
from more than one class. }
Instead , you can use indices to mark several inheritances.

\begin{figure}
%\vspace{3in}
\caption{Several inheritances }
\label{fig:fifth}
\input{drawing5.tex}
\end{figure}

And , well, you can use several levels of inheritances, just be
a bit careful about how you build the code, take this (it makes figure ~\ref{fig:sixth}) as example:
\begin{verbatim}
    d = a_simple_class()
    d.do_name_clase('worker')
    d.do_attributes(['salary' , 'post',
		    'labor union', 'productivity', 'qualifications',
		     'capabilities'])


    d.do_lines()
    f = a_simple_class()
    f.do_name_clase('computer scientist')
    f.do_attributes(['languages' , 'preferred OS',
		    'preferred editor', 'hackerism', 'ATBB'])

    f.do_lines()

    h = union_derivation()
    h.add_union(d,f)

    c = a_simple_class()
    c.do_name_clase('person')
    c.do_attributes(['name' , 'sex', 'money', 'health', 
		    'hobbies', 'dreams'])
    c.do_lines()

    e = union_derivation()
    e.add_union(c,h)
    e.generate_latex_code('drawing6.tex')

\end{verbatim}
\begin{figure}
%\vspace{3in}
\caption{Several levels of inheritances }
\label{fig:sixth}
\input{drawing6.tex}
\end{figure}

Finally a remainder: You can combine this features so you can get
 several levels and with several sons, but... watch the space! The
piece of paper has its limitations.

\subsection{ Associations examples}
Well, I got a bit upset when I realize that fact of multiple inheritances, so 
associations haven't got so complicated, and in fact , you can
do only associations between simple classes and associations,
 so you can't mix associations and derivations, that would have been
fine. figure~\ref{fig:seventh}

\begin{figure}
%\vspace{3in}
\caption{Simple association }
\label{fig:seventh}
\input{drawing7.tex}
\end{figure}


\subsection{Aggregations too!}

You can do aggregations, just replace  ``derivation'' in the
previous examples for ``agregation'' and that's all. As example look
at figure ~\ref{fig:eighth}.

\begin{figure}
%\vspace{3in}
\caption{Multiple aggregation }
\label{fig:eighth}
\input{drawing8.tex}
\end{figure}

\section{ Caveats and bugs}
If you want to do very complex drawings as:
\begin{itemize}
\item several levels of inheritances/agregations and each other
with lots of sons,
\item really deep trees of inheritances, more than four are probably
a really bad idea,
\item several nested associations,
\end{itemize}
then, probably you'll get a shit as outcome. This utility is not
clever, just try to to set the classes in a logical, predetermined
way.

Apart from this caveat, there'll be some bugs, \ldots, or perhaps not. python is rather robust!

\section{Bye bye}
I hope this documentation helps you to use this utility. 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}
