X-Git-Url: http://gitweb.hachti.de/?a=blobdiff_plain;f=pc-tools%2Fldc2%2Fdoc%2Fimpl_spec.tex;h=466e78b8a55be80cccdb7e1a624255babbf08d1c;hb=d65ad4d76066646927175a9896fe348bc0691e68;hp=474f722be9b4783c572f46996dcecb108100ce31;hpb=09c71e8a036e6034821398f7ef4c7a092804a571;p=h316.git

diff --git a/pc-tools/ldc2/doc/impl_spec.tex b/pc-tools/ldc2/doc/impl_spec.tex
index 474f722..466e78b 100644
--- a/pc-tools/ldc2/doc/impl_spec.tex
+++ b/pc-tools/ldc2/doc/impl_spec.tex
@@ -1,16 +1,84 @@
 \section{Implementation Specification}
 
-\subsection{Building \pname}
+\subsection{Theory of operation}
+\subsubsection{Overview}
+
+The program is implemented using standard C++.
+
+While the data structures according to \cite{ser16:progref}
+are designed consequently object oriented,
+most of the actual processing of the data after reading in is done 
+by the routines contained in
+\verb|main.cpp|, \verb|config.cpp| and \verb|tool.cpp|.
+
+Program configuration is capsuled into the class \verb|configuration_manager|,
+used by the routines in \verb|config.cpp|.
+
+\subsubsection{Program flow}
+The \verb|main()| routine sets up the working environment using the \verb|do_config()|
+subroutine contained in \verb|config.cpp|. This contains parsing the command line,
+reading a configuration file, and setting the global \verb|cfg_*| flags. The input and
+output file descriptors \verb|in_fd| and \verb|out_fd| are assigned to 0 and 1 respective
+files as stated in the configuration (command line option or configuration file).
+The \verb|configuration_manager| is able to dynamically generate help output for all
+options.
+
+The next call is \verb|read_tape()|, the data input routine. In \verb|read_tape()|,
+the static factory method \verb|tape_block::gen_from_fd()| is used to create and
+check blocks, taking data directly from the global file descriptor \verb|in_fd|.\\
+At the end of \verb|read_tape()|, the vector \verb|tape| has been filled with
+pointers to instances of \verb|tape_block|.
+
+In the next step, the routine \verb|process_tape()| is called, in which
+integrity checks on object level and splitting to files (if desired)
+are accomplished. Every valid and complete object consist of either one
+single \verb|eot_block| or a series of \verb|data_block|s, while the last block
+of each object must be one of the types which mark the end of an object.
+
+After all that, \verb|process_symbols()| is called. This routine generates three vectors
+containing symbol names: \verb|exported|, \verb|called|, and \verb|unsatisfied|.
+The latter is the difference of \verb|called| and \verb|exported|.\\
+If desired, those vectors are written out to \verb|out_fd|, one symbol per line.
 
+\subsubsection{Block factory}
+The software makes use of C++ virtual methods allowing for convinient processing of
+multiple kinds of blocks without knowing much about the block type currently worked 
+on.\\
+The block factory consists of the static factory method \verb|tape_block::gen_from_fd()| 
+and a corresponding private constructor of class \verb|tape_block|. The constructor 
+creates a block and reads data from the given file descriptor. The factory method 
+then tries to determine the block's type and recreate an object of the most accurate
+subtype applying to the block. Information about the block types is contained in 
+the block data itself.  A pointer to the newly created object is returned or one 
+of the exception defined in class \verb|tape_block| is thrown.
+
+
+\subsection{Detailed documentation}
+\subsubsection{Doxygen}
+The source code has been documented using  Doxygen and appropriate
+comments throughout the program code. Doxygen generates a very useful
+html documentation containing very usable diagrams (not strictly UML, but
+very fine anyway), lists and detailed documentation.
+
+The Doxygen configuration also creates man pages, latex sources with
+makefile for PostScript and PDF output.
+
+\subsubsection{Not in this document}
+I have decided not to create UML class and collaboration diagrams because
+in my opinion the Doxygen documentation perfectly covers those needs.
+
+The project already took several times the time I allocated in my schedule....
+
+\subsection{Building \pname}
 \subsubsection{Build environment}
 The program has been successfully built under Linux with the following
 programs:
 \begin{itemize}
-\item GCC version 4.1.2
-\item GNU make version 3.81
-\item Doxygen version 1.4.2
+\item GNU GCC, version 4.1.2
+\item GNU make, version 3.81
+\item Doxygen, version 1.4.2
 \item Debian teTex package, version 3.0
-\item Graphviz dot version 2.8
+\item Graphviz dot tool, version 2.8
 \end{itemize}
 At least the the software (without docs) should be compile on any 
 POSIX compatible system with a fairly recent GCC and GNU make 
@@ -21,7 +89,6 @@ There is a simple \verb|Makefile| which eases the standard build
 process for the application and documentation. Changes may be
 necessary to compile on a system other than stated in the last 
 paragraph.
-\\
 
 To build the application, follow these easy steps:
 \begin{itemize}
@@ -49,3 +116,5 @@ The Doxygen output is placed in the subdir \verb|doxy|.
 including binaries and documentation.
 
 \end{itemize}
+
+%  End of the show....
\ No newline at end of file