In my (Windows) SVN fpc installs, I can find the fpdoc executable both under the bin directory as well as utils\fpdoc

However, I've only found fpdoc.css in utils\fpdoc (and a different one in packages\fcl-res\xml) but not in the bin directory.

IIRC, fpdoc picks up fpdoc.css when generating HTML/CHM output. Shouldn't fpdoc.css be also present under the bin directory then?

Thanks,
Reinier

Bump.

Any reactions?

No.
You're responsible for putting this file wherever it needs to be put.

Michael.

Fine, I understand that, but what is fpdoc then doing in the bin directory?

Is it used in some other program?
This program presumably either:
- uses its own copy or version of the css file
- references the fpdoc.css in the utils\fpdoc directory (in which case: why not use the fpdoc executable there)
- is not interested in the css file

I must still be missing something...

Thanks,
Reinier

The binary ? Where would you put it if not in bin ?

The fpdoc system uses a fpdoc.css file for style.
We provide one which can be used, but you are under no obligation to use that file. You can perfectly create one from scratch, or adapt the existing one. Since we do not know what you want to do, we do not 'automagically' copy it to the output.

Michael.

Sure, sure, but my point was the connection between fpdoc.css and fpdoc.exe...
Not that important, please see below.

The following is meant as constructive advice, not criticism: Very well, how many people do you think use fpdoc *and* customize fpdoc.css? Even then, copying fpdoc.css to the bin directory would give a sensible default, no? If people want to customize it, replace it etc they can then always do so.

If you want your fpdoc.exe usable from the bin directory, I'd just copy over fpdoc.css during install.

Now we've got 2 different behaviours:
- fpdoc in the source directory has fpdoc.css and will generate chm/html files with it
- fpdoc in the bin directory doesn't have it.
In my view this difference in behaviour is unnecessary and only server to needlessly further increase the complexity of the fpdoc system...

Thanks,
Reinier

There is no difference in behaviour.

If you do not specify the location with --css-file, then fpdoc does not look in the bin directory, only in the current working directory.

That we should distribute the file somewhere is something I agree on, but I do not think it should be in the bin directory; it's not a binary, after all.

Michael.

Reinier Olislagers wrote

Very well, how many people do you think use fpdoc *and* customize fpdoc.css? Even then, copying fpdoc.css to the bin directory would give a sensible default, no?

I fully agree. I know you are allowed to customise the CSS file, but i don't know of a single project or person that actually done that. The fpdoc program should at least copy in the default fpdoc.css file - because it looks a damn lot better with the default fpdoc.css than without.

That we should distribute the file somewhere is something I agree on, but I do not think it should be in the bin directory; it's not a binary, after all.

+1

Isn't the fpdoc.css auto generated by the fpdoc executable? For some reason I though it was.

[...] The following is meant as constructive advice, not criticism: Very well, how many people do you think use fpdoc *and* customize fpdoc.css?

I thought almost everyone does that.

Even then, copying fpdoc.css to the bin directory would give a sensible default, no? If people want to customize it, replace it etc they can then always do so.

Please put only binaries into the bin. It might be in PATH.

Having two binaries with the same name is somewhat confusing.

Mattias

Right.
But there still is a difference between:
cd c:\development\fpc\bin\i386-win32
fpdoc ...etc...
and
cd c:\development\fpc\utils\fpdoc
fpdoc ...etc...

That we should distribute the file somewhere is something I agree on, but I do not think it should be in the bin directory; it's not a binary, after all.

Neither are
fp.ans
fpc.cfg
yylex.cod
program.pt
cvsup.tdf
... but they still live in my fpc bin directory...

<innocent expression>Probably supporting files of some sort?</innocent expression>

Still, I'm glad you think the file should be distributed somewhere...

Thanks,
Reinier

Hi

:-) Good point.

I do not understand what you try to say. Please explain ? As far as I know, only 1 copy of fpdoc is distributed. So where you get the second path from, I do not know.

I suspect the programs that use those files are coded to look in the program directory. They stem from the Dos age, and it was common practice in those days.

Meanwhile I think the world has evolved to other practices :-)

Still, I'm glad you think the file should be distributed somewhere...

Well, we're trying hard not to be totally unreasonably pig-headed. It takes a lot of effort, but we try nonetheless :-)

Jokes aside:
I leave it up to the Windows setup builders to decide where it should go. If they decide on the bin dir anyway, then so be it...

Michael.

My point is there *is* a difference in behaviour between fpdoc in the bin directory and
fpdoc in the utils\fpdoc directory (because fpdoc.css is only present in the latter)
Yes, this difference may only appear if you first change the current directory to that directory. But no, this difference is not necessary IMO. Sorry, I can't explain it any way else.

As far as I know, only 1 copy of fpdoc is distributed. So where you get the second path from, I do not know.

Running
make all
or (very much less likely)
make install
from an SVN copy.

<snip>

Meanwhile I think the world has evolved to other practices :-)

Tell that to the people who use fpc.cfg ;)

Well, we're trying hard not to be totally unreasonably pig-headed. It takes a lot of effort, but we try nonetheless :-)

Same here - reasonably pig-headed is a totally different story though ;)

Jokes aside: I leave it up to the Windows setup builders to decide where it should go. If they decide on the bin dir anyway, then so be it...

What about the make files/fpmake etc?

Anyway, while I can continue arguing this point (given pig-headedness already mentioned), I think I got across what I wanted to say... even though not everybody agrees ;)

Thanks,
Reinier

In our previous episode, Reinier Olislagers said:

The scripts that generate have their own locations set to the fpdoc.css

Since generating docs requires additional repositories (like fpcdoc), it is not a standard feature of installs anyway.

In our previous episode, Reinier Olislagers said:

FPC is supported to be used in installed form only, not directly from build directories. That is limited to what is needed for bootstrap.

True for fpc source docs...

So you're saying FPC users who don't have the source installed (e.g. on Debian) should get the source, download fpdoc.css separately or create their own if they want to generate HTML documentation of their own code. Doesn't seem user friendly.

It just doesn't make sense to me to distribute part of a tool. Granted, that part is optional, can be customized etc. but still, if it's there, people are more likely to use it than if it's not there.

I'm trying to be constructive here, but I get a lot of answers in the sense that "this is how it is, don't worry, it's the best solution" or "this is what you're doing wrong, you should be doing it my way".

Given Michael's suggestion, and in an effort to have some benefit out of this discussion:
1. Would anybody mind if FPC's fpdoc.css is distributed in fpc installs (not only in source?)
2. If the bin directory is unsuitable, where should it be placed?

I'd be happy to use my awful make/fpmake-fu to try and figure out a patch. If not, well, at least this file has gotten a thorough discussion.

Thanks,
Reinier

PS: For some reason, my Lazarus install (from the Windows installer) has an fpdoc.css that states

/*
$Id: fpdoc.css 32727 2011-10-07 07:47:29Z vincents $

Default style sheet for FPDoc reference documentation by Sebastian Guenther,

Feel free to use this file as a template for your own style sheets. */

The only diff with the fpc one is the
$Id: fpdoc.css 32727 2011-10-07 07:47:29Z vincents $ line

If fpc distributed fpdoc.css, presumably distributing this with Lazarus won't be necessary either...

There is no discussion that fpdoc.css should be distributed. The only question is: where should we put it ?

Michael.

Yes, you told me. I'm asking because I'm not sure what Marco wanted (and anybody else).

The only question is: where should we put it ?

Apparently the bin directory is not satisfactory (though I don't see why)?

On my Laz install (installed by Win installer) I only have bin,msg,units under the fpc directory.
Perhaps there are others in other versions...

What about the fpc root directory then?

michael.vancanneyt wrote on Tue, 14 Aug 2012:

There is no discussion that fpdoc.css should be distributed. The only question is: where should we put it ?

On Unix, $PREFIX/share/doc/fpc-$fpcversion/ would seem appropriate to me.

Jonas

2 reasons:

1. I do not think you should put such files there. I know that there are some historic reasons for putting some 'extra' things there, but I think we should change that DOS habit.

2. fpdoc.exe will not search it there. By putting it there you will create the expectation that it will search for it there (as some of the other utils do), but it will not.

I think it is better to have it in fpc/docs.

Michael.

<snip>

Ok.
So:
<fpc>\docs for Windows and
on Linux/Unix/(OSX??) Jonas' suggestion
$PREFIX/share/doc/fpc-$fpcversion/

Thanks,
Reinier

Seems like the reasonable thing, yes.

Michael.

Actually, the file is more a configuration file for fpdoc than its documentation, isn't it? From this point of view, shouldn't SysUtils.GetAppConfigDir serve as the most reasonable location?

Tomas

It is definitely not a config file. It is a file that must be copied to every project you want to document with fpdoc.

Michael.

In our previous episode, Jonas Maebe said:
[ Charset UTF-8 unsupported, converting... ]

Is that correct? While used in doc building, it is not a documentation file.

If you consider it an example or template share/examples/fpc-x would be better. (install.sh allows to specify a separate directory for examples)

Thinking about it, I will change fpdoc so it does not need the file installed, but generates it if not present, as Graeme suggested.

That will be far easier, and causes less headaches and discussion.

Michael.

If I understand it correctly, this is only the case for plain HTML whereas CHM includes it internally (and from this point of view it is much more a configuration file influencing the output than part of fpdoc documentation
- see also the comment from Marco).

From certain point of view it is unfortunate that the same file (equally

named and potentially even equally placed) is used as the default template for generation of new documents with fpdoc and also for viewing of the (distributed) FPC documentation because fpdoc users may want to change the style of their generated documents but they may not be interested in changing the design of our FPC documentation.

Tomas

Sounds good!

As far as I know, CHM does not include it internally. It expects it to be there, just as the other HTML files should be there.

The file in the docs dir is there so they can copy it. It will never be used directly.

Anyway, it's all moot now, I will let fpdoc generate the file.

Michael.

In our previous episode, said:

The CHM files contain a copy of the fpdoc.css file. It expects it to be there or specified with CSSFILE on the make cmdline during generation.

Since FPC installs an chm extaction tool by default, one can simply extract it from the CHM as if it were a ZIP file:

chmls extract rtl.chm fpdoc.css

will generate fpdoc.css specified during compilation of the CHM.

The file in the docs dir is there so they can copy it. It will never be used directly. Anyway, it's all moot now, I will let fpdoc generate the file.

I assume you mean you will embed fpdoc.css and use it by default, but cmdline params will override it?

Thinking about it, I will change fpdoc so it does not need the file installed, but generates it if not present, as Graeme suggested. That will be far easier, and causes less headaches and discussion.

If/when you are looking at fpdoc, perhaps you first might want to have a look at patch
http://bugs.freepascal.org/view.php?id=22639
first.

It touches some copyright strings for fpdoc (as well as changing some makeskel functionality).
Of course, I'd be very willing to split apart these changes as well.

Thanks,
Reinier

No need.
I applied it as-is, but it would be nice in the future to split the patch...

Michael.

Implemented it. Revision 22079.

The --css-file option is still honored.
If it is not specified, a built-in copy is written to the appropriate place.

Michael.

Reinier Olislagers wrote

> Meanwhile I think the world has evolved to other practices :-) Tell that to the people who use fpc.cfg ;)

On Unix based systems it is standard that the fpc.cfg is either located in /etc or is in your home directory as .fpc.cfg.

On Windows based systems the fpc.cfg is located in the bin directory, because this was done for a long time already, but the compiler is also capable to read the fpc.cfg from the directory given by the environment variables USERPROFILE and ALLUSERSPROFILE.

(also PPC_CONFIG_PATH will always be checked for a config file)

Regards,
Sven

does that include FPC itself?

it seems to me that folks questioning this install problem are talking specifically about fpc documenting itself and where this file needs to be for the fpc documentation to work and look proper in an out of the box installation whether that is from some sort of installation program thing or whether it is via downloading the sources from SVN and building them with the make system...

the task of placing it correctly for one's own projects is another matter completely...

Please, re-read the thread. The "folks questioning this install problem" have explicitly been mentioning the use for documentation generation using the fpdoc tool, not issues with reading FPC docs in HTML format (which do include the file, but not all fpdoc users need to have FPC docs installed or use their HTML version plus they wouldn't know that they should refer to the docs directory for the CSS file when invoking fpdoc even if it is there for the HTML documentation reading).

Tomas

Thanks a lot Michael!

I am perhaps doing something wrong when testing it?

FPC x86 windows r22081
Getting a baseline: this one
C:\Development\fpctrunk\bin\i386-win32>fpdoc --package=fcl --input=C:\Development\fpctrunk\packages\paszlib\src\zipper.pp --descr=D:\Reinier\Documents\SourceCode\fpc_laz_patch_playground\docs\paszlib.xml --format=chm --css-file=C:\Development\fpctrunk\utils\fpdoc\fpdoc.css --output=d:\cop\CSSSpecified.chm
gives a chm with a blue bar with index and #fcl on top chmls list d:\cop\CSSSpecified.chm | grep -i css
shows there is an fpdoc.css in the chm, as expected.

IIUC, at least one of these should use the embedded fpdoc.css, but neither does (no blue bar on top, no fpdoc.css found in the chm): C:\Development\fpctrunk\bin\i386-win32>fpdoc --package=fcl --input=C:\Development\fpctrunk\packages\paszlib\src\zipper.pp --descr=D:\Reinier\Documents\SourceCode\fpc_laz_patch_playground\docs\paszlib.xml --format=chm --css-file= --output=d:\cop\CSSEmpty.chm chmls list d:\cop\CSSEmpty.chm | grep -i css
indeed shows no fpdoc.css in the chm

C:\Development\fpctrunk\bin\i386-win32>fpdoc --package=fcl --input=C:\Development\fpctrunk\packages\paszlib\src\zipper.pp --descr=D:\Reinier\Documents\SourceCode\fpc_laz_patch_playground\docs\paszlib.xml --format=chm --output=d:\cop\CSSNotSpecified.chm
chmls list d:\cop\CSSNotSpecified.chm | grep -i css indeed shows no fpdoc.css in the chm