[Lazarus] Documentation update (CHM building, lazutils)

[Marco van de Voort]

On Fri, Dec 30, 2011 at 05:03:23AM +0100, Hans-Peter Diettrich wrote:
> Marco van de Voort schrieb:
> > 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 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.
 
> 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 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)
 
> > 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 :-)

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

> > 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 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 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 :-(

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.