Hans-Peter Diettrich wrote 6 lines
>>> 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.
Show quoted text 9 lines
> 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.
Show quoted text 5 lines
> 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.
Show quoted text 24 lines
>> 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 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.
Show quoted text 11 lines
>> 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.
