documentation (30nov11)

git-svn-id: svn://tug.org/texlive/trunk@24708 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 635 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/documentation/documentation.dtx b/Master/texmf-dist/source/latex/documentation/documentation.dtx
new file mode 100644
index 00000000000..24dc995279f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/documentation/documentation.dtx
@@ -0,0 +1,552 @@
+%
+% \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
\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/documentation/documentation.ins b/Master/texmf-dist/source/latex/documentation/documentation.ins
new file mode 100644
index 00000000000..3c584bc7568
--- /dev/null
+++ b/Master/texmf-dist/source/latex/documentation/documentation.ins
@@ -0,0 +1,83 @@
+\input docstrip.tex

+\keepsilent

+\askforoverwritefalse

+\preamble

+

+-------------------------------------------------------------------

+                          LICENCE

+-------------------------------------------------------------------

+

+This is a generated file.

+

+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)

+

+\endpreamble

+\generate{\file{documentation.sty}{\from{documentation.dtx}{sty}}}

+\Msg{*********************************************************}

+\Msg{*}

+\Msg{* To finish the installation you have to move the}

+\Msg{* following file into a directory searched by TeX:}

+\Msg{*}

+\Msg{* \space\space documentation.sty}

+\Msg{*}

+\Msg{* To produce the documentation run the file documentation.dtx}

+\Msg{* once through LaTeX. Then, run}

+\Msg{*}

+\Msg{* \space\space makeindex -s gglo.ist -o documentation.gls documentation.glo}

+\Msg{*}

+\Msg{* through makeIndex to produce the glossary. Finally, run LaTeX once again.}

+\Msg{* That's all!}

+\Msg{*}

+\Msg{* Happy TeXing!}

+\Msg{*********************************************************}

+\endbatchfile
\ No newline at end of file