path: root/macros/latex/contrib/documentation/documentation.dtx

%
% \iffalse meta-comment
%
%		-------------------------------------------------------------------
%		                          LICENCE
%		-------------------------------------------------------------------
%		
%		Copyright (C) 2011 by Omar Salazar Morales
%		Laboratory for Automation, Microelectronics and Computational Intelligence
%		Engineering Department
%		Universidad Distrital ``Francisco José de Caldas''
%		Bogotá, Colombia
%		http://www.udistrital.edu.co/
%		
%		This file may be distributed and/or modified under the
%		conditions of the LaTeX Project Public License, either
%		version 1.2 of this license or (at your option) any later
%		version. The latest version of this license is in:
%		http://www.latex-project.org/lppl.txt
%		and version 1.2 or later is part of all distributions of
%		LaTeX version 1999/12/01 or later.
%		
%		This work has the LPPL maintenance status `maintained'.
%		
%		The Current Maintainer of this work is Omar Salazar Morales.
%		
%		This work consists of the source files:
%		 - documentation.dtx (documented LaTeX file)
%		 - documentation.ins (installer)
%		
%		-------------------------------------------------------------------
%		                          LICENCIA
%		-------------------------------------------------------------------
%		
%		Este es un archivo generado.
%		
%		Derechos de autor (C) 2011 por Omar Salazar Morales
%		Laboratorio de Automática, Microelectrónica e Inteligencia Computacional
%		Facultad de Ingeniería
%		Universidad Distrital ``Francisco José de Caldas''
%		Bogotá, Colombia.
%		http://www.udistrital.edu.co/
%		
%		Este archivo puede ser redistribuido y/o modificado
%		bajo las condiciones de la Licencia Pública del Proyecto LaTeX,
%		versión 1.2 o cualquier versión superior (a su opción).
%		La última versión de esta licencia se encuentra en
%		http://www.latex-project.org/lppl.txt
%		y la versión 1.2 o superior es parte de todas las distribuciones
%		de LaTeX versión 1999/12/01 o superior.
%		
%		Este trabajo tiene el estado LPPL de `mantenido'.
%		
%		El responsable del mantenimiento de este trabajo es Omar Salazar Morales.
%		
%		Este trabajo consiste de los archivos fuente:
%		 - documentation.dtx (archivo LaTeX documentado)
%		 - documentation.ins (instalador)		
%
% \fi 
%
% \iffalse
%
%<*drv>
\documentclass{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{documentation.dtx}
\end{document}
%</drv>
%
% \fi
%
% \CheckSum{94}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \DoNotIndex{}
%
% \changes{v0.1}{2011/11/28}{Initial version}
%
% \title{Documentation of source codes with the \LaTeX{}
%        package \textsf{documentation}\thanks{This document
%        is the version~v0.1, 2011/11/28.}}
% \author{Omar Salazar Morales\\
%         Laboratory for Automation, Microelectronics\\ and Computational Intelligence\\
%         Universidad Distrital Francisco Jos\'e de Caldas\\
%         Engineering department\\
%         Bogot\'a, Colombia\\
%         \texttt{osalazarm@correo.udistrital.edu.co}\\
%         \texttt{http://www.udistrital.edu.co}}
% \date{November 28, 2011}
%
% \maketitle
%
% \begin{abstract}
% \noindent
% This document shows the \LaTeX{} implementation of the
% package \textsf{documentation}.
% This package is intented for all software's writers who
% want to document their source codes by using the comments of the
% programming language.
% The source files are processed with \LaTeX{} in order to generate
% the documentation of them. 
% \end{abstract}
%
% \tableofcontents
%
% \section{Introduction}
%
% On environments of software developtment is necessary to make
% the documentation of the source code according to its last modification.
% Sometimes, this is not easy, because of \emph{documentation} and
% \emph{source code} are written on different files.
%
% In order to avoid this situation, where a software maker 
% have to write two different files, \LaTeX{} gives the possibility
% to handle an unique file where source code and documentation
% are together. Through the \textsf{documentation} package a software
% maker can write the source code for his application, and inside of its comments,
% he can document it. It's only neccessary to put \LaTeX{} commands
% inside the comments of the source files.
% Source files are then proccesed by \LaTeX{} to get
% a beautiful document (PDF, DVI, PS, ...)
%
% The real advantage of this technique is that \LaTeX{}
% will be present to handle all the documentation.
% If a software maker wants to put a complex formula
% where he explains a difficult algorithm, then he will be able to do it
% in the usual way with \LaTeX{} commands. 
%
% \section{\textsf{Docstrip} modules}
%
% This package has been developed with the typical \LaTeX's
% documentation techniques. \textsf{Docstrip} has been used
% for the preparation of the source code of the package and its documentation.
%
% The following \textsf{docstrip} modules were implemented to generate
% the different files of this project.
%
% \vskip10pt
% \begin{tabular}{ll}
% \textbf{Option}&\textbf{Result}\\
% \hline
% sty & It generates the package's file |*.sty|\\
% drv & It generates the \LaTeX{} documentation's master file |*.drv|\\
% \end{tabular} 
%
% \section{How to use}
%
% \DescribeMacro{\usepackage}
% This package is used in the usual way.
% You should use the |\usepackage| command in the preamble of your
% master's documentation file as follows
% \begin{verbatim}
% \usepackage[<options>]{documentation}
% \end{verbatim}
% The |<options>| are presented in the next section.
%
% \section{Options}
%
% \DescribeMacro{java}
% |java| option is used when JAVA language is used.
% In this programming language the comment's character is |//|
% when one-line's comments are needed. If multi-line's comments
% are needed then |/*| and |*/| are neccessary.
% Then, all the comments inside your JAVA code have to start with |//|,
% or to be enveloped with |/*| and |*/|.
%
% \DescribeMacro{c}
% |c| option is used when C language is used (or any of its variants like
% C++ or C\#). This is the default option.
% This programming language uses the same comment's character as
% JAVA language, then, this option is the same as |java|.
%
% \DescribeMacro{assembler}
% |assembler| option is used when assembler language is used,
% for example, when you are programming microcontrollers.
% In this programming language the comment's character is semicolon (|;|).
% All the comments (line-by-line) inside your assembler
% code have to start with |;|
%
% \section{How it works}
% 
% \begin{enumerate}
%	\item You should create your source code as usual in
%       C, C++, C\#, JAVA or assembler languages
%       (this step is done inside an IDE (Integrated Development
%       Environment\footnote{Typical IDEs are \emph{KDevelop} on Linux systems,
%                            \emph{Eclipse} on Windows systems or
%                            \emph{Microsoft Visual Studio} on Windows systems.
%                            Be careful when you're saving your source files on these IDEs.
%                            You should guarantee that they have the right coding
%                            as ASCII files})).
%       These programming languages use the following comment's characters
%
%       \begin{tabular}{lll}
%       Programming&Comment's&Name of comment's\\
%       language&character&character\\
%       \hline
%       C,C++,C\#,JAVA&\texttt{//} or \texttt{/*} and \texttt{*/}&Double slash or slash with asterisk\\
%       Assembler&\texttt{;}& Semicolon
%       \end{tabular}
%       
% \item Now, you can add the documentation of your source code
%       inside the comments.
%       You can use \LaTeX{} commands as usual.
%       You should think that you are writing a \LaTeX{}
%       document.
%       If you need to use the comment's character inside your source code,
%       then you will be able to use a \LaTeX{} command as
%       is shown in the following table
%
%       \begin{tabular}{lll}
%       Programming language&Character&\LaTeX{} command\\
%       \hline
%       C,C++,C\#,JAVA&\texttt{/}&|\/|\\
%       C,C++,C\#,JAVA&\texttt{*}&|\*|\\
%       Assembler&\texttt{;}& |\;|
%       \end{tabular}
%
% \item Any piece of source code have to be enveloped by
%       |\begin{sourcecode}| and |\end{sourcecode}|.
%       Just before of these two \LaTeX{} commands, you have to
%       put your comment's character \emph{without spaces}.
%       In C or JAVA, you have to use |//| before |\begin{sourcecode}| and |\end{sourcecode}|.
%       For example, if you are writing a C code,
%       then a piece of source code looks like
%       \begin{verbatim}
%       /*
%          This is helloworld.c
%       
%          Comments with \LaTeX{} commands...
%
%       */
%       //\begin{sourcecode}
%       #include<stdio.h> // Header file
%       //\end{sourcecode}
%       //
%       // More comments with \LaTeX{} commands... 
%       //
%       //\begin{sourcecode}
%       void main (void)
%       {
%          printf("Hello world!\n"); // "Hello world" message
%       }
%       //\end{sourcecode}
%       /*
%          More comments with \LaTeX{} commands...
%       */
%       \end{verbatim}
%       In C or JAVA you can use |//| or |/*| and |*/| to add comments,
%       but you have to use |//| before |\begin{sourcecode}| and
%       |\end{sourcecode}|.
%
% \item You can add a master's documentation file (|*.tex|) in your IDE.
%       In the preamble of this file you have to use
%       |\usepackage[<options>]{documentation}|.
%       Now, you can read all your source files of your project with the \LaTeX{} command
%       |\inputsourcecode{<source file>}| where |<source file>|
%       is the path of your source file with its
%       extension\footnote{Extension is needed because of some IDEs
%                          create different files with the same name and
%                          different extensions}.
%
%       For the previous example, this file looks like
%       \begin{verbatim}
%       %
%       % This is dochelloword.tex
%       %
%       \documentclass{article}
%       \usepackage[c]{documentation} % Needed
%       \begin{document}
%       \inputsourcecode{helloworld.c} % input your source code
%       \end{document}
%       \end{verbatim}
%       You can use any \LaTeX{} class (for example,
%       \textsf{article}, \textsf{book}, \textsf{report}, ...)
%       and any number of |\inputsourcecode| commands in order to read
%       any number of source files.
%
% \item Run \LaTeX{} as usual to get the documentation of your
%       source code. In the previous example, run
%       |dochelloword.tex| through \LaTeX.
%       |\inputsourcecode| will read your source files
%       and it will extract the documentation
%       from the comments.  
% \end{enumerate}
%
% \StopEventually{\PrintChanges}
%
% \section{Implementation}
%
% \subsection{Package's identification}
%
% \begin{macro}{\NeedsTeXFormat}
% \begin{macro}{\ProvidesPackage}
%
% Package \textsf{documentation} was created to use it with \LaTeXe.
%
%    \begin{macrocode}
%<*sty>
\NeedsTeXFormat{LaTeX2e}%
\ProvidesPackage{documentation}%
[2011/11/28 v0.1 Make the documentation for your source code]%
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Preliminaries}
%
% \begin{macro}{\ifDOC@javalang}
% \begin{macro}{\ifDOC@Clang}
% \begin{macro}{\ifDOC@assemblerlang}
%
% The boolean variables |\ifDOC@...lang| are used to determine
% which programming language is especified by the user according to the
% following table.
% \vskip10pt
%
% \begin{tabular}{ll}
% \hline
% Variable&Programming language\\
% \hline
% |\ifDOC@javalang|& JAVA\\
% |\ifDOC@Clang|& C (or C++ and C\#)\\
% |\ifDOC@assemblerlang|& Assembler\\
% \hline
% \end{tabular}
% \vskip10pt
%
% These variables begin with a |false| value.
% 
%    \begin{macrocode}
\newif\ifDOC@javalang     \DOC@javalangfalse
\newif\ifDOC@Clang        \DOC@Clangfalse
\newif\ifDOC@assemblerlang\DOC@assemblerlangfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Options}
%
% \begin{macro}{java}
%
% |java| option calls all the necessary code which is needed to make
% the documentation for JAVA language. This programming language uses the 
% comment's characters |//| for one-line's comments and
% |/*...*/| for multi-line's comments.
%
% This option gives |true| value to |\ifDOC@javalang| and
% |false| to others.
% Inside this option, |\DOC@changeccofcommentchar| and
% |\DOC@definecsofcommentchar| are defined in order to
% change the |\catcode| of |/| and |*| as desire,
% and to define the macros |\/| and |\*| to print
% |/| and |*| inside the text of the source files.
% 
%    \begin{macrocode}
\DeclareOption{java}{%
  \DOC@javalangtrue \DOC@Clangfalse
  \DOC@assemblerlangfalse
  \gdef\DOC@changeccofcommentchar#1{\catcode`/=#1
                                    \catcode`*=#1}%
  \gdef\DOC@definecsofcommentchar{\chardef\/=`/
                                  \chardef\*=`*}}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{c}
%
% This option is almost the same as |java|.
%
%    \begin{macrocode}
\DeclareOption{c}{%
  \DOC@javalangfalse \DOC@Clangtrue
  \DOC@assemblerlangfalse
  \gdef\DOC@changeccofcommentchar#1{\catcode`/=#1
                                    \catcode`*=#1}%
  \gdef\DOC@definecsofcommentchar{\chardef\/=`/
                                  \chardef\*=`*}}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{assembler}
%
% |assembler| option calls all the necessary code which is needed to make
% the documentation for assembler language. This programming language uses the 
% comment's characters |;| for all kind of comments.
%
% This option gives |true| value to |\ifDOC@assemblerlang| and
% |false| to others.
% Inside this option, |\DOC@changeccofcommentchar| and
% |\DOC@definecsofcommentchar| are defined in order to
% change the |\catcode| of |;| as desire,
% and to define the macro |\;| to print
% |;| inside the text of the source files.
%
%    \begin{macrocode}
\DeclareOption{assembler}{%
  \DOC@javalangfalse \DOC@Clangfalse
  \DOC@assemblerlangtrue
  \gdef\DOC@changeccofcommentchar#1{\catcode`;=#1}%
  \gdef\DOC@definecsofcommentchar{\chardef\;=`;}}%
%    \end{macrocode}
% \end{macro}
%
% All the other options which are specified by the user,
% but which are not defined, give an error message as \emph{unknown
% options}.
%
%    \begin{macrocode}
\DeclareOption*{%
  \PackageError{documentation}%
  {Unknown option `\CurrentOption'}%
  {See the documentation for more details}}%
%    \end{macrocode}
%
% Now, it's necessary to process all the options which were especified
% by the user. |c| option is used as the default.
%
%    \begin{macrocode}
\ExecuteOptions{c}\ProcessOptions\relax
%    \end{macrocode}
%
% \subsection{The source code}
%
% \begin{environment}{sourcecode}
%
% |\begin{sourcecode}| and |\end{sourcecode}| is the way
% as an user gives the source code for his application.
% All source code has to be enveloped with this environment
% in order to write it |verbatim|.
% The real difference with respect to |verbatim| is that
% |sourcecode| recognizes the comment's character of the
% programming language.
% This environment permits to write the comment's character
% inside without any special \LaTeX{} command (like |\/|, |\*| or |\;|).
% The only restriction is that you have to use the comment's
% character of your programming language just before
% |\begin{sourcecode}| and |\end{sourcecode}|
% \emph{without spaces} between them.
% |sourcecode| uses the internal macros
% |\@verbatim|, |\frenchspacing|, |\@vobeyspaces|, |\if@newlist|,
% |\leavevmode| and |\endtrivlist|.
% See |ltmiscen.dtx| for more details.
% 
%    \begin{macrocode}
\def\sourcecode{\DOC@changeccofcommentchar{12}%
                \@verbatim \frenchspacing\@vobeyspaces \DOC@sourcecode}%
\def\endsourcecode{\if@newlist \leavevmode\fi\endtrivlist}%
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{\DOC@sourcecode}
%
% |\DOC@sourcecode| recognizes the beginning and the end of
% the real source code by using the comment's character of your
% programming language. Then, this macro depends on the language.
% This macro begins changing some |\catcode|s of some characters
% because it's needed to say to \LaTeX{} where is
% the end of the source code. This is done inside a group
% because it's needed to keep local all changes.
%
%    \begin{macrocode}
\begingroup
  \catcode`|=0   \catcode`[= 1
  \catcode`]=2   \catcode`\{=12
  \catcode`\}=12 \catcode`\\=12
  |catcode`/=12  |catcode`;=12
%    \end{macrocode}
%
% Now, |\DOC@sourcecode| is defined according to the language.
% It's needed to say to \LaTeX{} that source code
% will finish with the comment's character of the
% programming language which is followed by |\end{sourcecode}|
% \emph{without spaces}.
% At the end, the group is closed.
% 
%    \begin{macrocode}
  |ifDOC@javalang
    |gdef|DOC@sourcecode#1//\end{sourcecode}[#1|end[sourcecode]]%
  |fi
  |ifDOC@Clang
    |gdef|DOC@sourcecode#1//\end{sourcecode}[#1|end[sourcecode]]%
  |fi
  |ifDOC@assemblerlang
    |gdef|DOC@sourcecode#1;\end{sourcecode}[#1|end[sourcecode]]%
  |fi
|endgroup
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\inputsourcecode}
%
% This is the way as an user |\input|s his source code.
% This command uses the classical |\input| \LaTeX{} command.
% It begins with the definition of |\DOC@path| as the path of the source file.
% |\DOC@path| is necessary because of UNIX systems use |/|
% as a delimiter on its directory tree (for example |/usr/share/local/|),
% and JAVA and C use the same character as comment's character.
% Everything is done inside a group.
%
%    \begin{macrocode}
\def\inputsourcecode#1{%
\begingroup
  \def\DOC@path{#1}%
%    \end{macrocode}
%
% Now, it's time to define the right command secuence if
% an user wants to print the comment's character inside
% the documentation, also,
% it's changed the |\catcode| of the comment's character which
% is treated as an space (catcode 10).
% 
%    \begin{macrocode}
  \DOC@definecsofcommentchar
  \DOC@changeccofcommentchar{10}%
%    \end{macrocode}
%
% At the end, the source file is red.
% Notice that |\inputsourcecode| keeps all changes local.
% Then, your source file doesn't affect any other part of
% your \LaTeX{} document. 
% 
%    \begin{macrocode}
  \expandafter\input\DOC@path
\endgroup}%
%</sty>
%    \end{macrocode}
% \end{macro}
%
% \Finale
%
\endinput