[Lazarus] Lazarus trunk help options: CHM Help browser does not show up

Marco van de Voort marcov at stack.nl
Sat Feb 18 22:15:09 CET 2012


On Sat, Feb 18, 2012 at 06:40:14AM +0100, Hans-Peter Diettrich wrote:
> >>> commandline limits. (see below to get an idea)
> >> Where is the DOCS option (and more) documented?
> > 
> > Should it be?
> 
> Tell me a reason why it does *not* deserve documentation.

What doesn't deserve documentation?

But tell me the reason why it should have an higher priority on people's
lists than it has now?

> > If you think it should, please annotate such things in the wiki.  :-)
> 
> What do you expect me to annotate? That I'm missing a documentation of 
> the options, which the user can add on a "make" commandline?

Yes. If you find something out (e.g. by inspection makefiles), and think if
that is important, document it somewhere. I've been doing that for years
with the buildfaq.

> > Then they shouldn't be in the project system, but passed on the commandline,
> > or a seperate settings file.
> 
> They become part of the project created using --write-project. This is 
> not noticeable in the RTL and FCL projects, where all files reside in 
> the same directory. When e.g. the LCL refers to the RTL and FCL, the 
> content files (--import) reside in different directories, so that at 
> least macros or environment options have to be used to evaluate the 
> pathes on a user machine.

That's not what I meant. It's true that that info is needed in fpdoc before
compiling, but there is no reason whatsoever why it should be in the project
file that is checked into SVN and that contains which sources go into the
package.

IOW the project state should be separated in a system dependent (user
settings and preferences and paths), and a system independent part (which
sources and XMLs contribute to the patches, parameterised with macros in a
few rare cases)

> > Having to edit project files before using them, just switches one voodoo
> > solution by the other.
> +1

Good.

> > Which installer? Primarily docs are run by release engineers from svn. 
> > This use should be central.
> 
> This part was in response to the generation of local documentation by 
> the new installer (FPCup) of Reinier.

Specially then, when running updates from SVN. A need for editing checked
out files only leads to conflicts. This should be separate IDE state.

> >> and chance for errors. The input specifiers in a project include the 
> >> settings derived on the machine on which the project was created, which 
> >> will mix up with the settings added by FPDoc at runtime. One such 
> >> problem has already been fixed in the MakeFile.
> > 
> > I've no idea what so ever you are talking about.
> 
> See this snippet from your posted make:
> 
>  >>
> make[1]: Entering directory `D:/repo/fpcdocs'
> ../fpc/utils/fpdoc/fpdoc  --warn-no-node --package=rtl --descr=rtl.xml
> --content=rtl.xct --hide-protected --descr=system.xml --input="-dfpdocsystem
> -- -dHASGETHEAP
> STATUS -dSUPPORT_DOUBLE ../fpc/rtl/win32/system.pp -Fi../fpc/rtl/win32
> -Fi../fpc/rtl/unix -Fi../fpc/rtl/inc -Fi../fpc/rtl/i386 -dCPU32 -dHASVARIANT
> - -dFPC_HAS_TY
> PE_EXTENDED -dHASWIDECHAR -Fi../fpc/rtl/win -Fi../fpc/rtl/win32
> -Fi../fpc/rtl/unix -Fi../fpc/rtl/linux" --descr=objpas.xml
> <<
> 
> I'd suspect that "-Fi../fpc/rtl/win32" together with 
> "-Fi../fpc/rtl/unix" can result in problems. At least the results depend 
> on the search order for the include files.

That's indeed true. I didn't notice it, probably manually fixed it in
earlier attempts.
 
> >> And one more problem are inconsistent directory separators. At least I 
> >> had to fix several paths already, before passing them to fpdoc or makeskel.
> > 
> > That is general crossplatform and make problems. One of the reasons for me
> > that make has to go long term.
> 
> This is not only a make problem, it also turned out that FPDoc, 
> build_lcl_docs, and maybe even RTL functions, have problems with mixed 
> directory separators. Problems can arise when a script uses the current 
> platform separators, and these are different from the separators stored 
> in an fpdoc project file.

True. These problems also come up with CHM related tools.

But those are the minor ones. The make system which seems to hit the commandline limit of
the shell (8192) are the problem immediate problem.

Then, the platform dependence of doc making (though IMHO we should do per
platform docs. Just fixate to a platform, and then try to improve the docs
with little building improvements. (e.g. exclude lists for very linux
specific topics, better annotation of what is platform specific etc)

Adding another (platform) dimension to docs building will only decrease, not
increare the quality of the docs IMHO. _AND_ the ease of building them.

Then, finally, as stated to Reinier, tex4ht is also a big question mark. 




More information about the Lazarus mailing list