Re: [PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

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:

quoted

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