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

From: Brian Gernhardt <benji@silverinsanity.com>
Date: Mar 24, 2007, 14:26 UTC
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:

Show 18 quoted lines

> 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