summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/cstex/opmac-d.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-04-15 21:39:56 +0000
committerKarl Berry <karl@freefriends.org>2016-04-15 21:39:56 +0000
commit1450af3d3e883477599a3de6492b6cfdb8f2fba4 (patch)
tree1332b6ef07f634e401a425f18e916fd99822816c /Master/texmf-dist/doc/cstex/opmac-d.tex
parent5e77de80c3619d378c8a85ab0e2413086a57a8a5 (diff)
cstex (15apr16)
git-svn-id: svn://tug.org/texlive/trunk@40539 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/cstex/opmac-d.tex')
-rw-r--r--Master/texmf-dist/doc/cstex/opmac-d.tex197
1 files changed, 149 insertions, 48 deletions
diff --git a/Master/texmf-dist/doc/cstex/opmac-d.tex b/Master/texmf-dist/doc/cstex/opmac-d.tex
index 8643c42bdba..767b6a096e1 100644
--- a/Master/texmf-dist/doc/cstex/opmac-d.tex
+++ b/Master/texmf-dist/doc/cstex/opmac-d.tex
@@ -8,7 +8,7 @@
% UTF-8 encTeX has a conflict with DocByTeX
\chyph
-\def\projectversion{Dec. 2014}
+\def\projectversion{Apr. 2016}
\def\headtitle{OPmac}
\widowpenalty=10000
@@ -25,7 +25,7 @@
\input docby.tex
\setlinecomment{\percent} \noactive{\nb\percent} \noactive{\percent\cbrace}
-\noactive{\nb fontdimen}
+\noactive{\nb fontdimen} \noactive{\nb empty}
\title OPmac -- rozšiřující makra plain\TeX{}u
@@ -175,8 +175,25 @@ druhé závorky. Pomocí "\futurelet" uloží zkoumaný znak do "\next" a spustí
\inext {isnextchar}{\empty}{+-}
+Makro \db eoldef "\foo#1{<makro>}" pracuje jako "\def", ale parametr "#1" je
+separován koncem řádku. Takže třeba
+
+\begtt
+\eoldef\foo#1{param={#1}}
+\foo tady je parametr
+\endtt
+expanduje na "param={tady je parametr}". Implementace se opírá o to, že
+při "\eoldef\foo" se definují "\foo" a "\\foo:M".
+Přitom "\foo" ve skupině pozmění catcode znaku pro konec řádku a spustí
+\db eoldefA "\foo". Toto makro načte parametr "#2" do konce řádku (po "^^M"),
+dále ukončí skupinu a spustí "\\foo:M{parametr}". Konečně
+"\\foo:M" vykoná to, co definoval uživatel.
+
+\inext {eoldef}{\empty}{+-}
+
Makro \db maybebreak "<rozměr>" umožní uživateli rozlomit řádek
-nebo stránku v místě použití. Zlom se uskuteční, chybí-li do konce
+nebo stránku v místě použití. Pomocné marko \db maybebreakA se spustí po
+načtení parametru. Zlom se uskuteční, chybí-li do konce
řádku/stránky zhruba méně než "<rozměr>" místa. Jinak se zlom neuskuteční a
nestane se nic. Makro je závislé na módu \TeX{}u (vertikální/horizontální).
Chcete-li jím lámat
@@ -295,7 +312,9 @@ uživatelské dokumentaci.
\dgn \nb ttpenalty
\dgn \nb tthook
\dgn \nb intthook
+\dgn \nb ptthook
\dgn \nb iiskip
+\dgn \nb itemhook
\dgn \nb bibskip
\dgn \nb tabstrut
\dgn \nb tabiteml
@@ -312,6 +331,7 @@ uživatelské dokumentaci.
\dgn \nb sechook
\dgn \nb secchook
\dgn \nb cnvhook
+\dgn \nb prepghook
\dgn \nb pghook
\dgn \nb toclinehook
\dgn \nb fnotehook
@@ -360,9 +380,10 @@ Do nových velikostí tedy půjdeme se starými názvy přepínačů
"\ten<něco>" a to slovo "ten" budeme chápat jen jako historický relikt,
který nám ovšem napoví, že kontrolní sekvence je fontovým přepínačem.
-OPmac si zjistí, zda je definovaný "\regfont". Pokud ne, upozorní na starou
-verzi \csplain{}u na terminálu a potřebná makra si definuje. Je to kopie
-kódu ze souboru "csfontsm.tex" z balíčku \csplain{}.
+OPmac si zjistí, zda je definovaný "\regfont" (tj. je detekován dostatečně
+nový csplain). Pokud ne, upozorní na nedostupnost vicejazyčné podpory na
+terminálu a potřebná makra pro fonty si definuje. Je to kopie kódu ze
+souboru "csfontsm.tex" z balíčku \csplain{}.
\inext {regfont}{\empty}{+-}
@@ -528,6 +549,12 @@ Je-li detekován místo CSplainu e\TeX, nastavíme značky jazyků dle hodnoty
\inext {uselanguage}{\empty}{+-}
+Makro \db isolangset "{<dlouhý-název>}{<iso-zkratka>}" přiřadí dlohému názvu
+jazyka (a související hodnotě registu "\language") jeho
+zkratku dle ISO~639-1 při použití formátu generovaného z "etex.src".
+Naopak, při použití CSplainu makro nedělá nic, protože ISO
+zkratky a jejich propojení na hodnoty "\language" jsou nastaveny
+přímo v CSplainu.
\subsec REF soubor
@@ -555,8 +582,8 @@ Makro \db inputref spustíme na konci čtení souboru "opmac.tex", tedy v
situaci, kdy už budeme mít definovány všechny kontrolní sekvence, které se v
REF souboru mohou vyskytnout. Nyní si toto makro jen připravíme.
Makro ověří existenci souboru "\jobname.ref" a pokud existuje, provede
-"\input \jobname.ref". V takovém případě po načtení REF souboru jej otevře
-k~zápisu a připraví "\wref" do stavu, kdy toto
+"\input \jobname.ref". V takovém případě po načtení REF souboru jej
+pomocí makra "\openrefA" otevře k~zápisu a připraví "\wref" do stavu, kdy toto
makro bude ukládat data do souboru.
\inext {inputref}{^^B\cbrace}{+-}
@@ -564,20 +591,26 @@ makro bude ukládat data do souboru.
Makro \db openref kdekoli v dokumentu si vynutí založení souboru
"\jobname.ref". Toto makro neprovede nic, je-li REF soubor už založen. To
pozná podle toho, že makro "\wref" nemá význam "\wrefrelax". Jestliže soubor
-ještě není založen, makro jej založí, předefinuje "\wref" a vloží první
-řádek do souboru. Tím je zaručeno, že při příštím \TeX{}ování dokumentu
-je soubor neprázdný, takže jej OPmac rovnou přečte a znovu založí na začátku
-své činnosti. Nakonec se "\openref" zasebevraždí, aby se nemuselo při
-opakovaném volání obtěžovat vykonávat nějakou práci. Práce už je totiž
-hotova.
+ještě není založen, makro zavolá \db openrefA, které REF soubor založí,
+předefinuje "\wref" a vloží první řádek do souboru. Tím je zaručeno, že při
+příštím \TeX{}ování dokumentu je soubor neprázdný, takže jej OPmac rovnou
+přečte a znovu založí na začátku své činnosti. Nakonec se "\openref"
+zasebevraždí, aby se nemuselo při opakovaném volání obtěžovat vykonávat
+nějakou práci. Práce už je totiž hotova.
-\inext {openref}{^^B\cbrace}{++}
+\inext {openref}{\count=2 ^^B\cbrace}{++}
Pro zápisy do REF souboru používáme tuto konvenci: první kontrolní sekvence
na řádku je vždy tvaru "\X<název>", takže máme přehled, která kontrolní sekvence
pochází z REF souboru.
+Jako první je do REF souboru vložen příkaz \db Xrefversion "{<číslo>}". Pokud
+toto "<číslo>" mení rovno \db REFversion, REF soubor se nepřečte. Tím
+je zaručeno, že OPmac nezkolabuje při čtení REF souboru kvůli tomu, že je
+zde zmatení verzí. Číslo verze "\REFversion" zvětším o jedničku vždy, když
+v~budoucí verzi OPmac přidám nebo uberu v REF souboru nějakou funkci.
+\inext {REFversion}{\empty}{+-}
\subsec Lejblíky a odkazy
%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -749,10 +782,20 @@ v OPmac takto:
Příkazem "\firstnoindent" dávají tato makra najevo,
že následující odstavec nebude mít odstavcovou zarážku.
+{\bf Upozornění}: Od verze Apr. 2016 jsou makra "\tit", "\chap", "\sec" a
+"\secc" definována pomocí "\eoldef", tedy titulek ve zdrojovém kódu je
+ukončen koncem řádku a ne následujícím prázdným řádkem. Chcete-li mít delší
+titulek ve zdrojovém kódu rozdělen do více řádků, ukončete \uv{pokračovací
+řádky} symbolem~"%".
+Pokud chcete makra "\chap", "\sec" atd. použít uvnitř vlastních maker,
+nelze je použít přímo. Můžete to ale vyřešit třeba takto:
+
+\begtt
+\def\mymacro#1{... \csname\string\sec:M\endcsname{#1} ...}
+\endtt
+
Makro pro titul \db tit počítá s tím, že bude titul na více řádcích. Sází ho
-tedy jako odstavec s~pružnými "\leftskip" a "\rightskip". Příkaz "\unskip"
-těsně za parametrem "#1" odstraní mezeru z konce řádku, která tam obvykle
-je. Teprve poté je nadpis řádně centrován.
+tedy jako odstavec s~pružnými "\leftskip" a "\rightskip".
\inext{tit}{^^B\cbrace}{++}
@@ -795,13 +838,24 @@ zavolají odpovídající makro "\printchap",
V proměnlivé části makra "\dotocnum", tedy v "\dotocnumafter", se řeší
uložení informací o kapitole, sekci nebo podsekci do obsahu. K tomu je
-využito makro \db wcontents, které provede
+využito makro \db wtotoc "<úroveň><font>{<text>}", které vytvoří
\bgroup\def\begtthook{\langleactive}
\begtt
-\write\reffile{\string#1{<expandovaný thetocnum>}{#2}{\the\pageno}}
+\write\reffile
+ {\string\Xtoc{<úroveň>}{<font>}{<expandovaný thetocnum>}{<text>}{\the\pageno}}
\endtt
\par\egroup
+\noindent
+Přitom "<úroveň>" je číslo rovné nule, jedná-li se o kapitolu, je rovné
+jedné, jedná-li se o sekci a je rovno dvěma, jedná-li se podsekci.
+
+\inext{wtotoc}{^^B\cbrace}{++}
+
+Makro \db wcontents je v kódu ponecháno pro zpětnou kompatibilitu (ukládalo
+do REF souboru údaje pro obsah "\Xchap", "\Xsec" a "\Xsecc").
+Někdy v roce 2016 je pravděpodobně zcela odstraním.
+
\inext{wcontents}{^^B\cbrace}{++}
Makro \db dotocnum "{<text>}" umístí cíl odkazu do místa, které je od
@@ -984,15 +1038,23 @@ Pomocí \db ifischap se budeme ptát, zda v dokumentu jsou kapitoly.
V době čtení REF souboru vložíme veškerá data obsahu do makra "\toclist"
tak, že v tomto bufferu budeme mít za sebou sekvence "\tocline" následované pěti
-parametry. Makra \db Xchap, \db Xsec a \db Xsecc
-mají parametry "{<číslo>}{<text>}{<strana>}" a jsou definovány následovně:
+parametry, které jsou shodné, jako parametry
+makra \db Xtoc "<úroveň><info><číslo><text><strana>".
+
+\inext{Xtoc}{}{++}
+
+Makra \db Xchap, \db Xsec a \db Xsecc přetrvávají v kódu jen pro zpětnou
+kompatibilitu a někdy v roce 2016 je odstraním.
\inext{Xchap}{\empty}{+-}
-Makro \db tocline "{<odsazení>}{<font>}{<číslo>}{<text>}{<strana>}" vytvoří
-řádek obsahu. Řádek tiskneme jako odstavec, protože "<text>" může být třeba
-delší. Registr "\leftskip" nastavíme jako součin "<odsazení>" krát "\iindent".
-Pokud se v dokumentu vyskytují kapitoly, odsadíme ještě o další "\iindent".
+Makro \db tocline "{<úroveň>}{<info>}{<číslo>}{<text>}{<strana>}" vytvoří
+řádek obsahu. Údaj "<úroveň>" je číslo 0 pro kapitolu, 1 pro
+sekci a 2 pro podsekci. Údaj "<info>" používá OPmac pro informaci
+o fontu, kterým se má tisknout řádek v obsahu.
+Řádek obsahu tiskneme jako odstavec, protože "<text>" může být třeba
+delší. Registr "\leftskip" nastavíme jako součin "<úroveň>" krát "\iindent".
+Pokud se v~dokumentu vyskytují kapitoly, odsadíme ještě o další "\iindent".
Registr "\rightskip" nastavíme na 2"\iindent", aby delší "<text>" se zalomil
dřív než v místě, kde jsou stránkové číslice. Konec odstavce se stránkovou
číslicí pak vytáhneme mimo tento rozsah pomocí "\hskip-2\iindent". Odstavec
@@ -1343,6 +1405,9 @@ makro s~neseparovaným parametrem. Ovšem my budeme chtít mezeru přečíst.
Makrem "\setignoredchars" se zcela nakonec nastaví ignorovaným znakům
"\lccode" tečky.
+Makro \db sortingmessage ukládá informaci o použitém "\sortingdata", což
+bude později vypsáno na terminál makrem "\dosorting".
+
Makro \db setsecondarysorting se volá opakovaně a příležitostně pro případy,
kdy jsou hesla z~hlediska primárního řazení totožná. Nastaví jinak "\lccode"
znaků. Tentokrát mají všechny znaky ze "\sortingdata" rozdílný "\lccode", ve
@@ -1428,7 +1493,8 @@ skupiny. Pak osmipoložkové~atd. V~závěru (na řádku~\cite[konecsortu])
je první skupina celá setříděná a druhá obsahuje "\end", tj.
všechny položky jsou už setříděné v první skupině, takže stačí
ji uložit do "\iilist" a ukončit činnost. Pomocí \db gobbletoend
-odstraníme druhé "\end" ze vstupního proudu.
+odstraníme druhé "\end" ze vstupního proudu. Makro \db sortreturn ukončí
+činnost až po koncové "\relax" a dále vykoná svůj parametr.
\noactive{dvojice}
\ilabel [merge:porovnani] {isAleB}
@@ -1436,7 +1502,7 @@ odstraníme druhé "\end" ze vstupního proudu.
\ilabel [merge:p1] {ifx,}
\ilabel [merge:p2] {fif\nb mergesort\cbrace}
\ilabel [konecsortu] {empty\nb iilist}
-\inext {def\nb mergesort }{^^B\cbrace}{++}
+\inext {def\nb mergesort }{\empty}{+-}
{\def\quotehook{\catcode`\<12}
Jádro "\mergesort" vidíme na řádcích~\cite[merge:porovnani]
@@ -1601,7 +1667,7 @@ Není-li použit pdf\TeX{}, některá makra pro barvu deaktivujeme:
\inext{ifpdftex}{\empty}{+-}
-Makro \db draft vloží do "\headline" box nulové výšky a šířky "\draftbox",
+Makro \db draft vloží do "\prepghook" box nulové výšky a šířky "\draftbox",
který vystrčí svou šedou sazbu ven ze svého rozměru a je tištěn dřív, než
jakýkoli jiný materiál na stránce.
@@ -1688,7 +1754,20 @@ Ovšem po použití makra \db hyperlinks "{<barva-lok>}{<barva-url>}" se
uvedená makra "\toclink", "\pglink", "\citelink" a "\reflink" probouzejí k
životu. Zde je také definováno makro \db urlcolor.
-\inext{hyperlinks}{\empty}{+-}
+\inext{hyperlinks}{^^B\cbrace}{+-}
+
+Makro "\toclink" čte parametr ve fromátu \uv{číslo kapitoly, sekce,
+kapitoly.sekce atd.}.
+Makro "\pglink" zase vyžaduje svůj parametr jen jako číslo strany. Když je dokument
+rozdělen do bloků a v~každém je samostatné číslování stran, respektive bloky
+obsahují samostatné číslování sekcí, je potřeba rozlišit mezi těmito bloky,
+aby interní odkaz při "\hyperlinks" v dokumentu byl jednoznačný. Proto
+jsou zavedena (implicitně prázdná) makra \db tocilabel a \db pgilabel.
+Každý blok v dokumentu by pak měl mít svůj vlastní "\tocilabel" a
+"\pgilabel" o což se musí programátor maker postarat sám.
+
+
+\inext{tocilabel}{}{+-}
Pdf\TeX{}ové primitivy pro klikací odkazy dovolují dopravit do PDF další
atributy odkazu za slovem "attr". Tam je možné dát najevo, že chceme vidět
@@ -1727,7 +1806,7 @@ kategorie. Pak by ale makro "\url" nefungovalo uvnitř parametrů jiných
maker. V zájmu jednoduchosti makra "\url" to neděláme. Takže pokud uživatel
má v URL znak procento, musí psát "\%"
nebo si změní kategorie sám. Podobná poznámka platí pro znaky "{", "}", "\",
-"#" a "$".
+"#" a "$". %$
\subsec Outlines -- obsah v záložce PDF dokumentu
@@ -1748,7 +1827,7 @@ znovu projde "\toclist".
\inext{def\nb outlines}{^^B\cbrace}{++}
-V makru \db outlinesA "{<odsazení>}{<font>}{<číslo>}{<text>}{<strana>}"
+V makru \db outlinesA "{<odsazení>}{<info>}{<číslo>}{<text>}{<strana>}"
počítáme potomky. Makro je navrženo tak, aby bylo
snadno rozšířitelné na libovolnou úroveň hloubky stromu, nicméně pro potřeby
OPmac stačí hloubka tři (kapitoly, sekce, podsekce). Úroveň uzlu přečteme v
@@ -1775,15 +1854,9 @@ když je ji poprvé potřeba zvětšit o~jedničku.
\inext{outlinesA}{\count=2 ^^B\cbrace}{++}
-V makru \db outlinesB "{<odsazení>}{<font>}{<číslo>}{<text>}{<strana>}"
-vkládáme jednotlivou položku obsahu do záložek pomocí pdf\TeX{}ového
-primitivu\hfil\break
-"\pdfoutline goto name{<lejblík>} count<potomci> {<text>}".
-Číslo "<potomci>" je opatřeno znaménkem mínus právě tehdy, když chceme, aby
-položka ve výchozím stavu nezobrazovala své potomky, ale jen trojúhelníček.
-Potomci se zobrazí až po kliknutí na trojúhelníček. V makru \db outlinelevel
-máme makrem "\outlines" připravenu úroveň rozevření, kterou si uživatel
-přeje. Nejprve přičtením "\count<odsazení>" dostaneme řadu
+V makru \db outlinesB "{<odsazení>}{<info>}{<číslo>}{<text>}{<strana>}"
+vkládáme položku obsahu do záložek.
+Nejprve přičtením "\count<odsazení>" dostaneme řadu
"\count0:\count1:\count2" do stejného stavu, jako v předchozím prvním průchodu
a máme tím jednoznačně přidělen uzel stromu.
Do "\tmpnum" vložíme údaj o počtu potomků daného uzlu. K tomu je potřeba
@@ -1800,8 +1873,28 @@ vzápětí provedeme, ale nejprve ještě do toho může promluvit uživatel v makru
\inext{outlinesB}{^^B\cbrace}{++}
-Makro \db setcnvcodesA zkontroluje podle definovanosti "\r", zda je zapnutý
-"\csaccents" a pokud je, expanduje "\toasciidata".
+Makro \db outlinesC "{<úroveň>}{<lejblík>}{<minus>}{<potomci>}{<text>}"
+konečně zavolá primitivní
+"\pdfoutline goto name{<lejblík>} count<minus><potomci> {<text>}".
+a vytvoří lejblík v dané úrovni zanoření na
+základě předpočítaného údaje "<potomci>", který obsahuje počet potomků právě
+vkládané záložky. Údaj "<minus>" je (po expanzi)
+prázdný, pokud nechceme mít potomky skryté a obsahuje znak minus, pokud
+chceme mít potomky ve výchozím stavu skryté.
+Připomínám, že v makru \db outlinelevel
+máme makrem "\outlines" připravenu úroveň rozevření, kterou si uživatel
+přeje. Makro "\outlinesC" je připraveno k
+předefinování v modulu "opmac-xetex.tex", který pro vytvoření záložek
+používá "\special" a nepotřebuje znát údaj "<potomci>". Příslušný "\special"
+využije přímo údaj "<úroveň>".
+
+\inext{outlinesC}{}{+-}
+
+Makro \db setcnvcodesA zkontroluje, zda je uživatelem definováno makro
+"\toasciidata<iso-kód>". Pokud je, použije ho jako "\toasciidata" ke
+konverzi akcentovaných znaků na neakcentované. Jinak
+podle definovanosti "\r" zkontroluje, zda je zapnutý
+"\csaccents" a pokud je, expanduje interní "\toasciidata".
Makro \db toasciidata potřebujeme expandovat, protože
neobsahuje přímý zápis znaků. Důvod je zřejmý, nechceme, aby se
soubor {\tt opmac.tex} stal závislý na použitém kódování.
@@ -1852,6 +1945,10 @@ pomocí "\futurelet") a \db testparC (ošetří, zda tento následující znak je
\inext{testparA}{\empty}{+-}
+Makro \db printttline vytiskne číslo řádku.
+
+\inext{printttline}{\empty}{+-}
+
Makro \db activettchar pracuje podobně, jako makro "\adef". Navíc
potřebuje použít nově načtený znak ve své aktivní kategorii jako separátor
vymezující konec parametru. Do sekvencí \db savedttchar a \db savedttcharc
@@ -1917,11 +2014,10 @@ se ověří, zda následuje prázdný řádek.
V prvním cyklu "\loop" v těle makra "\doverbinput" se opakovaně volá
\db vireadline, což je makro, které přečte další řádek ze souboru. V druhém
cyklu se opakovaně volá "\vireadline" následované \db viprintline. Toto
-makro vytiskne přečtený řádek do dokumentu. Před řádkem může být v "\llap"
-vytištěno číslo řádku. Záleží na hodnotě "\ttline". Je to naprogramováno v
-souladu s uživatelskou dokumentací.
+makro vloží přečtený řádek do "\tmpb". Nakonec se "\tmpb" vytiskne stejným
+způsobem, jako při přečtení textu makrem "\begtt".
-\inext{vireadline}{\empty}{++}
+\inext{vireadline}{\empty}{+-}
\subsec Jednoduchá tabulka
@@ -2064,6 +2160,9 @@ Není-li aktivován PDF výstup, napíšeme jen varování a neprovedeme nic.
\inext{ifpdftex}{\empty}{+-}
+Makro \db inspicpage může při natažení PDF obsahovat text "page<number>".
+Pak se jako obrázek použije odpovídající strana PDF dokumentu.
+
\subsec PDF transformace
%%%%%%%%%%%%%%%%%%%%%%%%
@@ -2535,7 +2634,9 @@ která je obklopeno makry "\begoutput" a "\endoutput". Makro \db begoutput
zapíše do REF souboru údaj o čísle strany a předefinuje makra, která se
mohou vyskytnout v záhlaví či zápatí stránky, pokud od nich chceme, aby
se chovaly jinak než obvykle. Makro \db endoutput je prázdné a je určeno
-pro strýčka Příhodu.
+pro strýčka Příhodu. Makro \db prephoffset je rovněž implictně prázdné,
+spouští se v "\begoutput" a může v něm být nastaveno střídání
+okrajů pro liché a sudé stránky, viz též makro "\margins".
\inext{opmacoutput}{\empty}{+-}