From: Brian Gernhardt <benji@silverinsanity.com>
Date: Sat, 24 Mar 2007 14:26:30 GMT
Subject: Re: [PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf
Message-ID: <382A0F82-0CD9-43B8-8F91-4CAD6DBFF890@silverinsanity.com>
In-Reply-To: <20070324120421.GL8017@planck.djpig.de>


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