As part of the 2.6.0 documentation effort, I regenerated the docs for FPC, and as usual I also try to build the LCL docs. I had to create some XMLs for non existing LCL units.

I also commited a clenaed up version of the script I use to generate lcl.chm as "docs/html/build_lcl_chm.sh".

I noticed that the LCL is now dependent on other package(s). At least a package "lazutils". There seems to be some documentation in docs/html/lazutils but they are only moved former LCL documentation.

What is the plan with this package? Is it a part of the LCL or really an optional component? The LCL docs refers to lazutf8 81 times. If it is just a matter of generating an extra CHM and set up the buildscripts for it, just say so and I'll do it.

I also noticed some copies of the RTl docs in docs/xml/rtl but these don't seem to be diffs/additions but full copies (and now it is hard to find out what these actually change). Can these be removed?

Below is the condensed error list:

Warning: Target ID of <link> in unit "LCLProc" is unknown: "#LazUtils.LazUTF8" <repeated 81 times in total>

Warning: Target ID of <link> in unit "InterfaceBase" is unknown: "#lcl.Controls.TCursor" Warning: Target ID of <link> in unit "InterfaceBase" is unknown: "#lcl.Controls.TCursor"

Warning: Target ID of <link> in unit "Graphics" is unknown: "#fcl.FPCanvas.TFPCanvasHelper.Changed" .. and other fcl-image related bits. (50+ times)

Warning: Target ID of <link> in unit "Graphics" is unknown: "#rtl.Classes.TPersistent.DefineProperties" Warning: Target ID of <link> in unit "Graphics" is unknown: "#rtl.Classes.TPersistent.AssignTo" Warning: Target ID of <link> in unit "Graphics" is unknown: "#rtl.Classes.TPersistent.DefineProperties" Warning: Target ID of <link> in unit "Graphics" is unknown: "#rtl.Classes.TPersistent.AssignTo" Warning: Target ID of <link> in unit "Controls" is unknown: "#rtl.Classes.TComponent.DefineProperties" Warning: Target ID of <link> in unit "Controls" is unknown: "#rtl.Classes.TPersistent.DefineProperties" Warning: Target ID of <link> in unit "Controls" is unknown: "#rtl.Classes.TPersistent.AssignTo" Warning: Target ID of <link> in unit "Controls" is unknown: "#rtl.Classes.TComponent.Notification" Warning: Target ID of <link> in unit "Controls" is unknown: "#rtl.Classes.TComponent.Notification" Warning: Target ID of <link> in unit "Controls" is unknown: "#rtl.Classes.TComponent.GetChildren" Warning: Target ID of <link> in unit "Forms" is unknown: "#rtl.Classes.TComponent.GetChildren" Warning: Target ID of <link> in unit "Forms" is unknown: "#rtl.Classes.TComponent.Notification" Warning: Target ID of <link> in unit "Forms" is unknown: "#rtl.Classes.TComponent.GetChildren" Warning: Target ID of <link> in unit "Forms" is unknown: "#rtl.Classes.TComponent.Loaded" Warning: Target ID of <link> in unit "Forms" is unknown: "#rtl.Classes.TComponent.Notification" Warning: Target ID of <link> in unit "StdCtrls" is unknown: "#rtl.Classes.TComponent.Loaded" Warning: Target ID of <link> in unit "StdCtrls" is unknown: "#rtl.Classes.TBasicActionLink.AssignClient" Warning: Target ID of <link> in unit "ExtCtrls" is unknown: "#rtl.Classes.TComponent.Loaded" Warning: Target ID of <link> in unit "ExtCtrls" is unknown: "#rtl.Classes.TComponent.DefineProperties" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TCollectionItem.GetDisplayName" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TCollectionItem.SetIndex" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TPersistent.GetOwner" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TStrings.Get" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TStrings.GetObject" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TStrings.Put" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TStrings.PutObject" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TStrings.SetUpdateState" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TPersistent.DefineProperties" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TCollectionItem.SetIndex" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TCollectionItem.GetDisplayName" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TCollection.Update" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TBasicActionLink.AssignClient" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TPersistent.AssignTo" Warning: Target ID of <link> in unit "ComCtrls" is unknown: "#rtl.Classes.TPersistent.GetOwner" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.RecordChanged" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.DataSetChanged" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.ActiveChanged" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.LayoutChanged" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.DataSetScrolled" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.EditingChanged" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#fcl.db.TDataLink.UpdateData" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#rtl.Classes.TCollectionItem.GetDisplayName" Warning: Target ID of <link> in unit "DBGrids" is unknown: "#rtl.Classes.TCollection.Update" Warning: Target ID of <link> in unit "LDockCtrl" is unknown: "#rtl.Classes.TComponent.Loaded" Warning: Target ID of <link> in unit "LDockCtrl" is unknown: "#rtl.Classes.TComponent.Notification"

Package LCL depends on LCLBase depends on LazUtils. LazUtils contains basic stuff like UTF-8 functions and classes, which might be useful for non LCL applications too.
LCLBase contains the platform independent units of the LCL. LCL contains the interface code to the widgetset(s).

All three should get their own docs. LCL+LCLBase can be bundled.

I also noticed some copies of the RTl docs in docs/xml/rtl but these don't seem to be diffs/additions but full copies (and now it is hard to find out what these actually change). Can these be removed?

DoDi?

Mattias

Marco van de Voort wrote

Below is the condensed error list:

How does this error list relate to the rest of the e-mail? Do some of them disappear if you use official rtl xml instead of the lazarus copy? Or do those elements don't exist?

Felipe Monteiro de Carvalho wrote

On Thu, Dec 29, 2011 at 5:06 PM, Marco van de Voort wrote: > Below is the condensed error list: How does this error list relate to the rest of the e-mail?

It's the raw data that was the basis for the mail.

Do some of them disappear if you use official rtl xml instead of the lazarus copy? Or do those elements don't exist?

I only use the FPC rtl, since I built the 2.6.0 docs. I did wanted to look what was changed in the lazarus docs, but the differences were too great, so I suspected the lazarus RTL stuff was an orphan. (which is confirmed by looking at the mutations in svn. Low, very low:-)) The mail was meant to get confirmation about that. Or maybe somebody has the corresponding original XMLs these are branched from so we can efficiently computate diffs.

Meanwhile btw I have a first lazutils setup working. (fpdoc is still running, but the lazutf8 errors are gone)

lazutils is now a separate package, and lcl references the new lazutils package. Everything is done and committed, in theory generating CHMs is a matter of installing dependencies, and then

running fixdocs.sh in the fpcdocs repo

and then running build_html_chm.sh in lazarus/docs/html

The snapshot at http://www.stack.nl/~marcov/doc-chm.zip is updated.

The lazutils package still needs an entry in the help menu though.

I can either separate lcl/lclbase or not, I can't have a logical separation and still put them in one file:-) At least afaik.

One problem with separation is that currently the lcl doc generation uses a wildcard in the lcl dir to find units. If these packages are split, then there need to be clear registries of which units belong to what package that the scripts can use. (to avoid units being member of two packages, or painful manual synchronization that is constantly out of date)

I meant: They should be separate in source, but packagers, installers, distributors can bundle them if they like.

lclbase: lcl, lcl/forms, lcl/nonwin32, lcl/widgetset lcl: lcl/interfaces/**

Mattias

As part of the 2.6.0 documentation effort, I regenerated the docs for FPC, and as usual I also try to build the LCL docs. I had to create some XMLs for non existing LCL units.

You're busy with Lazarus these days, too? :-)

I've just finished a first version of an documentation manager, which can create documentation projects for RTL, FCL, and any Lazarus packages. Main usage: quick creation of the final documentation, unit skeletons and update of existing XML doc files.

Since it's so overly complicated to interface such an application with the existing FPDoc tools (fpdoc, makeskel...), the next version will be much closer to Lazarus packages, using heavily modified versions of the fpc/utils/fpdoc/ units. The final project will become available in lazarus examples/docmgr (not to confuse with "dockmanager", for use by everybody :-)
[Recommendations for better directory/project names are welcome :-]

I also commited a clenaed up version of the script I use to generate lcl.chm as "docs/html/build_lcl_chm.sh".

The documentation manager will eliminate the need for any scripts, in an platform independent way :-)

I noticed that the LCL is now dependent on other package(s). At least a package "lazutils". There seems to be some documentation in docs/html/lazutils but they are only moved former LCL documentation.

Right.

What is the plan with this package? Is it a part of the LCL or really an optional component? The LCL docs refers to lazutf8 81 times. If it is just a matter of generating an extra CHM and set up the buildscripts for it, just say so and I'll do it.

Perhaps the LazUtils (etc.) documentation should be added to the LCL package, like the LCLBase documentation is (the essential) part of that package.

Note: documentation packages must not necessarily equal Lazarus (source) packages!

I also noticed some copies of the RTl docs in docs/xml/rtl but these don't seem to be diffs/additions but full copies (and now it is hard to find out what these actually change). Can these be removed?

Dunno, I also wonder when this (Unicode strings) change will be really finished :-(

Warning: Target ID of <link> in unit "LDockCtrl" is unknown: "#rtl.Classes.TComponent.Loaded" Warning: Target ID of <link> in unit "LDockCtrl" is unknown: "#rtl.Classes.TComponent.Notification"

IMO the LDock... stuff is so outdated, that it should be removed from the repository. I also wonder when the trunk will allow for docking on Windows again :-(

A happy new year to everybody :-)

DoDi

All three should get their own docs. LCL+LCLBase can be bundled.

ACK

These old copies can be removed. There existed (and still exist) substancial gaps in the RTL documenation, so that I felt a need for a version usable with Lazarus, but copies certainly are not a solution.

I already verified that one unit can be documented in multiple doc files, so that it might be easier to supply additional or corrected documentation in different doc files, extending the FPC provided RTL/FCL documentation. The contents of all doc files are merged inside the fpdoc tools, so that the Lazarus added content only has to be updated (removed) when covered properly by the FPC docs.

I'll resume my work on the FPC and Lazarus documentation when the documentation manager is finished. The current version requires too many patches to the FPDoc units, so that I'll implement an independent package and project structure in the next days. We can start discussing details right now, if somebody is interested in support for OSTarget specific or nationalized documentation (in a new thread, please).

DoDi

lclbase: lcl, lcl/forms, lcl/nonwin32, lcl/widgetset lcl: lcl/interfaces/**

I'm not sure of the use of documentation for the lcl/interfaces/*. There exist no references to the widgetset units in the source code, so that almost no links to such documentation can be added to the general LCL (interface) documentation. Consequently it does no harm when the widgetsets are documentated in separate packages (and CHM... files).

Eventually a Lazarus Help menu entry can be added, that refers to the (selected?) widgetset documentation?

DoDi

It seems closely related to fpdoc, so maybe
examples/fpdocmgr

What does that mean?
According to svn you added the files. Are they still needed or can they be removed?

I removed them.

Mattias

Ok. I removed them.

Mattias

> [Recommendations for better directory/project names are welcome :-] It seems closely related to fpdoc, so maybe examples/fpdocmgr

Fine, this will become the name of version 2.0 :-)

Sorry, I missed the target. My comment was aimed at the recent LazUtils and stringhandling changes.

Here "outdated" means the source code, not the documentation. Not only the LDock manager was never finished, docking on Windows is broken since almost a year, and according bug reports and patches have been delayed AFAIR to Lazarus 1.0 - what means to me that they will not be fixed this century :-(

DoDi

Please also remove it from the LCL(Base?) source package. Currently rebuilding the LCL fails with missing unit LDockTree in alllclunits :-(

As a workaround I added a dummy lcl\ldocktree.pp, to make the compiler happy.

DoDi

Sorry. Done.

Mattias

These scripts may be nice, but are not very useful for Window users. That's why my documentation manager tries to import LPK files, and now I ran into a problem with the new LazUtils.lpk:

How can "$(IDEBuildOptions)" be evaluated in code? This macro seems to specify compiler options (-Fi, -Fu...), which also are required by the fpdoc source parser.

For the RTL and FCL documentation the fpcdocs Makefile can be used on every platform, to produce the fully expanded fpdoc and makeskel commandlines, which can be redirected into an file and parsed by the docmgr. But how get the actual commandlines or compiler options for Lazarus packages?

DoDi

The macro IDEBuildOptions are only the custom options set by the user.

You can read the .compiled file or the Makefile.compiled or run the tool as IDE plugin. As IDE plugin you get all macros.

Mattias

I do doc work from time to time. And when I update FPC docs, I test the state of Lazarus too (and usually they are broken :-)

I've just finished a first version of an documentation manager, which can create documentation projects for RTL, FCL, and any Lazarus packages. Main usage: quick creation of the final documentation, unit skeletons and update of existing XML doc files.

For user documentation or for the lazarus project? Those are not necessarily the same things.

I think lowering the reliance on makefiles and shellscripts is a good thing. I'm already thinking about fixing the lpr in docs/html in time. But I first have to figure out if it is functional or not. If only because I'm slowly reaching the borders of my shellscript knowledge.

But while I like that direction, currently for me it is more important to keep the lcl building lazarus free. (that is no need for a updated build updated lazarus to build the docs, since I do it remotely on a server)

If that is at the expense of requiring a GUI system then IMHO it gets worse rather than better:-)

I agree with that. OTOH the split has been done, and it is now easier to maintain it than to undo it. But let's keep it in mind for the next reorganization.

I don't know what that has to do with it. Current docs describe the 2.6 branch not the 2.7 branch which has unicodestrings. But these files are already unmaintained from before the 2.6 branch existed, so I don't know what they are for.

They are code page aware strings, not unicodestrings. :)

That are two different string types and the latter existed already in 2.4 and maybe earlier ;)

Regards,
Sven

For documentation writers, and for users which want to have their local or otherwise specialized (national...) documentation.

I don't understand why (platform specific) shell scripts shall be used for documentation purposes - is Pascal not suited for such tasks? ;-)

But while I like that direction, currently for me it is more important to keep the lcl building lazarus free. (that is no need for a updated build updated lazarus to build the docs, since I do it remotely on a server)

Building final documentation is not a special problem when project files are used, which can be generated and updated by e.g. my documentation manager - then FPDoc can do it all.

A GUI is not a requirement, it only simplifies the development of the desired functionality :-)

I consider to commit a first demo version of my documentation manager, to clarify how it looks and what it can do. Then everybody can see what parts can be made available in a commandline version, too.

DoDi

I wonder how strings with different encoding will work together, without kind of Unicode strings - be UTF-8 or UTF-16.

I also wonder what's the benefit of using strings with different encodings together, when every other string operation will require a codepage translation...

DoDi

It looks like the LCL compilation depends on the used widgetset?

Which version of LCL.compiled should be used, to obtain meaningful compiler options for creating documentation?

DoDi

For the units in the LCLBase see lcl/Makefile.compiled. For units in the LCL interfaces use the
lcl/interfaces/*/Makefile.compiled.

Mattias

For the units in the LCLBase see lcl/Makefile.compiled. For units in the LCL interfaces use the lcl/interfaces/*/Makefile.compiled.

Thanks :-)

Can I expect the Makefile.compiled in the directory of any .lpk file?

DoDi

Any lpk that needs building via make has at least one of them. For the Lazarus sources this means all lpk belonging to "make bigide". Complicated packages like the lcl.lpk have multiple of them.

See here
http://wiki.lazarus.freepascal.org/Lazarus_Packages#Compiling_a_package_via_make

Mattias

2011/12/30 Hans-Peter Diettrich :

I don't understand why (platform specific) shell scripts shall be used for documentation purposes - is Pascal not suited for such tasks? ;-)

How about putting all the functionality necessary to build the documentation into lazbuild? It already has an option to build the IDE (lazbuild --build-ide), it has all units needed to read current Lazarus configuration, paths, etc, wouldn't it be consequent to make it also able to replace the shell scripts to build the docs (lazbuild --build-chmdoc)?

Bernd

Well, I'm the primary user, and I don't build lazarus (or lazbuild) before building the docs (I do it remotely on a server where there is always a clean lazarus svn).

I've had a look at the lpr Felipe pointed at, since the shell scripts already ate up way to much time, and that probably will do to.

IMO there exist too many user options, which are not reflected in a standard build, e.g. the output documentation directories on the server or user machine.

At least the generation of the documentation projects should be automated somehow, then every user can modify these projects according to his needs. I go different ways for building FPC and Lazarus documentation projects:

The RTL and FCL documentation is generated by a Makefile, so that the generated commandline can be recorded instead of excecuted (-n

mydoc.bat). The LazDoc Manager imports these commandlines and creates

the project files. An additional Makefile option could write the project files immediately, instead of creating the output.

The documentation of Lazarus packages instead shall be collected from the LPK files (not yet complete). The Makefile here is of little help, because the only mentioned source file is the synthetic allunits.pas file, which would deserve another parse. But of course options could be added (to LazBuild or the Makefile) to create the documentation (projects) like for the FPC documentation.

Once these project files exist, they can be modified or configured by the user, and the final documentation can be built in a simple script, containing lines like ("?" to be substituted):
fpdoc --project=? --format=? --output=?

Merging multiple documentation packages into one output file is not supported by fpdoc, so that e.g. the LCL documentation in one file would require to import the LCL, LCLBase and LazUtils packages into the same LCL package. I've put this feature into the LazDoc Manager already.

DoDi

Marco van de Voort wrote

If that is at the expense of requiring a GUI system then IMHO it gets worse rather than better:-)

+1
The generation should be callable from another script.

-Michael

As it already is?

If you want to learn more about the documentation manager, look into examples\fpdocmanager\ :-)

DoDi