Nice!

Parsing out the revision number, date, and committer can be done in the Perl call, and passed as separate parameters. That would simplify the stylesheets and also make them less fragile. Right now, they depend on magic string length constants that do not indicate what they mean.

Perl can do the sort and tail itself, parse out the version, date, and committer, and return a string with those three parameter settings. I will write that, if desired.

Kind of went the opposite direction in terms of perl, I find the result to be quite readable though.

@hrs
Can you please suggest how to accomplish what this is doing (and I think what this is doing is extremely important, I was embarrassed when I showed the Porters Handbook to someone and it said that it was last updated two years ago) in a style sheet in a way that is less complex (this is not about parsing XML, but about getting an SVN keyword out of a group of text files, which is super stable, compatible and will work even on files that are part of the documentation, even if they're not XML)?

@hrs (edited, so it makes more sense)

The reason why this is not parsing XML as such is:

1. The user puts $FreeBSD$ anywhere in the file, usually somewhere in an XML comment at the top of the file.
2. subversion replaces this string, not caring about the document structure or if this is XML at all.
3. On build, make extracts that information the exact same way it was created by subversion, i.e. not caring about the document structure or if this is XML, and passes it into the document generator.

So, besides the fact that this approach is very lean and easy to understand, I also think it's the right thing to do given how this information is created (it might be more accurate to use subversion, but afaik the build process shouldn't depend on this, so it's not an option).

In D5754#123995, @grembo wrote:

So, besides the fact that this approach is very lean and easy to understand, I also think it's the right thing to do given how this information is created (it might be more accurate to use subversion, but afaik the build process shouldn't depend on this, so it's not an option).

Agreed. svn info can get the information, but then the build only works if Subversion is present and the doc tree is a working copy, neither of which can be assumed.

As Michael says, source files are not necessarily XML, and I think that use of version strings in the XML files is not consistent.

We could (and maybe should) also check the latest dates of other types of files that affect the rendered output, like illustrations. Those do not always have easily accessible version strings, though.

Committed in r48778:

Replace revision and publication date in generated documentation with
the actual date of last update. This fixes the problems with misleading
"last update" dates that only reflect the change in a single
rarely-changed file. Note that hrs had reservations about doing this in
the Makefile rather than with a stylesheet. However, not all our source
files are XML. For now, this change works, and can be replaced by a
more elegant solution later. We should also consider checking dates on
other files that affect the content or appearance of documents, like
images.