[Pkg-pascal-devel] pasdoc and timestamps

[Michalis Kamburelis]

Paul Gevers wrote:
> Hi Michalis,
> 
> Maybe you have heard of the Reproducible Build project [1]. As I believe
> you are also doing Continuous Integration of your projects, you might be
> interesting to help Debian with Pasdoc. Pasdoc currently by default adds
> timestamps to the documentation, which causes e.g. castle-game-engine to
> not be build reproducible by default. Now I can of course fix cge to not
> add timestamps, but it would be cool if pasdoc changes its default
> behavior to not add timestamps and only do that when asked for.
> 
> What do you think?
> 

Right now, pasdoc has an option --exclude-generator to exclude *all* the
information about generation, including things making the build
non-reproducible. This turns off the generation of:

1. pasdoc name (and www page)
2. pasdoc version number
3. document creation time
4. also, in the pasdoc output (stdout/stderr), build duration time (this
allows to even compare outputs, to check are warnings/errors the same).

(grep sources for NoGeneratorInfo for this.)

I don't think we want to just make "--exclude-generator the default
behavior", as this would remove mentions of PasDoc (point 1. above) from
the generated output. And these mentions are nice, they provide some
exposure of the project, and they are very non-intrusive --- as far as I
know, most people don't mind them. Also, excluding 2. is possibly not
interesting anyway? (Because when PasDoc version changes, it's output
will *probably* change anyway because of various improvements/changes
around the place.)

So, the proposition:
- make the creation time (point 3.) be excluded by default, and include
it only when --include-creation-time is specified.
- move the build duration time to "verbose" log level, so that it's not
shown by default, completely independent from the
--exclude.../--include... options.
- make --exclude-generator just turn off visibility of 1. and 2. (pasdoc
name and version) from the output.

Summary:
- --exclude-generator (exclude 1. and 2.) and --include-creation-time
(include 3.) would be orthogonal, so there's no question about "what is
the priority".
- default would be to show pasdoc name and version, but not creation
time --- is this useful?

Michalis