diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/gmdoc-enhance/README')
| -rw-r--r-- | Master/texmf-dist/doc/latex/gmdoc-enhance/README | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/gmdoc-enhance/README b/Master/texmf-dist/doc/latex/gmdoc-enhance/README new file mode 100644 index 00000000000..28e8f97e316 --- /dev/null +++ b/Master/texmf-dist/doc/latex/gmdoc-enhance/README @@ -0,0 +1,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!
\ No newline at end of file |