[m-rev.] for review: version identifiers in documentation

[Simon Taylor]

Estimated hours taken: 1.5
Branches: main, release

Put version identifiers in the documentation.

doc/Mmakefile:
	Preprocess the `.texi' files to produce `.texi_pp' files.
	The `.texi_pp' files contain the contents of the `.texi'
	files with the string VERSION replaced by the value
	of $(VERSION), which is taken from the file VERSION
	in the top-level `mercury' directory.

	The rules to automatically generate the `.texi' files
	for the library reference manual now generate `.texi_pp' files.
	This makes it clearer that they are not to be edited.

	Fix a bug which was causing the library documentation on the
	web page to be out of date -- library_1.html needs to depend
	on library-chapters.texi_pp.

doc/faq.texi:
doc/library.texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
	Add version information.

	Put a proper heading at the top of mercury_ref.info.

doc/mercury.html.in:
doc/mercury.info.in:
doc/mercury.html:
doc/mercury.info:
	Add `.in' files which are preprocessed as for the `.texi' files.
	Remove the old unpreprocessed versions.

doc/texi2html:
	Allow `.texi_pp' as a suffix for the texinfo files to process.

w3/information/Makefile
	Create the VERSION file, and include it in the generated
	Mmake.common.

Index: doc/Mmakefile
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/Mmakefile,v
retrieving revision 1.27
diff -u -u -r1.27 Mmakefile
--- doc/Mmakefile	17 Aug 2001 10:15:44 -0000	1.27
+++ doc/Mmakefile	3 Oct 2001 09:55:15 -0000
@@ -50,21 +50,21 @@
 
 #-----------------------------------------------------------------------------#
 
-.SUFFIXES: .texi .dvi .ps .text
+.SUFFIXES: .in .texi_pp .texi .dvi .ps .text
 
-%.dvi: %.texi
+%.dvi: %.texi_pp
 	$(TEXI2DVI) $< > $*.dvi_log
 
 %.ps: %.dvi
 	$(DVIPS) -f < $< > $@
 
-%.text: %.texi
+%.text: %.texi_pp
 	$(MAKEINFO) --no-headers -o $@ $<
 
-%.html %_toc.html: %.texi
+%.html %_toc.html: %.texi_pp
 	$(TEXI2HTML) $<
 
-%_1.html: %.texi
+%_1.html: %.texi_pp
 	$(TEXI2HTML_SPLIT) $<
 
 %.1: ../scripts/% make_manpage
@@ -73,6 +73,17 @@
 	MERCURY_MKINIT=../util/mkinit \
 	./make_manpage $< > $@
 
+SED_CMD = sed -e "s/VERSION/$(VERSION)/g" < $< > $@
+
+%.texi_pp: %.texi
+	$(SED_CMD)
+
+mercury.html: mercury.html.in
+	$(SED_CMD)
+
+mercury.info: mercury.info.in
+	$(SED_CMD)
+
 #-----------------------------------------------------------------------------#
 
 	# Currently `mmake all' does not build the PostScript or plain-text
@@ -132,15 +143,15 @@
 
 #-----------------------------------------------------------------------------#
 
-mercury_user_guide.info: user_guide.texi
+mercury_user_guide.info: user_guide.texi_pp
 	$(MAKEINFO) $<
-mercury_ref.info: reference_manual.texi
+mercury_ref.info: reference_manual.texi_pp
 	$(MAKEINFO) $<
-mercury_trans_guide.info: transition_guide.texi
+mercury_trans_guide.info: transition_guide.texi_pp
 	$(MAKEINFO) $<
-mercury_faq.info: faq.texi
+mercury_faq.info: faq.texi_pp
 	$(MAKEINFO) $<
-mercury_library.info: library.texi
+mercury_library.info: library.texi_pp
 	$(MAKEINFO) $<
 
 #-----------------------------------------------------------------------------#
@@ -166,8 +177,8 @@
 # Note that some modules are just implementation details of the library,
 # so they are not documented.
 
-library-menu.texi: $(LIBRARY_DIR)/*.m
-	{								\
+library-menu.texi_pp: $(LIBRARY_DIR)/*.m
+	{ 								\
 	echo "";							\
 	for filename in $(LIBRARY_DIR)/*.m; do				\
 		case $$filename in					\
@@ -184,9 +195,9 @@
 				;;					\
 		esac;							\
 	done;								\
-	} > library-menu.texi
+	} > library-menu.texi_pp
 
-library-chapters.texi: $(LIBRARY_DIR)/[a-z]*.m
+library-chapters.texi_pp: $(LIBRARY_DIR)/[a-z]*.m
 	for filename in $(LIBRARY_DIR)/[a-z]*.m; do 			\
 		case $$filename in					\
 			$(LIBRARY_DIR)/private_builtin.m)		\
@@ -213,10 +224,10 @@
 				echo ""; 				\
 				;;					\
 		esac;							\
-	done > library-chapters.texi
+	done > library-chapters.texi_pp
 
-library.dvi library_toc.html mercury_library.info: \
-	library-menu.texi library-chapters.texi
+library.dvi library_toc.html library_1.html mercury_library.info: \
+	library-menu.texi_pp library-chapters.texi_pp
 
 #-----------------------------------------------------------------------------#
 
@@ -304,7 +315,7 @@
 # INSTALL_WEBPAGE_DIR).
 
 .PHONY: install_webpage
-install_webpage: library-chapters.texi split_html ps install_dirs
+install_webpage: library-chapters.texi_pp split_html ps install_dirs
 	cp *.ps $(INSTALL_WEBPAGE_DIR)
 	for file in $(INSTALL_WEBPAGE_DIR)/*.ps ; do \
 		gzip -f -9 $$file ; \
@@ -321,7 +332,7 @@
 
 .PHONY: clean_texi
 clean_texi:
-	rm -f library-menu.texi library-chapters.texi
+	rm -f library-menu.texi library-chapters.texi *.texi_pp
 
 realclean_local: realclean_texi realclean_manpages
 
Index: doc/faq.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/faq.texi,v
retrieving revision 1.24
diff -u -u -r1.24 faq.texi
--- doc/faq.texi	4 Jun 2001 06:31:34 -0000	1.24
+++ doc/faq.texi	3 Oct 2001 09:41:17 -0000
@@ -22,7 +22,7 @@
 @finalout
 @setchapternewpage off
 @ifinfo
-This file is the Mercury Frequently Asked Questions list.
+This file is the Mercury Frequently Asked Questions List, version VERSION.
 It contains a list of frequently asked questions about Mercury, with answers.
 
 Copyright (C) 1995-1997 The University of Melbourne.
@@ -48,7 +48,8 @@
 @end ifinfo
 
 @titlepage
- at title The Mercury Frequently Asked Questions list
+ at title The Mercury Frequently Asked Questions List
+ at subtitle Version VERSION
 @author Fergus Henderson
 @author Thomas Conway
 @author Zoltan Somogyi
@@ -73,7 +74,7 @@
 
 @ifinfo
 @node Top,,, (mercury)
- at top The Mercury Frequently Asked Questions list
+ at top The Mercury Frequently Asked Questions List, version VERSION
 @menu
 * Programming::     Common programming errors.
 * Unimplemented::   Problems caused by unimplemented Mercury features.
Index: doc/library.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/library.texi,v
retrieving revision 1.17
diff -u -u -r1.17 library.texi
--- doc/library.texi	4 Jun 2001 06:31:34 -0000	1.17
+++ doc/library.texi	3 Oct 2001 10:02:22 -0000
@@ -13,7 +13,7 @@
 @finalout
 @setchapternewpage off
 @ifinfo
-This file documents the Mercury standard library.
+This file documents the Mercury standard library, version VERSION.
 
 Copyright (C) 1995-1999 The University of Melbourne.
 
@@ -39,6 +39,7 @@
 
 @titlepage
 @title The Mercury Library Reference Manual
+ at subtitle Version VERSION
 @c @author Fergus Henderson
 @c @author Thomas Conway
 @c @author Zoltan Somogyi
@@ -64,7 +65,7 @@
 
 @ifinfo
 @node Top,,, (mercury)
- at top Mercury Library Reference Manual
+ at top Mercury Library Reference Manual, version VERSION
 @end ifinfo
 
 The Mercury standard library contains a variety of modules which we
@@ -101,7 +102,7 @@
 ``high''.
 
 @menu
- at include library-menu.texi
+ at include library-menu.texi_pp
 @end menu
- at include library-chapters.texi
+ at include library-chapters.texi_pp
 @bye
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.217
diff -u -u -r1.217 reference_manual.texi
--- doc/reference_manual.texi	25 Sep 2001 09:36:58 -0000	1.217
+++ doc/reference_manual.texi	3 Oct 2001 09:41:17 -0000
@@ -16,7 +16,7 @@
 @finalout
 @setchapternewpage off
 @ifinfo
-This file documents the Mercury programming language.
+This file documents the Mercury programming language, version VERSION.
 
 Copyright (C) 1995-2001 The University of Melbourne.
 
@@ -42,6 +42,7 @@
 
 @titlepage
 @title The Mercury Language Reference Manual
+ at subtitle Version VERSION
 @author Fergus Henderson
 @author Thomas Conway
 @author Zoltan Somogyi
@@ -72,7 +73,7 @@
 
 @ifinfo
 @node Top,,, (mercury)
- at top
+ at top The Mercury Language Reference Manual, version VERSION
 @end ifinfo
 @c XXX Move to after Determinism
 @c * Assertions::        Assertion declarations allow you to declare laws
Index: doc/texi2html
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/texi2html,v
retrieving revision 1.3
diff -u -u -r1.3 texi2html
--- doc/texi2html	11 Sep 1995 11:01:01 -0000	1.3
+++ doc/texi2html	3 Oct 2001 10:11:38 -0000
@@ -315,7 +315,7 @@
     $docu_dir = '.';
     $docu_name = $docu;
 }
-$docu_name =~ s/\.te?x(i|info)?$//;	# basename of the document
+$docu_name =~ s/\.te?x(i|info|i_pp)?$//;# basename of the document
 
 $docu_toc = $docu_doc = $docu_foot = $docu_name;
 $docu_toc  .= '_toc.html';		# document's table of contents
Index: doc/transition_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/transition_guide.texi,v
retrieving revision 1.36
diff -u -u -r1.36 transition_guide.texi
--- doc/transition_guide.texi	4 Jun 2001 06:31:36 -0000	1.36
+++ doc/transition_guide.texi	3 Oct 2001 09:41:17 -0000
@@ -39,6 +39,7 @@
 
 @titlepage
 @title The Prolog to Mercury transition guide
+ at subtitle Version VERSION
 @author Thomas Conway
 @author Zoltan Somogyi
 @author Fergus Henderson
@@ -63,7 +64,7 @@
 
 @ifinfo
 @node Top,,, (mercury)
- at top The Prolog to Mercury transition guide
+ at top The Prolog to Mercury Transition Guide, version VERSION
 
 This guide gives some advice about
 translating Prolog programs into Mercury.
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.272
diff -u -u -r1.272 user_guide.texi
--- doc/user_guide.texi	12 Aug 2001 11:05:45 -0000	1.272
+++ doc/user_guide.texi	3 Oct 2001 09:41:17 -0000
@@ -43,7 +43,7 @@
 @c ----------------------------------------------------------------------------
 
 @ifinfo
-This file documents the Mercury implementation.
+This file documents the Mercury implementation, version VERSION.
 
 Copyright (C) 1995-2001 The University of Melbourne.
 
@@ -69,6 +69,7 @@
 
 @titlepage
 @title The Mercury User's Guide
+ at subtitle Version VERSION
 @author Fergus Henderson
 @author Thomas Conway
 @author Zoltan Somogyi
@@ -100,7 +101,7 @@
 
 @ifinfo
 @node Top,,, (mercury)
- at top The Mercury User's Guide
+ at top The Mercury User's Guide, version VERSION
 
 This guide describes the compilation environment of Mercury ---
 how to build and debug Mercury programs.
Index: w3/information/Makefile
===================================================================
RCS file: /home/mercury1/repository/w3/information/Makefile,v
retrieving revision 1.17
diff -u -u -r1.17 Makefile
--- w3/information/Makefile	3 Aug 2001 03:36:33 -0000	1.17
+++ w3/information/Makefile	3 Oct 2001 10:21:53 -0000
@@ -39,8 +39,10 @@
 	echo "PERL=perl"  >> Mmake.common
 	echo "INFO=info"  >> Mmake.common
 	echo "DVIPS=dvips"  >> Mmake.common
+	echo 'include $$(MERCURY_DIR)/VERSION'  >> Mmake.common
+	echo "VERSION=rotd-`date '+%Y-%m-%d'`" > VERSION
 	(cd notes; mmake MERCURY_DIR=.. )
-	(cd mercury-doc; mmake library-chapters.texi split_html ps)
+	(cd mercury-doc; mmake split_html ps)
 	$(CP) notes/*.text doc
 	$(CP) mercury-doc/*.html notes/*.html doc
 	$(CP) mercury-doc/*.ps doc
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------