On Mar 24, 2007, at 8:04 AM, Frank Lichtenheld wrote:
On Fri, Mar 23, 2007 at 02:53:58PM -0700, Junio C Hamano wrote:
While this is attractive to some degree, *I* am grumpy. Doesn't
this patch make html and man branches update all files _every_
time any small change is made to some documentation?
Not with my patch; which is a bug in the patch though because
asciidoc.conf should really depend on GIT-VERSION-FILE.
Another possibility would be to replace the @@GIT_VERSION@@ in the
man pages
themself and not in the asciidoc.conf. This would mean perhaps
slightly
bigger changes to the build system, but running sed on all the
files is of
course a lot faster than regenerating them with asciidoc.
What do you think?
I think that any change that causes the documentation to be rebuilt
without any change in the documentation is a horrible horrible idea.
The asciidoc+xmlto/xsltproc chain is noticeably slow, and I don't
think that having the version number is important enough to cause a
rebuild. Using sed is definitely better than doing a rebuild from
the start at the cost of a fair amount of complexity (and extra
files, but that's fairly negligible).
I'm not convinced of the need to have a version in every doc file,
though. The only use I can think of is to avoid version skew between
the documentation and the programs, and that's easily solved by
always building and installing them together. Adding a version to
just the main git man file might not be a bad mid-point though to
make that skew easier to detect without having to rebuild *everything*.
~~ Brian
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html