Documentation, I'm here to help

[dbannon]

Folks, I'd like to contribute to the documentation. I'm  long time ago Delphi user and remember the readily available docs with good example code snippets was a real feature. But I'm struggling to understand the document process for Lazarus. So, can anyone clarify a range of things please ?

I've read the Documentation Editor page, built the editor, looked at the xml in source tree and viewed the chm files.

User facing documentation appears in three places, (1) the chm file distributed with the binary, (2) eg http://lazarus-ccr.sourceforge.net/docs/lcl/buttons/tspeedbutton.html and (3) http://wiki.freepascal.org/TSpeedButton . The first two are derived from the source docs/xml files but not the wiki one. OK

But not always. There is no file containing the stuff that is on SQLdb tab. Eg TSQLQuery is quite well documented on web, http://wiki.freepascal.org/TSQLQuery, quite differently in the shipped chm file but neither content appears in a source xml file. TSQLTransaction OTOH, has a minimal web presense, OK in the CHM file, also no mention in the source xml. 

Question - Is that because TSQL* are FCL things, not LCL ?? Where does FCL stuff come from ?

(Ah you say, at last, a question !)

The footer to the wiki pages (eg  http://wiki.freepascal.org/TSpeedButton) is a useful index to the components, and from there, you can get to the appropriate sourceforge page. But if there is no wiki page, eg TEditButton, its actually pretty hard to find your way. The sourceforge index is a bit clunky, You need to know which unit its in, which tab (LCL) its one. Sigh....

Question - should we have a wiki page for ALL LCL components so that nicely laid out footer can be used ?

And speaking of TEditButton, its (very basic) description is in editbutton.xml in the source. Not in misc.xml. But other components appear in an xml file named for the lazarus tab they appear on. Also Tcalendar, TMainMenu and others.

Question - is there a document / policy / rumour outlining best practice on just where such content should be placed ?

Question - How do the Lord Developers want to receive patches ? One component's text description at a time ?  or a batch of updates united because they do or should appear in the same xml file ? (I'd prefer the former but its slower,,,,)

Wow, still reading ? Thats sad ......

David

[marcov]

The wiki is meant for fast moving documentation, the docs for thorough slow moving docs that are usable in the IDE. Patches that move somewhat validated/vetted content from wiki to docs are welcome.

Any patches to the XML files are welcome. I don't think it has to be really one change one patch file, but don't get it too unwieldy, and please don't use automatic tools without inquiring acceptance first (nothing is worse having to trawl through a 1MB patch file to separate one capitalizations from real changes). Do split them out according to project.

lazarus generates a lazutils and lcl.chm from the XML files (or loose html or PDF via latex)

The tool used to generate documentation that interacts with source (gets procedure signatures) is called fpdoc

FPC generates rtl.chm, fcl.chm and some minor ones (fcl-res,fpdoc etc).

The FPC CHM's come from XMLs in the fpcdocs repository (which then uses the sourcecode from the main fpc which should be checked out with name "fpc" at the same level as "fpcdocs")

There are also latex only docs (prog,user,ref) that are compiled to html and then converted to CHMs using a fairly simple FPC DOM program.

There is a fixdocs.sh script in the fpcdoc repository that builds the fpc docs (but it is a *nix script, might want to try a linux vm). In the past docs were only buildable on *nix, but this has improved somewhat in recent times (but the windows side is still not as easy)

Besides the CHMs, .xct files are generated, which contain metadata for links between CHMs.  The ref manual generates a .kwd files (which contains reference metadata for language buildins. I'm not sure this is still needed, it could be that the IDE now reads it from ref.chm directly)

To build the Lazarus CHMs, you need to set FPCDocDir to the FPC docs path (so it can find the .xct files) and use the build script build_lcl_chm.sh in lcl/docs/html 

There is some minor trickery involved. Not to hard, but sometimes confusing for the user. Some minor release engineering work might make this process more enduser doable.

The good part is that the whole documentation does not use anything external to the lazarus project than a recent latex installation. (miktex and TeX live are both used, I use the latter), so problems are usually easily reproduced.

[dbannon]

Great answer marcov, thanks.
I'll have some fun (yes, I think writing doc is fun).
No prob with unix stuff, been Unix then Linux full time user since year 2000.
As an action plan I will -
1. Ensure there is a wiki page that points to the sourceforge docs for all components that appear on Tab.
2. Starting on selected components, beef up the bit of text and add some short, generic code snippets if possible.

I'm still unsure which particular xml file the latter should go into. is the message that it does not matter too much ? 

[dbannon]

I hate it when I press the send button too fast ....

One more question, is there a more specific place to 'discuss' documentation issues ?  I think its pretty important to FPC and Lazarus, very easy to turn a new user off with incomplete or confusing docs.  But fully understand most users don't think about it until they cannot find what they want.

Davo 

[marcov]

I'm still unsure which particular xml file the latter should go into. is the message that it does not matter too much ?

I only do wiki for additional docs (like the executing programs faq). Anything that is core docs (like components), I prefer to have in fpdoc format. I do work mostly on the FPC side though.

fpdoc takes the sources and creates an XML structure to fill in.  These can be then filled in with fpdoceditor (view menu) or by hand. Then, the documentation is generated with updated source and the descriptions from the XML.

So there is an XML per unit, and most of it are templates of routines to document. There are some possibilities for general topics in an unit (e.g. a description of what the unit is good for in multiple topics).

Maybe it would be a good thing to read the fpdoc manual and look at the rtl and lcl chms.

There is not much discussion on documentation, but most of the FPC discussions happen on the fpc-devel maillist.

[JuhaManninen]

There is not much discussion on documentation, but most of the FPC discussions happen on the fpc-devel maillist.

.. and the Lazarus mailing list is best for discussing LCL documentation as all developers read it.

[dbannon]

Right. The thing I particularly wanted to start with is the component TSQLite3Connection. It appears on the LCL Component list in footer of eg http://wiki.freepascal.org/TIpFileDataProvider . But in fact its not an LCL at all, its a FCL. And that's under the control of the fpc people who don't, it seems, solicit input from people such as myself the way Lazarus does. OK, I'll concentrate on the easy stuff. The wiki and the LCL source docs.

Thanks for your help guys. I'll "solve" this now if thats OK....

[marcov]

Right. The thing I particularly wanted to start with is the component TSQLite3Connection. It appears on the LCL Component list in footer of eg http://wiki.freepascal.org/TIpFileDataProvider . But in fact its not an LCL at all, its a FCL. And that's under the control of the fpc people who don't, it seems, solicit input from people such as myself the way Lazarus does. OK, I'll concentrate on the easy stuff. The wiki and the LCL source docs.

Thanks for your help guys. I'll "solve" this now if thats OK....

The LCL source documentation is based on exactly the same tooling principles as the fcl source documentation.