summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/documentation/documentation.dtx
blob: f9bdd6cdecf001486e255d3550c7804349385ffe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
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