\chyph

\hsize=11cm \vsize=16cm
\parindent=1.5em

\emergencystretch=2em

\widowpenalty=10000
\clubpenalty=10000

\raggedbottom

\font\bbf=csbx12
\font\smalltt=cstt8
\font\smallrm=csr8

\hyphenation{docby}

\newcount\secnum

\def\sec #1\par {\removelastskip\bigskip
\advance\secnum by1\noindent\hbox to\parindent{\bbf\hss\the\secnum.\hss}%
   {\bbf #1}\par\nobreak\medskip}

\def\title #1\par {\centerline{\bbf #1}\medskip}
\def\author #1\par {\centerline{\it #1}\medskip}

\def\abstract #1\par{\bgroup \smallrm \baselineskip=10pt 
   \leftskip=\parindent \rightskip=\parindent
   \noindent #1\par \egroup}

\def\url#1{{\tt#1}}

%% \begtt, \endtt

\def\begtt{\medskip\bgroup
   \nobreak\setverb \parskip=0pt %\parindent=0pt
   \def\par{\endgraf\penalty200\leavevmode}
   \baselineskip=10pt
   \obeylines \obeyspaces
   \startverb}
{\catcode`\|=0 \catcode`\\=12
  |gdef|startverb#1\endtt{%
        |smalltt#1|nobreak|egroup|penalty0|vskip-3pt|relax|scannexttoken}}
\long\def\scannexttoken#1{\ifx#1\par\else\noindent#1\fi}
\def\setverb{\def\do##1{\catcode`##1=12}\dospecials}

\def\begitems{\medskip}
\def\enditems{\par\medskip}
\def\item{\par\noindent\hbox to\parindent{\hss$\bullet$\hss}%
  \hangindent=\parindent \hangafter=1\relax}

\let\cmd=\uv

\title DocBy.\TeX{} -- dokumentov�n� zdrojov�ch text� \TeX{}em

\author Petr Ol��k

\abstract 
DocBy.\TeX{} je makro \TeX{}u, kter� umo�n� jednodu�e
dokumentovat zdrojov� texty v programovac�ch jazyc�ch, nap��klad v
jazyku~C. Obsahuje mo�nost vkl�d�n� vymezen�ch �sek� zdrojov�ch text�
a d�ky enc\TeX{}u um� automaticky zv�raznit dokumentovan� slova 
v~t�chto textech a ud�lat z nich aktivn� odkazy. Automaticky vytv���
obsah a rejst��k. K vytvo�en� c�lov� dokumentace v PDF form�tu je
pot�eba pouze pdf\TeX{} dopln�n� enc\TeX{}em. Nen� nutn� pou��t ��dn�
preprocesory.

\sec �vod, motivace, zad�n�

M�j syn Mirek p��e ro�n�kovou pr�ci z programov�n� a je z�ejm�, �e
pokud to bude cht�t odevzdat, m�l by sv� zdrojov� k�dy n�jak
dokumentovat. Nab�dl jsem se mu, �e mu pro tyto ��ely nap��u \TeX{}ov�
ud�l�tko. Sna�il jsem se splnit n�sleduj�c� c�le

\begitems
\item Form�t dokumentace je klikac� PDF. Dokumentaci ve form�tu html
  negenerujeme. 
\item V�c by m�la b�t co nejjednodu���, tj. pokud mo�no jen
  pou�it� \TeX{}u. P��padn� preprocesory by pr�ci zbyte�n�
  komplikovaly.
\item K napsan�mu zdrojov�mu k�du se m��e ps�t dokumentace zvlṻ
  do \uv{vedlej��ho} \TeX{}ov�ho souboru, v n�m� budou p��kazy na
  vkl�d�n� vymezen�ch �sek� zdrojov�ho k�du podle pot�eby. K�d bude
  tedy vlo�en v dob� zpracov�n� dokumentace \TeX{}em aktu�ln�. 
  Tj. p�esn� ten, kter� na��t� kompil�tor p�i p�ekladu programu.
\item Zdrojov� k�d je �len�n do modul�. Kompil�tor je p�ekl�d� do objekt�
  {\tt *.o} a ty pak sestavuje do v�sledn�ho programu. Jeden modul z
  pohledu program�tora �e�� jeden ucelen� probl�m a stoj� za to jej
  dokumentovat jako \uv{samostatnou jednotku}. \TeX{}ov� soubory 
  s dokumentac� tedy respektuj� strukturu �len�n� na moduly.
\item Pomoc� enc\TeX{}u je mo�n� za��dit, �e libovoln� v�skyt
  dokumentovan�ho slova v za�len�n�m zdrojov�m k�du se stane
  automaticky aktivn�m odkazem na m�sto, kde je slovo
  dokumentov�no. Dokumentovan�m slovem m��e b�t funkce, struktura,
  prom�nn� nebo cokoli jin�ho.
\item DocBy.\TeX{} s�m vytvo�� pod �arou na str�nce, kde je slovo
  dokumentov�no, seznam v�ech str�nek, kde se slovo vyskytuje nap���
  celou dokumentac�. Podobn� seznamy str�nek vznikaj� v rejst��ku.
\item Rejst��k vznik� ze v�ech dokumentovan�ch slov zcela automaticky
  uvnit� \TeX{}u. Tj. bylo pot�eba implementovat makrojazykem \TeX{}u
  abecedn� t��d�n�.
\item �len�n� na sekce a podsekce a automatick� vytvo�en� obsahu,
  kter� je klikac�, je samoz�ejmost�.
\item V�c funguje v csplainu, proto�e j� i syn pou��v�me tento form�t.
\enditems

P�izn�m se bez mu�en�, �e mo�nosti sou�asn�ch n�stroj� na
dokumentov�n� zdrojov�ch k�d� jsem moc nestudoval. Je tedy mo�n�, �e 
v~n�kter�ch aspektech znovu vynal�z�m kolo a �e n�kter� vlastnosti,
kter� se b�n� p�i dokumentov�n� pou��vaj�, chyb�. Je to
takov� \uv{rodinn�} zak�zka na m�ru programu, kter� syn odevzd�v� jako
ro�n�kovou pr�ci. Nicm�n� jsem se sna�il n�stroj ud�lat aspo� trochu
obecn� pou�iteln� a dovol�m si jej na konferenci \TeX{}perience 2008
p�edv�st. Poslucha�i sami posoud�, zda jim to m��e b�t k n��emu
dobr�. Obecnou pou�itelnost deklaruji nap��klad t�m, �e dokumentaci k
DocBy.\TeX{}u (v�etn� technick� dokumentace s~rozborem v�ech maker)
p��u v DocBy.\TeX{}u.

Zva�oval jsem aspo� na vte�inu doporu�it synovi liter�rn�
programov�n�, jak jej vytvo�il Donald Knuth (tzv. WEB). Ov�em, velmi rychle
jsem od toho upustil. Domn�v�m se, �e doba, kdy Knuth vytv��el sv�
d�lo, byla poznamen�na pon�kud jin�mi po��ta�i, ne� jak� m�me p�ed
sebou dnes. Dnes je b�n� grafick� rozhran�, ve kter�m je mo�n�
sou�asn� otev��t v�ce editor� vedle sebe v r�zn�ch oknech s r�zn�mi
texty.  V jednom t�eba m��e b�t text ur�en� pro po��ta� a v druh�m
text, kter� je ur�en pro �lov�ka. V�e je vid�t nar�z, jak m��e vid�t i
�ten�� tohoto �l�nku na obr�zku~1. Nen� tedy nutn� tyto informace
slu�ovat do jedin�ho souboru, aby byly bl�zko sebe, a pot� je
preprocesory (tangle, weave) zase odd�lovat. Dne�n� program�to�i tak�
obvykle p�em��lej� v~intenc�ch, jak k�d zpracov�v� kompil�tor. Trh�n�
tohoto k�du na �seky (jako v Knuthov� WEBu) asi moc nemiluj�.

Poznamen�v�m je�t�, �e jsem Knuth�v WEB nezavrhl z neznalosti. S�m jej
velmi dob�e zn�m. Vrtal jsem se pom�rn� do hloubky ve zdrojov�ch
k�dech \TeX{}u a tak� jsem napsal jednoduchou�k� program vlna v CWEBu.
Syn�v program je ov�em asi stokr�t slo�it�j�� ne� program vlna,
tak�e rozhodov�n� o CWEBu ani moc dlouho netrvalo. CWEB jsme nepou�ili.

Proto�e syn bude odevzd�vat svou ro�n�kovou pr�ci a� v lednu roku
2009, ne�ekejte nyn� hotov� d�lo. Jeho program je ve st�diu zrodu a
DocBy.\TeX{} se tak� zat�m vyv�j� podle po�adavk� program�tora. 
V~dob�, kdy se sna��m aspo� ��ste�n� dodr�et term�n odevzd�n� tohoto
p��sp�vku (srpen 2008) tedy nen� DocBy.\TeX{} ve st�diu, kdy bych jej
mohl zve�ejnit na internetu. Ani uk�zek zat�m moc nen�. Syn m�
naprogramov�no v tuto chv�li asi 20 modul� sv�ho programu a bude
p�id�vat je�t� mnoho dal��ch. Dokumentov�ny DocBy.\TeX{}em m� moduly
dva. Na obr�zc�ch 2, 3 m��ete posoudit, jak vypad� sou�asn� verze
dokumentace jeho programu. Na obr�zku 4 pak vid�te str�nku z dokumentace
samotn�ho DocBy.\TeX{}u.

A� DocBy\TeX{} dosp�je do n�jak� rozumn� stabiln� verze, najdete jej
na internetu na \url{http://www.olsak.net/docbytex.html}.

\sec P��klad pou�it� DocBy.\TeX{}u

P�edpokl�d� se, �e program je �len�n na moduly. Ka�d� modul obsahuje
skupinu funkc�, kter� �e�� jeden ucelen� probl�m. P�edpokl�dejme
teoretick� program {\tt lup}, kter� m� t�i moduly: main v souboru 
{\tt main.c}, win v souborech {\tt win.c} a {\tt win.h} a kone�n�
modul base v souborech {\tt base.h} a {\tt base c}. Dokumentace k
takov�mu programu vznikne tak, �e autor nap��e hlavn� \TeX{}ov� soubor
(nap��klad {\tt lup.tex}) a z n�j bude ��st dal�� \TeX{}ov� soubory,
kter� obsahuj� dokumentaci k jednotliv�m modul�m: {\tt main.d},
{\tt win.d} a {\tt base.d}. V {\tt lup.tex} m��e b�t n�jak� rozvern�
�vod a d�le p��kazem \cmd{\tt\char`\\module} jsou na��t�ny jednotliv�
dokumenta�n� soubory k modul�m. V t�chto souborech se autor dokumentace
soust�ed� na probl�m �e�en� v dan�m modulu (n�co jako sekce v Knuthov�
WEBu) a postupn� vkl�d� do dokumentace vymezen� �seky k�du ze soubor�
{\tt *.c} a {\tt *.h} pomoc� p��kazu \cmd{\tt\char`\\ins}. Dokumentovan�
slova vymezuje p��kazem \cmd{\tt\char`\\dg} (dokumentace glob�ln�ho slova). 
Vztah mezi jednotliv�mi soubory p�i na��t�n� kompil�torem a p�i
na��t�n� \TeX{}em je nazna�en na obr�zku~5.

Obsah souboru {\tt lup.tex} m��e vypadat t�eba takto:

\begtt
\input docby.tex

\title   Program lup -- dokumentace ke zdrojov�m text�m

\author  Progr a M�tor

\dotoc  % tady bude obsah

\sec �len�n� zdrojov�ch text�

Zdrojov� texty programu "lup" jsou rozd�leny do t�� modul�. 
V "base.c" jsou definov�ny pomocn� funkce a v "base.h" jsou 
jejich prototypy. Podobn� ve "win.c" jsou funkce pro okenn� 
z�le�itosti a "win.h" obsahuje jejich prototypy. Kone�n� 
"main.c" obsahuje hlavn� funkci programu.

\module base
\module win
\module main
\doindex  % v tomto m�st� bude sestaven rejst��k
\end
\endtt

V tomto p��klad� jsme se rozhodli �ten��e dokumentace seznamovat s
programem \uv{zdola nahoru}, tedy od element�rn�ch funkc� a� k hotov�mu
programu. N�kdo mo�n� preferuje cestu \uv{shora dol�} a m��e m�t v
dokumentaci na konci souboru {\tt lup.tex} t�eba naps�no:

\begtt
\module main
\module win
\module base
\doindex
\end
\endtt

Oba p��stupy jsou mo�n�, proto�e dokumentace je automaticky prov�z�na
hyperlinky. �ten�� se kdykoli m��e pod�vat na dokumentaci t� funkce,
jej�� pou�it� zrovna �te, a obr�cen� m��e proj�t v�skyty ve�ker�ho
pou�it� funkce, kdy� �te jej� dokumentaci.

Pod�vejme se nyn� podrobn�ji nap��klad do souboru {\tt base.d}, kde je
soust�ed�na dokumentace modulu base. ��st tohoto souboru m��e vypadat
t�eba takto:

\begtt
Struktura \dg dvojice se pou��v� jako n�vratov� hodnota funkce
"uzasna_funkce" a sdru�uje dv� hodnoty typu "float".
\ins c dvojice

Funkce \dg [struct dvojice]uzasna_funkce() si vezme jeden parametr 
"p" a vr�t� ve struktu�e "dvojice" dvojn�sobek a trojn�sobek 
tohoto parametru. 
\ins c uzasna_funkce
\endtt

P��kazem \cmd{\tt\char`\\ins c dvojice} jsme dali najevo, �e pot�ebujeme
ze souboru se stejn�m jm�nem jako je aktu�ln� n�zev modulu (tj. base)
a s~p��ponou {\tt.c} p�e��st ��st k�du, kter� obsahuje deklaraci zm�n�n�
struktury. Pro vymezen� ��st� z na��tan�ho souboru je pot�eba do
zdrojov�ho k�du vlo�it vymezuj�c� pozn�mky tvaru
{\tt//:~slovo}. P��klad ��sti k�du ze souboru {\tt base.c} v�e
osv�tl�:

\begtt
#include <stdio.h>

//: dvojice

struct dvojice {
  float x, y;
};

//: uzasna_funkce

struct dvojice uzasna_funkce (float p)
{
  struct dvojice navrat;
  navrat.x = 2*p; // tady nasobim p dvema
  navrat.y = 3*p; // tady nasobim p tremi
  return navrat;
} 
\endtt

P��kaz \cmd{\tt\char`\\ins c slovo} tedy na�te ��st k�du od vymezuj�c�
pozn�mky tvaru {\tt//:~slovo} po v�skyt pozn�mky tvaru {\tt//:} nebo a�
po konec souboru. Do zdrojov�ho k�du je tedy pot�eba vlo�it vymezuj�c�
pozn�mky. 

Na po�ad� �sek�, kter� zahrnujeme ze zdrojov�ho textu do dokumentace,
nez�le��. Klidn� jsme mohli dokumentaci za��t od pov�d�n� o~��asn�
funkci (v�etn� vlo�en� jej�ho k�du) a potom je�t� dopsat, co to je ta 
struktura {\tt dvojice} a n�sledn� vlo�it deklaraci t�to struktury.

Na obr�zku~6 je vid�t zhruba v�sledek zpracov�n� na�eho p��kladu
DocBy.\TeX{}em (prvn� str�nka). N��e sice p��u \uv{v�imn�te
si}, \uv{za pov�imnut� stoj�} atd., ov�em je to pot�eba br�t s rezervou. Je
mo�n�, �e tisk obr�zku~6 bude jen �ernob�l� a pravd�podobn� dost
zmen�en�. Omlouv�m se tedy preventivn� �ten��i, pokud ho nut�m, aby si
v�iml, �e n�co zmodralo nebo zezelenalo, kdy� asi obr�zek~6 mu tuto
informaci jednozna�n� neposkytne.

V�imn�me si, �e \TeX{} zapsal ��sla ��dk� p�esn� podle toho, jak jsou
ve zdrojov�m k�du. Tj. po��tal i p�eskakovan� ��dek
{\tt\#include~<stdio.h>} i p�eskakovan� pr�zdn� a vymezuj�c� ��dky.
Koment��ov� ��dek s~vymezen�m {\tt//:~slovo} nen� do dokumentace zahrnut a pokud
n�sleduje za ��dkem s~vymezen�m pr�zdn� ��dek, ani ten nen� do
dokumentace zahrnut. 

Za pov�imnut� stoj� pou�it� p��kazu \cmd{\tt\char`\\dg}. Za
n�m n�sleduje slovo (separovan� mezerou), kter� dokumentujeme. Toto
slovo se v dokumentaci v�razn� ozna�� (v PDF verzi �ervenou barvou
nav�c v barevn�m r�me�ku) a jak�koli jin� v�skyt takov�ho slova ve
zdrojov�m textu nebo mezi uvozovkami {\tt\char`\"...\char`\"} bude
automaticky ozna�en modrou barvou a bude klikac�. Kliknut� na modr�
v�skyt slova kdekoli v dokumentaci vr�t� �ten��e na �erven� v�skyt,
kde je slovo dokumentov�no.

V�echny C��kov� koment��e ve vlo�en�m zdrojov�m k�du automaticky zezelenaly.

Palcov� uvozovky {\tt\char`\"...\char`\"} vymezuj� kusy k�du
uvnit� odstavce. Text takto uvozen� je ps�n strojopisem a pokud se 
v n�m vyskytuj� dokumentovan� slova, tato slova automaticky modraj�.
Text mezi t�mito uvozovkami je nav�c p�episov�n ve \uv{verbatim}
m�du \TeX{}u, tj. ��dn� znaky nemaj� speci�ln� vlastnosti (s v�jimkou
koncov� palcov� uvozovky).

Na str�nce, kde je slovo dokumentov�no (pomoc� \cmd{\tt\char`\\dg}), je
v pozn�mk�ch pod �arou slovo znovu zm�n�no a vedle t�to zm�nky je
seznam v�ech str�nek, na kter�ch se kdekoli v textu vyskytuje pou�it�
tohoto slova.  D�le jsou v�echna dokumentovan� slova zahrnuta do
z�v�re�n�ho abecedn�ho rejst��ku, kter� odkazuje jednak na str�nku,
kde je slovo dokumentov�no, i na str�nky se v�emi v�skyty slova.

Pozorn� �ten�� si jist� v�iml, �e v pozn�mce pod �arou a v rejst��ku
je {\tt uzasna\_funkce} zm�n�na v�etn� jej�ho n�vratov�ho typu a nav�c je
slovo ukon�eno dvojic� z�vorek {\tt()} a t�m je nazna�eno, �e se jedn�
o~funkci. Je to d�ky z�pisu
\cmd{\tt\char`\\dg~[struct~dvojice]uzasna\_funkce()} v~m�st� dokumentace
funkce. Nepovinn� parametr s n�vratovou hodnotou funkce se p�ep��e
p�ed jm�no funkce pod ��ru i do rejst��ku, ale rejst��k p�i abecedn�m
�azen� tento parametr ignoruje.

\sec Dal�� mo�nosti

DocBy.\TeX{} umo��uje vyzna�it vkl�dan� �seky k�du dal��mi zp�soby: je
mo�n� kontrolovat, zda se vlo�� nebo nevlo�� vymezuj�c� ��dky, nebo
jen vymezuj�c� ��dek na jedn� stran�, je mo�n� navazovat vkl�d�n�m od
m�sta, kde vkl�d�n� naposledy skon�ilo, je mo�n� vlo�it prototyp
funkce, je mo�n� vkl�dat od libovoln� vymezen�ho m�sta ve zdrojov�m
k�du do dal��ho vymezen�ho m�sta (nen� tedy nutn� vymezovat text jen
v��e uveden�mi pozn�mkami), je mo�n� vlo�it jedin� ��dek s prvn�m
v�skytem slova nebo s dal��m v�skytem slova od m�sta posledn�ho
vlo�en�.

Je mo�n� nastavit jin� vzory, podle kter�ch zelenaj� ve vlo�en�ch
souborech koment��e. Implicitn� DocBy.\TeX{} pova�uje za koment�� �sek
od {\tt//} do konce ��dku a �sek mezi {\tt/*...*/}.

V DocBy.\TeX{}u m��e autor dokumentace zalo�it sekce a subsekce,
p�itom implicitn� p��kaz \cmd{\tt\char`\\module} zalo�� novou sekci.
Je mo�n� odkazovat pomoc� lejbl�k� na sekce, subsekce.
Je mo�n� vkl�dat obr�zky a odkazovat na n�. 

DocBy\TeX{} implementuje jmenn� prostory, tak�e je mo�n� dokumentovat
slovo lok�ln� v r�mci �seku dokumentace, kter� vymezuje ur�it� jmenn�
prostor. Nastaven� jmenn�ch prostor� je pom�rn� flexibiln� a umo��uje
na lok�ln� dokumentovan� slovo odkazovat glob�ln� p�i dlouh�m v�pisu
slova v�etn� specifikace jmenn�ho prostoru.

DocBy.\TeX{} rozli�uje mezi PDF a DVI m�dem, d�le mezi enc a non-enc
m�dem a kone�n� mezi csplain a plain m�dem.

Pro zpracov�n� dokumentace je ide�ln� pou��t pdf\TeX{} s aktivovan�m
v�stupem do PDF (tj. PDF m�d) a s enc\TeX{}em (tj. enc m�d)  
a s form�tem csplain nebo plain (tj. csplain nebo plain m�d).
V~takov�m p��pad� funguj� barvy, odkazy i automatick� tvo�en�
aktivn�ch odkaz� ve vkl�dan�m zdrojov�m textu.

Nen�-li aktivov�n PDF v�stup, DocBy.\TeX{} o tom nap��e varov�n� na
termin�l a p�ejde do DVI m�du. V tomto m�du nefunguj� barvy a odkazy
nejsou klikac�.

Nen�-li aktivov�n enc\TeX{}, DocBy.\TeX{} p�ejde do non-enc m�du a
nap��e o tom varov�n� na termin�l. V takov�m p��pad� dokumentovan�
slova ve vkl�dan�m zdrojov�m textu automaticky nemodraj� a nest�vaj�
se klikateln�mi odkazy. Ani se jejich v�skyty neuv�d�j� na spr�vn�ch
str�nk�ch v rejst��ku a v pozn�mk�ch pod �arou. Takt� koment��e
automaticky nezelenaj�.

P�i csplain m�du generuje DocBy.\TeX{} n�kter� n�zvy �esky. Jedn� se
o n�zev kapitoly s obsahem, rejst��kem a modulem. V plain m�du jsou
tyto n�zvy anglicky. Pracujete-li s jin�m jazykem, m��ete p�edefinovat
odpov�daj�c� makra.

Generov�n� rejst��ku i obsahu prob�h� v DocBy.\TeX{}u zcela
automaticky. Pro vytvo�en� rejst��ku nen� nutn� pou��vat extern�
program (DocBy.\TeX{} si slova abecedn� zat��d� s�m).  Sta�� tedy
vlo�it na po�adovan� m�sta p��kazy \cmd{\tt\char`\\dotoc} a
\cmd{\tt\char`\\doindex}. Rejst��k ani obsah nejsou spr�vn� vygenerov�ny po
prvn�m pr�chodu \TeX{}u. Je pot�eba \TeX{}ovat dvakr�t nebo t�ikr�t.
Pro generov�n� obsahu i rejst��ku si DocBy.\TeX{}
zakl�d� pomocn� soubor s p��ponou {\tt.ref}, v na�em p��klad� tedy
{\tt lup.ref}.

\bigskip

\abstract
DocBy.\TeX{} is a \TeX{} macro which gives you possibility to
simply document your source codes written in various programming
languages, for instance written in C. You can include parts of your
source code into your documentation. All occurrences of documented
words in your included source code are automatically made as active
links if enc\TeX{} and pdf\TeX{} is in progress. To make PDF output,
you needn't no more than pdf\TeX{} with enc\TeX.  The table of
contents and the index are created automatically too.  The sorting of
words in the index is implemented at \TeX{} macro level.

\end

\pic [plocha] {Obr�zek 1. Pracovn� plocha s v�ce editory}

\pic [mireka] {Obr�zek 2. Uk�zka z Mirkovy dokumentace, modul hash}

\pic [mirekb] {Obr�zek 3. Uk�zka z Mirkovy dokumentace, rejst��k}

\pic [docdoc] {Obr�zek 4. �vodn� strana dokumentace k DocBy.\TeX{}u}

\pic [vztahy] {Obr�zek 5. Vztahy mezi zdrojov�mi soubory}

\pic [lupkuk] {Obr�zek 6. Uk�zka uk�zkov�ho v�stupu}
