FWIW, here is a simple script which we use on the Javadoc team to remove
timestamps from docs. Run the script giving a single argument of a
directory containing html files to be "un-stamped".
For JDK API docs, we not only have to strip out the javadoc timestamps;
we also have to strip out the timestamps that appear in some of the
generated source files.
--------------------------8<---------------------------------
#!/bin/sh
# Remove timestamps from html files generated by javadoc.
# This includes timestamps generated by javadoc itself,
# and timestamps propogated from the javadoc comments.
for file in $(find $1 -name \*.html | xargs -n 1 grep
--files-with-matches "Generated by javadoc" ) ; do
sed --in-place \
-e 's/\(-- Generated by javadoc \).*\( --\)/\1(removed)\2/' \
-e 's/\(<meta name="date" content="\).*\(">\)/\1(removed)\2/' \
-e
's/\(Monday\|Tuesday\|Wednesday\|Thursday\|Friday\|Saturday\|Sunday\),
[A-Z][a-z]* [0-9][0-9]*, [12][0-9]* [0-9][0-9:]* \(AM\|PM\)
PDT/(removed)/' \
$file
done
-------------------------->8---------------------------------
FWIW, one issue that has come to light (and which we are working to fix)
is that in some situations, the order of entries within some of the
generated files is not deterministic/consistent.
-- Jon
On 07/24/2014 09:47 AM, Martin Buchholz wrote:
On Thu, Jul 24, 2014 at 8:28 AM, Benedikt Morbach <[email protected]
<mailto:[email protected]>> wrote:
> At Google we also strive for repeatable builds. We find timestamps
> embedded in jar files to be the biggest problem.
>
> Timestamps are useful for users checking up-to-dateness via the
"Show
> Source" action in a web browser.
Isn't it more useful to just have the version that the docs were
built for displayed?
That would be easier to find than having to look at comments in
the html source and
"These are the docs for version 1.2" seems more useful than "these
docs were built on 2014/07/01"
It depends. My own most-read javadoc is
http://gee.cs.oswego.edu/dl/jsr166/dist/docs/java/util/concurrent/CompletableFuture.html
and that has no release version associated with it. The value of the
timestamps may be small, but it is definitely non-zero.
It depends on the use case. For Linux operating system deployments,
it makes a lot of sense to drop the timestamp, especially because the
user will have a good chance of being able to observe the timestamps
of the underlying files.
But I think the Right Thing to do is to add the extra tooling to
compare javadoc-generated html files and ignore the timestamp
differences, and that should be less total work than persuading all
the javadoc generating tools not to produce them.
How do you handle jar/zip files?
