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
|
[en]
LaTeX-package 'gmdoc-enhance' - some enhancements for gmdoc.
Author: Paul Ebermann <Paul-Ebermann@gmx.de>
License: LPPL 1.3b or later, maintained
(see http://www.latex-project.org/lppl/).
All Documentation (other than this file) is in german.
This package provides some enhancements for the gmdoc package:
nicer formatting for multiple line inline comments,
an ability to "comment out" some code, and a macro to input
other files in "normal" LaTeX mode.
The package is based on the package gmdoc (from
Grzegorz `Natror' Murzynowski) and needs it and its
required packages (gmutil, gmverb, gmiflink, hyperref,
multicol, color, makeidx).
The typesetting of the documentation needs additionally
class scrartcl (from KOMA-script) and some LaTeX base
packages.
The package comes as .dtx + .ins.
Run "latex gmdoc-enhance.ins" to create the style file (and maybe put
it to texmf/tex/latex/paul/, if your docstrip is configured
accordingly), run (after that and maybe updating your TeX hash)
"latex gmdoc-enhance.dtx" to create the documentation.
Usage
-------
(1) Write your dtx-files for documenting with gmdoc, not doc.
(See the gmdoc-documentation for details.)
(2) Put
\usepackage[...]{gmdoc-enhance}
in the preamble of the documentation driver.
(This package itself is calling gmdoc without
any options - if you need options, put
\usepackage[...]{gmdoc} before this line.)
(3) Use options and/or user macros to change the look.
(4) If you want visible "commented out" code, change the
code to use the marker.
Options:
- - - -
inline - mark more-than-one-line inline comments on the
following lines with %, and change the look of the
inline comments a bit.
visible - enable special treating of "comment out" (see below),
with blue highlight and "!" as marker.
User macros:
- - - - - -
\InlineCommentsWithPercent - same as option 'inline', but can be
switched everywhere.
\normalInlineComments - switch back to normal gmdoc behaviour for
inline comments.
\setVisibleCommentChar{<marker>} - set the visible comment
marker character to <marker>. This should be a
single character, preferably of category "other" (12).
Default is "!" (exclamation mark).
\setVisibleCommentColor[<model>]{<color>} - indicate which color
to use for commented out code. This is simply given to
the color package (more precisely, xcolor), so should
be in a format recognized by this package.
Default is nothing (don't change color).
\activateVisibleComments - enable using "commented out" code.
\normalInput{<file>} - inputs <file> (if existing), but with normal
LaTeX catcode conventions active.
How to use the "comment out" feature:
- - - - - - - - - - - - - - - - - - -
This is useful if you (for debugging purposes, for example)
want to deactivate some code, but also don't want it to be
executed in the documentation part (which would give often some
strange error messages.
One way to solve this (without this package) would be using
%^^A or %^^B on the beginning of these lines (to ignore these
completely).
With this package, you can show this code as commented out in
the output.
Some example code:
---
\ifx aa
%!\doSomething% do something -- commented out.
\doAnotherthing% do something other instead.
\fi
---
So, after the first %, put your comment marker (default !), and
then more TeX code. Until the next %, it is shown as commented out
code, then begins an inline comment.
Have fun!
-------------
[de]
LaTeX-Paket 'gmdoc-enhance' - Verbesserungen für gmdoc.
Autor: Paul Ebermann (Paul-Ebermann@gmx.de).
Lizenz: LPPL 1.3b oder später, mit Maintenance-Status
"author-maintained". Siehe http://www.latex-project.org/lppl/.
Geschrieben für eigenen Gebrauch
(d.h. die Dokumentation von LaTeX-Paketen von Paul Ebermann), aber
vielleicht ist es auch für andere von Nutzen.
Dieses Package basiert auf gmdoc von Grzegorz `Natror' Murzynowski
zur Dokumentation von (La)TeX-Paketen und fügt ein paar weitere
nützliche Funktionen hinzu, wie Markierung der inline-Kommentare
als solche auch in Folgezeilen, sichtbare Kommentare (auskommentierter
Code), und die Möglichkeit, andere LaTeX-Dateien im normalen Modus
einzubinden (anstatt im gmdoc-Modus).
Das Paket kommt als .dtx + .ins.
Mit "latex gmdoc-enhance.ins" wird die .sty-Datei erstellt (und
eventuell gleich nach texmf/tex/latex/paul/ installiert,
wenn docstrip entsprechend eingerichtet ist), mit
"latex gmdoc-enhance.dtx" kann (danach und eventuell nach einer
Aktualisierung der TeX-Dateidatenbank) die Dokumentation neu
erstellt werden.
Zur Verwendung siehe pauldoc.pdf.
----------
[eo]
LaTeX-pakaĵo 'gmdoc-enhance' - plibonigoj por gmdoc.
(Se vi ne scias, kio estas gmdoc, legu sube.)
Aŭtoro: Paŭlo Ebermann (Paul-Ebermann@gmx.de).
Licenzo: LPPL 1.3, 'maintained'
(-> http://www.latex-project.org/lppl/).
Kreitaj por propra uzo, sed eble iom de ĝi ankaŭ
uzeblas por aliaj.
La dokumentaro (escepte tiu ĉi dosiero) estas nur en la germana
lingvo.
La pakaĵo estas bazita sur la pakaĵo gmdoc (de Grzegorz
`Natror' Murzynowski) kaj bezonas ĝin kaj ĝiajn bezonatajn
pakaĵojn (laŭ ties dokumentaĵo: gmutil, gmverb, gmiflink,
hyperref, multicol, color, makeidx).
Por produkti la dokumentaĵon, vi ankaŭ bezonas la
dokument-klason scrartcl (de KOMA-script) kaj kelkajn bazajn
LaTeX-pakaĵoj.
La pakaĵo venas en .dtx + .ins.
Voku "latex gmdoc-enhance.ins" por krei la .sty-dosieron (kaj
eble meti ĝin al texmf/tex/latex/paul/, se via docstrip estis
konfigurita laŭe), voku "latex gmdoc-enhance.dtx" por rekrei
la dokumentaron.
Uzado
-------
Enkonduko (Kio estas gmdoc)
- - - - - - - - - - - - - -
gmdoc estas alternativa sistemo (al doc) por dokumenti
(La)TeX-pakaĵojn. Oni tiel ne plu bezonas marki ĉiujn
kodo-pecojn, sed gmdoc mem trovas ĝin.
Ankaŭ eblas uzi komentojn en la sama linio kiel kodo, kiu
poste tamen povas daŭrigi en pluraj linioj.
Se vi volas krei proprajn LaTeX-pakaĵojn, pripensu uzi ĝin
anstataŭ la doc-pakaĵo, kiu estas liverita kun LaTeX mem.
(La kodo de via pakaĵo ja aspektas iom alie, depende de la
elekto.)
Por vidi ekzemplojn de gmdoc-komentita kodo, rigardu la
fontokodon de tiu pakaĵo (gmdoc-enhance.dtx), la pakaĵo
monatnomoj, aŭ la pakaĵojn de Grzegorz `Natror' Murzynowski
(gm*.sty/gm*.cls).
gmdoc-enhance (tiu ĉi pakaĵo) nun aldonas kelkajn funkciojn,
kiujn mi konsideris mankantaj en gmdoc.
Kiel uzi
- - - - -
(1) Kiel supre menciite, necesas formati/dokumenti vian pakaĵon
por uzo kun gmdoc. (Tio fakte estas pli facila ol por doc.)
(2) Metu
\usepackage[...]{gmdoc-enhance}
en la kapliniojn de la dokumentaĵ-stirilo.
(3) adaptu la opciojn kaj/aŭ uzu individuajn makroojn
(vidu sube).
(4) Se vi volas forkomenti kodon, uzu la markilon.
Opcioj:
- - - -
inline - marku sekvajn liniojn se en-liniaj komentoj komence
per %, kaj krome iom ŝanĝu la aspekton de tiuj
komentoj.
visible - ŝaltu la specialan traktadon de for-komentita kodo,
kun blua koloro.
Uzantaj makrooj:
- - - - - - - -
\InlineCommentsWithPercent - ŝaltu la 'inline'-opcion, ekde
la loko, kie ĝi aperas.
\normalInlineComments - reŝaltu al la normala gmdoc-aspekto.
\setVisibleCommentChar{<markilo>} - indikas, kiu signo estu la
markilo por forkomentita kodo. Tiu estu signo el kategorio
"aliaj" (12).
Defaŭlto estas "!" (eksklamsigno).
\setVisibleCommentColor[<kolormodelo>]{<koloro>} - indikas, per kiu
koloro marki la forkomentitan kodon. <kolormodelo> povas
esti forlasita, tiam <koloro> estu nomita koloro konata
al la xcolor-pakaĵo. Alikaze <kolormodelo> indiku iun
kolormodelon konatan al xcolor, kaj <koloro> iun koloron
en tiu kolormodelo. (Ni nur pludonas la informojn al
xcolor, ne mem traktas ilin.)
Defaŭlto estas nenio, t.e. tute ne ŝanĝi la koloron.
\activateVisibleComments - ŝaltu la uzadon de forkomentita kodo
ekde tiu momento.
\normalInput{<dosiero>} - legas kaj interpretas la enhavon de <dosiero>
kun la normalaj \LaTeX-konvencioj aktivaj (ne la gmdoc-specifaj
specialaĵoj).
Kiel forkomenti kodon
- - - - - - - - - - -
Tiu funkcio estas uzenda, se vi volas forigi iujn partojn
(kutime tutajn liniojn) de la kodo portempe, sed ilia TeX-codo
ne estu parto de la komento (kiu povas kaŭzi strangajn erarojn),
sed aperu kiel "forkomentita" en la rezulto.
(Ĉe normala doc-moduso tiu problemo ne okazas, ĉar tie ne
eblas havi tiujn en-liniajn komentojn.)
Por fari tion, uzu '%!' por komenci vian forkomentitan kodon,
kaj poste aperu '%' kun normala en-linia komento (eble malplena).
Jen ekzemplo:
---
\ifx aa
%!\doSomething% faru ion -- forkomentita.
\doAnotherthing% faru ion alian anstataŭe.
\fi
---
La ! ne aperas, la '%\doSomething%' ja.
(Kaj anstataŭ ! endas uzi alian signon, se vi ŝanĝis ĝin
per \setVisibleCommentChar.)
Bonan dokumentadon!
|
