diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/documentation/documentation.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/documentation/documentation.dtx | 552 |
1 files changed, 552 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 |