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.

git-svn-id: svn://svn.tartarus.org/sgt/putty@4804 cda61777-01e9-0310-a592-d414129be87e

diff --git a/CHECKLST.txt b/CHECKLST.txt
index 2be089e..5c6d2cf 100644 (file)
--- a/CHECKLST.txt
+++ b/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

diff --git a/doc/Makefile b/doc/Makefile
index 6820f93..eb472d9 100644 (file)
--- a/doc/Makefile
+++ b/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

diff --git a/doc/blurb.but b/doc/blurb.but
index cb0722e..2c2b19b 100644 (file)
--- a/doc/blurb.but
+++ b/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 $

diff --git a/doc/config.but b/doc/config.but
index 59a551f..1dacb51 100644 (file)
--- a/doc/config.but
+++ b/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
 

diff --git a/doc/errors.but b/doc/errors.but
index 66579ef..c5f8043 100644 (file)
--- a/doc/errors.but
+++ b/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
 

diff --git a/doc/faq.but b/doc/faq.but
index fea60ff..52f7c03 100644 (file)
--- a/doc/faq.but
+++ b/doc/faq.but
@@ -1,4 +1,4 @@
-\versionid $Id$
+\define{versionidfaq} \versionid $Id$
 
 \A{faq} PuTTY FAQ
 

diff --git a/doc/feedback.but b/doc/feedback.but
index fadc007..b0b1d65 100644 (file)
--- a/doc/feedback.but
+++ b/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
 

diff --git a/doc/gs.but b/doc/gs.but
index 043d65f..2660723 100644 (file)
--- a/doc/gs.but
+++ b/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
 

diff --git a/doc/intro.but b/doc/intro.but
index aab1504..ab9b04e 100644 (file)
--- a/doc/intro.but
+++ b/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
 

diff --git a/doc/licence.but b/doc/licence.but
index 7636809..8a76e5f 100644 (file)
--- a/doc/licence.but
+++ b/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
 

diff --git a/doc/pageant.but b/doc/pageant.but
index d08563e..7e8a198 100644 (file)
--- a/doc/pageant.but
+++ b/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
 

diff --git a/doc/plink.but b/doc/plink.but
index e4cb0bc..abcf42f 100644 (file)
--- a/doc/plink.but
+++ b/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
 

diff --git a/doc/pscp.but b/doc/pscp.but
index 9154fbd..e5f1778 100644 (file)
--- a/doc/pscp.but
+++ b/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
 

diff --git a/doc/psftp.but b/doc/psftp.but
index d18b1e7..0b9f070 100644 (file)
--- a/doc/psftp.but
+++ b/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
 

diff --git a/doc/pubkey.but b/doc/pubkey.but
index 8b9a3f9..a8b9a33 100644 (file)
--- a/doc/pubkey.but
+++ b/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
 

diff --git a/doc/using.but b/doc/using.but
index a341588..7390506 100644 (file)
--- a/doc/using.but
+++ b/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
 

diff --git a/doc/vids.but b/doc/vids.but
new file mode 100644 (file)
index 0000000..93d2416
--- /dev/null
+++ b/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