How To Make Lazarus Docs/sk

Tvorba dokumentácie pre Lazarus

Súbory dokumentácie, ktoré budú eventuálne zahrnuté do systému on-line nápovedy, môžete vygenerovať zo súborov jednotiek Lazarus Component Library (lcl). Utilita FpDoc generuje HTML súbory použitím zdrojových súborov Pascal (*.pp or *.pas) ako vstupu. Veľká časť veľmi dôležitých informácií môže byť zahrnutá, ak použijete popisný súbor XML v spojitosti so zdrojovým súborom.

Kým je výborne možné generovať XML tagy ručne, použitím inštrukcií v manuále FpDoc, oveľa jednoduchšie je použiť utilitu makeskel, ktorá je poskytnutá ako súčasť FpDoc. Táto utilita generuje súbor XML s množinou prázdnych tagov pre každý identifikátor, typ, procedúru a funkciu v zdrojovom kóde.

Použitie nástroja makeskel úplne priamočiare: musíte zadať meno (jedného alebo viacerých) vstupného súboru (ako pri FPDOC), meno výstupného súboru a meno balíčka:

makeskel --package=rtl --input=crt.pp --output=crt.xml

Týmto príkazom makeskel prečíta súbor crt.pp a vytvorí súbor crt.xml, ktorý obsahuje prázdne uzly pre všetky identifikátory nájdené v crt.pp, všetko v balíčku zvanom rtl. Iný príklad:

makeskel --input='-Sn system.pp' --input=crt.pp --output=rtl.xml

Ako vidno na príklade, voľba input môže obsahovať aj niektoré voľby prekladača, ako vprípade FPDOC. Uvedený príkaz spracuje súbory system.pp a crt.pp, a vytvorí značky prvkov, pre identifikátory oboch unít, v súbore rtl.xml.

Používateľ môže editovať tento XML súbor, buď pomocou jednoduchého textového editora alebo pomocou editora XML ako KXMLEditor. V týchro súboroch môže existovať obrovský počet údajov.

Pripomínam, že upravované sú len značky popisujúce Objekty, aspoň zo začiatku (použite Search na nájdenie objektu a potom zadajte krátke titulky a popisy komponentov).

Keď dokončíte úpravy XML súboru, uložte ho a spusťte

 fpdoc --package=lcl --input=thisunit.pp --descr=thisunit.xml

Výsledné HTML súbory budú umiestnené v podadresári nazvanom 'thisunit'.

Bude tam veľký počet HTML súborov (zvyčajne okolo 160) - tieto budú eventuálne všetky použité pre Help súbory, ale je tam veľmi veľa informácií, napr. pre umiestnenie na tejto Wiki stránke. Je užitočné tieto súbory prefiltrovať a zahrnúť len tie, ktoré popisujú komponenty. To môžete urobiť pomocou

 grep -l Inheritance * > outputfile

keďže len komponenty majú popis ich dedičnosti (Inheritance).

Výstupný súbor môže byť použitý na ovládanie utilizy pre konverziu z HTML na text, napríklad aplikáciou html2text. Tento proces môže byť čiastočne automatizovaný v nasledujúcom Pascal programe (ktorý je prehnane jednoduchý, nie veľmi robustný, ale pracuje!):

 program convhtml;
 { CT Kirkpatrick, MD 20040720 }
 {$mode objfpc}{$H+}
 { číta zoznam mien súborov z listfile a konvertuej ich z HTML na text,
   zapísaním výstupu všetkých súborov do výstupného súboru }<br>
 uses
   Classes, unix;<br>
 var
   listfile, outfile: text;
   pathname, listfname, outfname, fname: string;
   execstring, comstring: string;
 begin
   Writeln ('Zadajte cestu k súborom na konverziu');
   Readln (pathname);
   Writeln ('Zadajte meno súboru obsahujúceho zoznam súborov pre konverziu');
   Readln (listfname);
   shell ('grep -l Inheritance ' + pathname + '* > ' + pathname + 'filelist.txt');
   Writeln ('Zadajte meno výstupného súboru');
   Readln (outfname);
   Assign (listfile, pathname +'filelist.txt');
   Assign (outfile, pathname + outfname);
   Reset (listfile);
   Rewrite (outfile);
   while not eof (listfile) do
   begin
     readln (listfile, fname); //writeln (fname);
     //if fname = '' then begin readln (listfile, fname); writeln (fname) end;
     execstring := '/usr/bin/html2text ';
     comstring := '-nobs ' + fname
               + ' >> ' + pathname + outfname;
     writeln ('Executing ', execstring, comstring);
     shell (execstring + comstring);
   end;
 end.

Pôvodní spolupracovníci a zmeny

This page has been imported from the epikwiki version. Original by User:Kirkpatc.

• preložené z originálu - Slavko 14:50, 11 Apr 2005 (PDT)

From the Free Pascal wiki, page "How To Make Lazarus Docs/sk", as it stood on 2020-02-17 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.