How To Make Lazarus Docs: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: How To Make Lazarus Docs

New		Line
1	+	## Making Documentation Files for Lazarus
2	+
3	+	### Overview and XML description files
4	+
5	+	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 (and other, such as CHM) 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. This description file contains the actual help text, while the source code provides the function names etc.
6	+
7	+	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 <u>makeskel</u> 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.
8	+
9	+	The user can then edit this XML file, either with
10	+
11	+	- a simple text editor
12	+	- an XML editor like KXMLEditor
13	+	- the specialized [[FPDoc Editor\|FPDoc editor]] which is included with Lazarus. This tool can be used to quickly edit entries when writing code.
14	+	- the specialized [[Lazarus Documentation Editor]] which is included with Lazarus (you'll need to compile it and use it as an external tool). This is the most extensive tool and is quite user-friendly.
15	+
16	+	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).
17	+
18	+	### Creating output
19	+
20	+	Having an XML description file is fine, but you probably want some more readable output. You can generate e.g. html, chm and other output (note: not all platforms support all outputs).
21	+
22	+	#### Creating output with lazde
23	+
24	+	The [[Lazarus Documentation Editor]] (LazDE) tool has a dialog (Menu Extra, Build) that lets you build help files as well. This tool offers GUI controls for the various files so it might be the easiest for beginners or casual users. This tool calls fpdoc to process the files.
25	+
26	+	#### Creating output with build_lcl_docs
27	+
28	+	The Lazarus tool build_lcl_docs in \$(lazarusdir)\docs\html allows you to combine many description files and source file and generate all kinds of output. Internally it uses fpdoc like the previous tool.
29	+
30	+	#### Creating output with fpdoc
31	+
32	+	Finally, you can also call fpdoc directly.
33	+
34	+	When you have finished editing the XML file, save it and then run
35	+
36	+	``` bash
37	+	fpdoc --package=lcl --input=thisunit.pp --descr=thisunit.xml
38	+	```
39	+
40	+	The "lcl" indicates you're editing LCL help; if you're editing FPC help, it would probably be "fcl" (these names are determined by the developers in charge of documentation and are not apparent from other sources). The resultant HTML files will be placed in a subdirectory called 'thisunit'.
41	+
42	+	(As mentioned, you can also output in other formats, but those are not discussed here)
43	+
44	+	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.
45	+
46	+	This can be done with:
47	+
48	+	``` bash
49	+	grep -l Inheritance * > outputfile
50	+	```
51	+
52	+	as only components have a description of their inheritance.
53	+
54	+	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):
55	+
56	+	``` pascal
57	+	program convhtml;
58	+	{ CT Kirkpatrick, MD 20040720 }
59	+	{$mode objfpc}{$H+}
60	+	{ reads a list of filenames from listfile, and converts them in
61	+	turn from HTML to plain text, writing the output of all the files to outfile }
62	+	uses
63	+	Classes, unix;
64	+	var
65	+	listfile, outfile: text;
66	+	pathname, listfname, outfname, fname: string;
67	+	execstring, comstring: string;
68	+	begin
69	+	Writeln ('Enter path for files to convert');
70	+	Readln (pathname);
71	+	Writeln ('Enter name of file to contain list of files for conversion');
72	+	Readln (listfname);
73	+	shell ('grep -l Inheritance ' + pathname + '* > ' + pathname + 'filelist.txt');
74	+	Writeln ('Enter name of output file');
75	+	Readln (outfname);
76	+	Assign (listfile, pathname +'filelist.txt');
77	+	Assign (outfile, pathname + outfname);
78	+	Reset (listfile);
79	+	Rewrite (outfile);
80	+	while not eof (listfile) do
81	+	begin
82	+	readln (listfile, fname); //writeln (fname);
83	+	//if fname = '' then begin readln (listfile, fname); writeln (fname) end;
84	+	execstring := '/usr/bin/html2text ';
85	+	comstring := '-nobs ' + fname
86	+	+ ' >> ' + pathname + outfname;
87	+	writeln ('Executing ', execstring, comstring);
88	+	shell (execstring + comstring);
89	+	end;
90	+	end.
91	+	```
92	+
93	+	---
94	+	From the Free Pascal wiki, page "How To Make Lazarus Docs", 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](/wiki-contact).

Back to history