summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gmdoc-enhance/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/gmdoc-enhance/README
Initial commit
Diffstat (limited to 'macros/latex/contrib/gmdoc-enhance/README')
-rw-r--r--macros/latex/contrib/gmdoc-enhance/README286
1 files changed, 286 insertions, 0 deletions
diff --git a/macros/latex/contrib/gmdoc-enhance/README b/macros/latex/contrib/gmdoc-enhance/README
new file mode 100644
index 0000000000..28e8f97e31
--- /dev/null
+++ b/macros/latex/contrib/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