Trying out FPDocManager.

Have somme comments/questions - sorry if these have been raised before:
1. What is the "common documentation directory" you are asked to select when starting it for the first time? Does it contain your sources? Compiled documentation? Would be nice if there were a bit more description. (Probably is the "root directory" in the config assistant. Ok.)

2. Configuration assistant: good idea!
2nd tab, FPC: "Now select the FPC
source directory and the FPC documentation directory in it" Assuming that means the fpcdocs SVN repository
I keep fpcdocs separate as I have multiple fpc installs. Is it required to have fpcdocs under your FPC directory?

3. RTL step: noticed you need to create 2 Windows batch files. Wouldn't it be more useful if there were some cross platform way of generating the rtl etc docs (e.g. shelling out to fpdoc with parameters like lazbuild is doing right now?)

4. Trying to select the newly generated rtl.bat gives an access violation (Lazarus SVN 36494, FPC SVN 20683 x86). Any fix for that?

Thanks,
Reinier

Trying out FPDocManager.

Thanks for trying out, and for all your feedback :-)

Sorry for the confusion :-(
[Please suggest the most descriptive name for it]

Yes, that directory will hold all FPDoc output and the config files for the manager itself. It can be initally empty.

No, that's why you have to tell the manager where that directory is.

3. RTL step: noticed you need to create 2 Windows batch files. Wouldn't it be more useful if there were some cross platform way of generating the rtl etc docs (e.g. shelling out to fpdoc with parameters like lazbuild is doing right now?)

These files can be omitted as soon as somebody explains how to use the FPCDocs Makefile to *only* create the FPDoc projects.

4. Trying to select the newly generated rtl.bat gives an access violation (Lazarus SVN 36494, FPC SVN 20683 x86). Any fix for that?

That looks like a bug in the Makefile and/or FPDoc. Does the AV also occur when you invoke "make ..." directly, without generating the batch file? The Makefile is designed on/for Linux, with possible problems on other platforms.

Is it related to Mantis 0021148? (still open, no response)

FPDoc showed a strange behaviour with duplicate paths and options, as may be inserted by the Makefile. If this is the reason of the AV, I'll have to supply an according patch for FPDoc.

It's already known that "touch" is not normally available on Windows, and the CSS file didn't (still doesn't?) exist and consequently cannot be copied. These lines should be removed from the batch file, but they never should cause an AV.

DoDi

Mmm yes, "Project directory" is even more vague.
Perhaps choose something like "FPDocManager documentation directory" and make sure whatever you do, the names match between the readme, config wizard and the dialog?

I understand.
However, I'd suggest rewording the text in that tab. To me it implies you have to have your docs under the FPC dir, while you just confirmed it can be anywhere.

Not going there... make files are not my forte at all..

No, it doesn't (at least for rtl.chk)

Just to clarify: make... > bla.bat (as instructed in the wizard) works perfectly fine. Selecting the resulting .bat file in the wizard fails. Does the wizard execute that batch file or something? That would be... unexpected for a config wizard...

Is it related to Mantis 0021148? (still open, no response)

rtl.bat now has:
C:\Development\extras\fpcdocs>type rtl.bat
fpdoc --warn-no-node --package=rtl --descr=rtl.xml --content=rtl.xct --hide-pr
tected --descr=system.xml --input="-dfpdocsystem -dHASGETHEAPSTATUS -dSUPPORT_D
UBLE ../rtl/win64/system.pp -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/inc -Fi../
tl/i386 -dCPU32 -dHASVARIANT -dFPC_HAS_TYPE_EXTENDED -dHASWIDECHAR -Fi../rtl/wi
-Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=objpas.xml --input="-d
ASINTF ../rtl/objpas/objpas.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi
./rtl/linux" --descr=types.xml --input="../rtl/objpas/types.pp -Fi../rtl/win -F
../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=strutils.xml --input="../
tl/objpas/strutils.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/li
ux" --descr=sysutils.xml --input="../rtl/unix/sysutils.pp -Fi../rtl/objpas/sysu
ils -Fi../rtl/inc -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux"
--descr=strings.xml --input="../rtl/inc/strings.pp -Fi../rtl/i386 -Fi../rtl/inc
-Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=mouse.xml
--input="../rtl/unix/mouse.pp -Fi../rtl/inc -Fi../rtl/win -Fi../rtl/win64 -Fi..
rtl/unix -Fi../rtl/linux" --descr=keyboard.xml
--input="../rtl/unix/keyboard.pp
-Fi../rtl/inc -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --d
scr=crt.xml --input="../rtl/unix/crt.pp -Fi../rtl/inc -Fi../rtl/win -Fi../rtl/w
n64 -Fi../rtl/unix -Fi../rtl/linux" --descr=video.xml --input="../rtl/unix/vide
.pp -Fi../rtl/inc -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux"
--descr=dos.xml --input="../rtl/unix/dos.pp -Fi../rtl/inc -dcpui386 -Fi../rtl/w
n -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=sockets.xml --input="
dver1_0 ../rtl/unix/sockets.pp -Fi../rtl/inc -Fi../rtl/win64 -Fi../rtl/win -Fi.
/rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=objects.xml --input="../rtl/
nc/objects.pp -Fi../rtl/i386 -Fi../rtl/win64 -Fi../rtl/win -Fi../rtl/win64 -Fi.
/rtl/unix -Fi../rtl/linux" --descr=heaptrc.xml
--input="../rtl/inc/heaptrc.pp -
i../rtl/i386 -Fi../rtl/win64 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi..
rtl/linux" --descr=mmx.xml --input="../rtl/i386/mmx.pp -Fi../rtl/win64 -Fi../rt
/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=ipc.xml --input=".
/rtl/unix/ipc.pp -Fi../rtl/win64 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -
i../rtl/linux" --descr=printer.xml --input="../rtl/unix/printer.pp -Fi../rtl/wi
64 -Fi../rtl/inc -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux"
-descr=typinfo.xml --input="../rtl/objpas/typinfo.pp -Fi../rtl/win64 -Fi../rtl/
in -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=ports.xml --input="
./rtl/unix/ports.pp -Fi../rtl/win64 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/uni
-Fi../rtl/linux" --descr=getopts.xml --input="../rtl/inc/getopts.pp -Fi../rtl/
in64 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=emu3
7.xml --input="../rtl/go32v2/emu387.pp -Fi../rtl/i386 -Fi../rtl/win -Fi../rtl/w
n64 -Fi../rtl/unix -Fi../rtl/linux" --descr=dxeload.xml --input="../rtl/go32v2/
xeload.pp -Fi../rtl/i386 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl
linux" --descr=go32.xml --input="../rtl/go32v2/go32.pp -Fi../rtl/i386 -Fi../rtl
win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=gpm.xml --input="-d
ER1_0 ../rtl/linux/gpm.pp -Fi../rtl/i386 -Fi../rtl/win -Fi../rtl/win64 -Fi../rt
/unix -Fi../rtl/linux" --descr=graph.xml
--input="../packages/graph/src/unix/gr
ph.pp -Fi../packages/graph/src/inc -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix
-Fi../rtl/linux" --descr=oldlinux.xml --input="../rtl/linux/oldlinux.pp -Fi../r
l/linux -Fi../rtl/unix -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/l
nux" --descr=unixtype.xml --input="../rtl/unix/unixtype.pp -Fi../rtl/unix -Fi..
rtl/linux -Fi../rtl/linux/i386 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi
./rtl/linux" --descr=baseunix.xml --input="../rtl/unix/baseunix.pp -Fi../rtl/un
x -Fi../rtl/linux -Fi../rtl/linux/i386 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/
nix -Fi../rtl/linux" --descr=unix.xml --input="../rtl/unix/unix.pp -Fi../rtl/u
ix -Fi../rtl/linux -Fi../rtl/linux/i386 -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl
unix -Fi../rtl/linux" --descr=classes.xml
--input="../rtl/win64/classes.pp -Fi.
/rtl/objpas/classes -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linu
-dfpdocsystem" --descr=unixutil.xml --input="../rtl/unix/unixutil.pp -Fi../rtl
win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=x86.xml --input="..
rtl/unix/x86.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" -
descr=dynlibs.xml --input="../rtl/inc/dynlibs.pas -Fi../rtl/unix -Fi../rtl/win
Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=linux.xml --input="../rt
/linux/linux.pp -Fi../rtl/linux -Fi../rtl/unix -Fi../rtl/win -Fi../rtl/win64 -F
../rtl/unix -Fi../rtl/linux" --descr=math.xml
--input="../rtl/objpas/math.pp -F
../rtl/i386 -dFPC_HAS_TYPE_EXTENDED -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/uni
-Fi../rtl/linux" --descr=matrix.xml --input="../rtl/inc/matrix.pp -Fi../rtl/in
-Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=dateuti
s.xml --input="../rtl/objpas/dateutils.pp -Fi../rtl/objpas -Fi../rtl/win -Fi../
tl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=wincrt.xml --input="../package
/graph/src/win32/wincrt.pp" --descr=clocale.xml
--input="../rtl/unix/clocale.pp
-Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=cthreads.
ml --input="../rtl/unix/cthreads.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/uni
-Fi../rtl/linux" --descr=cmem.xml --input="../rtl/inc/cmem.pp -Fi../rtl/win -F
../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=cwstring.xml --input="../r
l/unix/cwstring.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux
--descr=exeinfo.xml --input="../rtl/inc/exeinfo.pp -Fi../rtl/win -Fi../rtl/win
4 -Fi../rtl/unix -Fi../rtl/linux" --descr=lineinfo.xml --input="../rtl/inc/line
nfo.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --descr=ln
odwrf.xml --input="../rtl/inc/lnfodwrf.pp -Fi../rtl/win -Fi../rtl/win64 -Fi../r
l/unix -Fi../rtl/linux" --descr=ctypes.xml --input="../rtl/inc/ctypes.pp -Fi../
tl/unix -Fi../rtl/win -Fi../rtl/win64 -Fi../rtl/unix -Fi../rtl/linux" --format=
tml --output=rtl --footer-date="mmm dd yyyy" --write-project=winrtl.xml cp fpdoc.cst rtl/fpdoc.css
touch rtl.chk

Running it gives:
<snip huge amount of parameters>
FPDoc - Free Pascal Documentation Tool
Version 2.7.1 [2012/03/31]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

Done.

C:\Development\extras\fpcdocs>cp fpdoc.cst rtl/fpdoc.css cp: cannot create regular file `rtl/fpdoc.css': No such file or directory (fpdoc.cst exists, subdir rtl does not exist)
... so it seems to run with different errors - didn't generate those errors you saw)..

FPDoc showed a strange behaviour with duplicate paths and options, as may be inserted by the Makefile. If this is the reason of the AV, I'll have to supply an according patch for FPDoc.

Looking at todays bugtracker, there's more wrong with fpdoc in trunk anyway...

It's already known that "touch" is not normally available on Windows, and the CSS file didn't (still doesn't?) exist and consequently cannot be copied. These lines should be removed from the batch file, but they never should cause an AV.

Got my own touch in the path (not in FPC though).

Thanks,
Reinier

I tried to improve the text, and fixed another bug that had crept into the wizard.

>> Is it required to have fpcdocs under your FPC directory?

Correction: you are right, according to the FPDoc documentation fpcdocs must reside inside a FPC source directory, so that the Makefile can find the units.

But you can choose any FPC version, if you have more than one on your machine (as I have).

Me2 :-(

>> 4. Trying to select the newly generated rtl.bat gives an access >> violation (Lazarus SVN 36494, FPC SVN 20683 x86). Any fix for that?

You're right, I could reproduce and fix this bug :-) Please update and try again.

Thanks
DoDi

Hmmm... Where did you find that? I know it's at least the easiest option, but IIRC, you can use things like the FPCSRCDIR environment variable and css-file command line option to tweak things.

Having the structure is how I currently have my directories set up; I think I'll try and make that work if possible:
c:\development
|
+-extras
| +-fpcdocs
| +-synapse
| +-tiopf
| +-...
+-fpctrunk
+-fpcfixes26
+-....
+-lazarusfpctrunk
+-lazarusfpctrunkx64
+-lazarusfixes26
+-....

Wondering how you are going to make that work for Linux/other OS... Perhaps you could create the batch/shell files from within fpdoc manager using TProcess.Execute?

Ok.

Ok thanks. I was reading the FPDoc reference manual pdf... ;)

As I mentioned: instead of having the user run make blabla > bla.bat: Perhaps you could create the batch/shell files from within fpdoc manager using TProcess.Execute?

Thanks, that one seems fixed.

However, selecting fcl.bat gives another access violation....

Thanks,
Reinier

In fpcdocs/README.DOCS. But FPCSRCDIR may be usable when the fpcdocs are in a different place (as mentioned there).

Not me :-(

As long as FPC and Lazarus expect that every user can use a console, I see no better solution. Except that the developers should decide to distribute the FPDoc projects instead of the Makefile...

DoDi

Again: not me :-(

I'm not familiar with shelling out to processes, in detail on different platforms. Where is "make", and where is "fpdoc"? But I'm open to contributions...

DoDi

However, selecting fcl.bat gives another access violation....

Fixed, removed more special support for the fcl docs.

DoDi

http://wiki.lazarus.freepascal.org/Executing_External_Programs

Location of make: doesn't matter where make is as long as it's in the path (on Windows at least).
Otherwise, you can test if it's in the compiler binary path, <fpcdir>\bin\<architecture>, e.g.
c:\development\fpctrunk\bin\i386-win32\make.exe

fpdoc is in <fpcdir>\utils\fpdoc\fpdoc.exe (or in the compiler binary path, see above)

See here
http://lazarus.freepascal.org/index.php/topic,16512.msg90010.html#msg90010 for a simple sample program with TProcess...

IIRC, you said yourself you are limiting the program to Windows, so don't see how cross platform considerations come into it..

Thanks,
Reinier

E.g. means exempli gratia, for example.

This doesn't help when the Path is not set up as required.

If you don't have a make.exe in your path or fpc bin directory... well, you can always make the make path configurable for the user (instead of having him run make himself)...

Alternatively, just tell the user to put make.exe in the bin dir.... should still be more user friendly than having him hunt down the proper path for make, start a console session, run make with that path and rtl.chk etc.

Or tell users to set up the path as required before starting fpdocmanager... not my preferred solution but would be possible.

See e.g. fpcup for a way on how to detect existing make.exe, including Delphi make.

I think limiting the number of manual steps a user should go through just to start a tool makes a lot of sense - especially if these steps can be automated for almost 100% (and error handling with proper messages can do the rest).
That's why I liked your config wizard so much in general.

The FPDocManager has fpdoc built-in, but this doesn't help when the Makefile wants to call a stand-alone fpdoc.

See before for location of fpdoc in the FPC tree.

Again: feel free to provide an patch or a stand-alone tool, that allows to create an fpdoc commandline or project for the RTL and FCL, on every machine.

No thanks, I think I'll stick with the existing fpdoc tools:
1. FPDocmanager is not cross platform
2. FPdocmanager requires manually setting unit paths and recompiling
3. As you mentioned, it doesn't support an FPCDocs directory separate from an FPC directory

Then why is fpdocmanager in Lazarus, not in FPC - I thought fpcdocs should be maintainable with FPC only without requirement for Lazarus, but I might be mistaken...
Do the current fpdoc toolset maintainers agree with FPDocmanager projects replacing makefiles? And when will this replacement happen?

I've been fighting with the existing fpdoc system, that's why I decided to try fpdocmanager... having an idea which way things will go will definitely help.

Thanks,
Reinier

I don't have "make" in my (Windows) path, nor fpdoc. I've written batch files that add the compiler bin and tools directory to the path, for every FPC version. The FPDocManager has fpdoc built-in, but this doesn't help when the Makefile wants to call a stand-alone fpdoc.

All my FPC/Lazarus stuff resides on D:, not on C:.

See here http://lazarus.freepascal.org/index.php/topic,16512.msg90010.html#msg90010 for a simple sample program with TProcess...

This doesn't help when the Path is not set up as required.

Again: feel free to provide an patch or a stand-alone tool, that allows to create an fpdoc commandline or project for the RTL and FCL, on every machine.

IIRC, you said yourself you are limiting the program to Windows, so don't see how cross platform considerations come into it..

The FPDocManager has no platform dependencies. The only external dependency currently is the fpcdocs Makefile, which should be replaced by fpdoc projects, supplied and maintained by the FPC/fpdoc people.

DoDi

I am in a position to answer this one:

The FCL/RTL docs will have a fpdoc project file, as soon as the necessary support for it has migrated to the fixes branch. I have set up and tested these files (albeit only on linux). The fpdoc project file format is documented already.

That said:
If FPDocmanager has some private extensions to the fpdoc project file format (or uses another file altogether), they will not be included.

Michael.

Good news!
Where is the fpdoc project file format documented?

Thanks,
Reinier

in the fpdoc documentation: fpdoc.tex, obviously :-)

Michael.

Oh joy ;) Thanks; Lyx seems to be able to open it, so I'm happy ;)

Regards,
Reinier

A happy user !!

Quick, we must stuff him and put him in a museum !!

Michael.

As long as it's on alcohol ;)

More seriously, if you want to have a hand in testing (+asking newb questions) on Windows, you have my email address...

Regards,
Reinier

I have plenty of vodka and pastis available ;)

More seriously, if you want to have a hand in testing (+asking newb questions) on Windows, you have my email address...

Not sure I catch your drift ?

You want me to test on windows with your help,
or do you want me to help you when you're testing on Windows ?

The former is not going to happen, but the latter may happen :-)

Michael.

Ah... the possibilities.... I'd prefer pastis and a bit of water... giving that nice enigmatic look of preserved user in a big glass container...

Yep, the latter.

Reinier

I leave it to the users, like you <g>, to send complaints to the FPC team, instead of implementing complicated and error prone workarounds for an obviously simple proper fix.

Sorry, you have a very wrong picture of the FPDocManager :-( None of the above is true, eventual restrictions (if ever) are imposed by fpdoc.

Then why is fpdocmanager in Lazarus, not in FPC - I thought fpcdocs should be maintainable with FPC only without requirement for Lazarus, but I might be mistaken...

You can have a GUI, or use the FPC commandline procedures. LazDE also is a Lazarus tool for documentation writers.

Do the current fpdoc toolset maintainers agree with FPDocmanager projects replacing makefiles?

You seem to miss that *fpdoc* introduced projects, the FPDocManager only *uses* that feature.

And when will this replacement happen?

Don't ask me :-(

I've been fighting with the existing fpdoc system, that's why I decided to try fpdocmanager... having an idea which way things will go will definitely help.

I've been fighting with the existing fpdoc system, too, that's why I decided to implement fpdocmanager. I can't help you if you don't like it, for reasons residing in fpdoc.

DoDi

FPDocManager uses the project files as they are. It leaves it entirely to fpdoc, to create and load such files.

DoDi