How To Make Lazarus Docs

From Lazarus wiki
Revision as of 08:51, 18 January 2010 by Skalogryz (talk | contribs)
Jump to navigationJump to search

Deutsch (de) English (en) slovenčina (sk)

Making Documentation Files for Lazarus

Documentation files, which will eventually be incorporated into the on-line Help system, can be generated from the Unit files in the Lazarus Component Library (lcl). The FpDoc utility can generate HTML files using the Pascal source files (*.pp or *.pas) as input. A great deal more useful information can be incorporated if an XML description file can be used in conjunction with the source file.

While it is perfectly possible to generate the XML tags by hand, using the instructions in the FpDoc manual, it is much easier to use the utility makeskel which is provided as part of the FpDoc suite. This utility generates an XML file with a set of empty tags for every identifier, type, procedure and function in the source file. The user can then edit this XML file, either with a simple text editor or using an XML editor like KXMLEditor. There is a huge number of entries in these files: I suggest that only the tags describing Objects be edited, at least initially (use the Search facility to find 'object', and then enter short titles and descriptions for the components).

When you have finished editing the XML file, save it and then run

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

The resultant HTML files will be placed in a subdirectory called 'thisunit'.

There will be a huge number of HTML files (typically about 160) - these will eventually all be used for Help files, but there is too much information, for example, to put on this WiKi site. It is helpful to filter the files, only including those that describe Components. This can be done with

grep -l Inheritance * > outputfile

as only Components have a description of their Inheritance. The outputfile can then be used to drive a utility to convert HTML to text. One such application is html2text. The process has been partly automated in the following Pascal program (which is excessively simple, not particularly robust, but works!):

program convhtml;
{ CT Kirkpatrick, MD 20040720 }
{$mode objfpc}{$H+}
{ reads a list of filenames from listfile, and converts them in
turn from HTML to plain text, writing the output of all the files to outfile }
uses Classes, unix;
var listfile, outfile: text; pathname, listfname, outfname, fname: string; execstring, comstring: string; begin Writeln ('Enter path for files to convert'); Readln (pathname); Writeln ('Enter name of file to contain list of files for conversion'); Readln (listfname); shell ('grep -l Inheritance ' + pathname + '* > ' + pathname + 'filelist.txt'); Writeln ('Enter name of output file'); 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.

Original contributors and changes

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