Now we use Subversion, it seems excessive to have an individual $Id$

line for every single .but file at the bottom of each page of the
HTML PuTTY docs. However, we can't _always_ replace that with a
single SVN revision, because there isn't always one available (SVN
still allows mixed working copies in which some files are
deliberately checked out against a different revision).

Hence, here's a mechanism for doing better. It uses `svnversion .'
to determine _whether_ a single revision number adequately describes
the current directory, and replaces all the version IDs with that if
so. If it can't do that, it uses the version IDs as before.

Also, this allows an explicit version string to be passed on the
make command line which will override _both_ these possibilities, so
that release documentation can be clearly labelled with the release
version number.

[originally from svn r4804]

CHECKLST.txt

@@ -119,7 +119,10 @@ of the tag.
     + Make sure Owen has kept the Alpha release link maps somewhere
       useful.
 
- - Run Halibut to build the docs.
+ - Run Halibut to build the docs. Define VERSION on the make command
+   line to override the version strings, since Subversion revision
+   numbers are less meaningful on a tag.
+    + make -C doc VERSION="PuTTY release 0.XX"
 
  - Build the binary archives putty.zip (one for each architecture):
    each one just contains all the .exe files except PuTTYtel, and

doc/Makefile

@@ -1,14 +1,46 @@
+all: man index.html
+
+# Decide on the versionid policy.
+#
+# If the user has passed in $(VERSION) on the command line (`make
+# VERSION="Release 0.56"'), we use that as an explicit version
+# string. Otherwise, we use `svnversion' to examine the checked-out
+# documentation source, and if that returns a single revision
+# number then we invent a version string reflecting just that
+# number. Failing _that_, we resort to versionids.but which shows a
+# $Id for each individual file.
+#
+# So here, we define VERSION using svnversion if it isn't already
+# defined ...
+ifndef VERSION
+SVNVERSION=$(shell test -d .svn && svnversion .)
+BADCHARS=$(findstring :,$(SVNVERSION))$(findstring S,$(SVNVERSION))
+ifeq ($(BADCHARS),)
+ifneq ($(SVNVERSION),)
+VERSION=Built from revision $(patsubst M,,$(SVNVERSION))
+endif
+endif
+endif
+# ... and now, we condition our build behaviour on whether or not
+# VERSION _is_ defined.
+ifdef VERSION
+VERSIONIDS=vstr
+vstr.but: FORCE
+	echo \\versionid $(VERSION) > vstr.but
+FORCE:;
+else
+VERSIONIDS=vids
+endif
+
 CHAPTERS := $(SITE) blurb intro gs using config pscp psftp plink pubkey
 CHAPTERS += pageant errors faq feedback licence
-CHAPTERS += index
+CHAPTERS += index $(VERSIONIDS)
 
 INPUTS = $(patsubst %,%.but,$(CHAPTERS))
 
 # This is temporary. Hack it locally or something.
 HALIBUT = $(HOME)/src/halibut/build/halibut
 
-all: man index.html
-
 index.html: $(INPUTS)
 	$(HALIBUT) --text --html --winhelp $(INPUTS)
 
@@ -25,4 +57,4 @@ puttytel.1: man-ptel.but mancfg.but; $(MKMAN)
 pterm.1: man-pter.but mancfg.but; $(MKMAN)
 
 clean:
-	rm -f *.html *.txt *.hlp *.cnt *.1
+	rm -f *.html *.txt *.hlp *.cnt *.1 vstr.but

doc/blurb.but

@@ -1,3 +1,5 @@
+\define{versionidblurb} \versionid $Id$
+
 \title PuTTY User Manual
 
 \cfg{xhtml-leaf-level}{1}
@@ -26,5 +28,3 @@ Unix-specific documentation that currently exists is the man pages.
 \copyright This manual is copyright 2001-2004 Simon Tatham. All
 rights reserved. You may distribute this documentation under the MIT
 licence. See \k{licence} for the licence text in full.
-
-\versionid $Id: blurb.but,v 1.13 2004/10/24 22:57:36 jacob Exp $

doc/config.but

@@ -1,4 +1,4 @@
-\versionid $Id: config.but,v 1.97 2004/11/09 17:57:32 simon Exp $
+\define{versionidconfig} \versionid $Id$
 
 \C{config} Configuring PuTTY
 

doc/errors.but

@@ -1,4 +1,4 @@
-\versionid $Id: errors.but,v 1.10 2004/09/27 00:23:19 jacob Exp $
+\define{versioniderrors} \versionid $Id$
 
 \C{errors} Common error messages
 

doc/faq.but

@@ -1,4 +1,4 @@
-\versionid $Id$
+\define{versionidfaq} \versionid $Id$
 
 \A{faq} PuTTY FAQ
 

doc/feedback.but

@@ -1,4 +1,4 @@
-\versionid $Id: feedback.but,v 1.20 2004/11/15 15:57:28 jacob Exp $
+\define{versionidfeedback} \versionid $Id$
 
 \A{feedback} Feedback and bug reporting
 

doc/gs.but

@@ -1,4 +1,4 @@
-\versionid $Id: gs.but,v 1.9 2004/10/24 16:24:58 jacob Exp $
+\define{versionidgs} \versionid $Id$
 
 \C{gs} Getting started with PuTTY
 

doc/intro.but

@@ -1,4 +1,4 @@
-\versionid $Id: intro.but,v 1.7 2004/10/24 15:58:31 jacob Exp $
+\define{versionidintro} \versionid $Id$
 
 \C{intro} Introduction to PuTTY
 

doc/licence.but

@@ -1,4 +1,4 @@
-\versionid $Id: licence.but,v 1.7 2004/08/30 13:23:23 simon Exp $
+\define{versionidlicence} \versionid $Id$
 
 \A{licence} PuTTY Licence
 

doc/pageant.but

@@ -1,4 +1,4 @@
-\versionid $Id: pageant.but,v 1.11 2004/05/22 11:09:31 simon Exp $
+\define{versionidpageant} \versionid $Id$
 
 \C{pageant} Using Pageant for authentication
 

doc/plink.but

@@ -1,4 +1,4 @@
-\versionid $Id: plink.but,v 1.26 2004/10/15 23:32:01 jacob Exp $
+\define{versionidplink} \versionid $Id$
 
 \C{plink} Using the command-line connection tool Plink
 

doc/pscp.but

@@ -1,4 +1,4 @@
-\versionid $Id: pscp.but,v 1.29 2004/08/03 13:23:48 jacob Exp $
+\define{versionidpscp} \versionid $Id$
 
 \#FIXME: Need examples
 

doc/psftp.but

@@ -1,4 +1,4 @@
-\versionid $Id: psftp.but,v 1.7 2004/10/24 18:30:10 jacob Exp $
+\define{versionidpsftp} \versionid $Id$
 
 \C{psftp} Using PSFTP to transfer files securely
 

doc/pubkey.but

@@ -1,4 +1,4 @@
-\versionid $Id: pubkey.but,v 1.22 2004/05/06 11:27:58 simon Exp $
+\define{versionidpubkey} \versionid $Id$
 
 \C{pubkey} Using public keys for SSH authentication
 

doc/using.but

@@ -1,4 +1,4 @@
-\versionid $Id: using.but,v 1.37 2004/10/24 16:48:43 jacob Exp $
+\define{versionidusing} \versionid $Id$
 
 \C{using} Using PuTTY
 

doc/vids.but

@@ -0,0 +1,30 @@
+\# Invoke the versionid macros defined in all the other manual
+\# chapter files.
+
+\versionidblurb
+
+\versionidintro
+
+\versionidgs
+
+\versionidusing
+
+\versionidconfig
+
+\versionidpscp
+
+\versionidpsftp
+
+\versionidplink
+
+\versionidpubkey
+
+\versionidpageant
+
+\versioniderrors
+
+\versionidfaq
+
+\versionidfeedback
+
+\versionidlicence