Directory macros/latex/contrib/gmdoc-enhance

[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!