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