diff options
Diffstat (limited to 'macros/latex/contrib/documentation/documentation.dtx')
| -rw-r--r-- | macros/latex/contrib/documentation/documentation.dtx | 552 |
1 files changed, 552 insertions, 0 deletions
diff --git a/macros/latex/contrib/documentation/documentation.dtx b/macros/latex/contrib/documentation/documentation.dtx new file mode 100644 index 0000000000..f9bdd6cdec --- /dev/null +++ b/macros/latex/contrib/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 |