[en] LaTeX-package 'gmdoc-enhance' - some enhancements for gmdoc. Author: Paul Ebermann 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{} - set the visible comment marker character to . This should be a single character, preferably of category "other" (12). Default is "!" (exclamation mark). \setVisibleCommentColor[]{} - 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{} - inputs (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{} - indikas, kiu signo estu la markilo por forkomentita kodo. Tiu estu signo el kategorio "aliaj" (12). Defaŭlto estas "!" (eksklamsigno). \setVisibleCommentColor[]{} - indikas, per kiu koloro marki la forkomentitan kodon. povas esti forlasita, tiam estu nomita koloro konata al la xcolor-pakaĵo. Alikaze indiku iun kolormodelon konatan al xcolor, kaj 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{} - legas kaj interpretas la enhavon de 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!