cvs diff: man pages

Fergus Henderson fjh at cs.mu.oz.au
Sat Feb 8 01:06:07 AEDT 1997
Previous message: [m-dev.] cvs diff: scripts/ml.in
Next message: cvs diff: SPARC position-indepenent code
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Hi Tom,

Could you please review the following diff for me?

---------------------------------------------------------------------------

Estimated hours: 5

Add Unix-style man pages for most of the Mercury development tools.

doc/make_manpage:
	New file.  This is a shell script that converts the
	output from `foo --help' into a a man page.

doc/Mmake:
	New rules for creating and installing man pages.
	Also add some rules for installing the postscript
	and text

Mmake.common.in:
	New variables specifying the directories to install the man
	pages, postscript documentation, and text documentation.

scripts/ml.in:
scripts/c2init.in:
scripts/mmake.in:
scripts/msc.in:
	Small changes to the help messages to make them come out
	better when converted to man pages.

scripts/mgnuc.in:
	Add a `--help' option.

---------------------------------------------------------------------------

cvs diff: Diffing .
Index: c2init.in
===================================================================
RCS file: /home/staff/zs/imp/mercury/scripts/c2init.in,v
retrieving revision 1.9
diff -u -r1.9 c2init.in
--- c2init.in	1997/02/01 00:12:06	1.9
+++ c2init.in	1997/02/07 13:50:30
@@ -11,23 +11,28 @@
 # This script outputs an appropriate init.c, given the .c files.
 # Type `c2init --help' for usage message.
 #
-# Environment variables: MERCURY_MOD_LIB_DIR, MERCURY_MOD_LIB_MODS,
-# MERCURY_MKINIT.
 
-Usage="\
-Usage: c2init [options] modules ...
+# IMPORTANT: the manpage is produced automatically from this help
+# message, so if you change the help message, don't forget to check
+# that the manpage still looks OK.
+Help="\
+Name:	c2init - Create Mercury initialization file.
+Usage:	c2init [options] modules ...
 Options: 
--l, --library
-	Don't generate a \`main()' function.
-	Instead, generate a function
-		mercury_main(int argc, char **argv, char *stack_bottom);
-	(declared in \"init.h\") that can be called from C code.
--c <n>, --max-calls <n>
-	Break up the initialization into groups of at most <n> function calls.
-	(Default value of <n> is 40.)
--w <label>, --entry-point <label>
-	Set entry point to <label>.
-	(Default value is \`mercury__io__run_0_0'.)"
+	-l, --library
+		Don't generate a \`main()' function.
+		Instead, generate a function
+			mercury_main(int argc, char **argv, char *stack_bottom);
+		(declared in \"init.h\") that can be called from C code.
+	-c <n>, --max-calls <n>
+		Break up the initialization into groups of at most <n> function
+		calls.  (Default value of <n> is 40.)
+	-w <label>, --entry-point <label>
+		Set entry point to <label>.
+		(Default value is \`mercury__io__run_0_0'.)
+Environment variables:
+	MERCURY_MOD_LIB_DIR, MERCURY_MOD_LIB_MODS, MERCURY_MKINIT.
+"
 
 MERCURY_MOD_LIB_DIR=${MERCURY_MOD_LIB_DIR=@LIBDIR@/modules}
 MERCURY_MOD_LIB_MODS=${MERCURY_MOD_LIB_MODS=$MERCURY_MOD_LIB_DIR/*}
@@ -48,12 +53,13 @@
 	-l-|--no-library)
 		library_opt=""; shift;;
 	-h|--help|"-?")
-		echo "$Usage"
+		echo "$Help"
 		exit 0;;
 	--)
 		shift; break;;
 	-*)
-		echo "$Usage" 1>&2;
+		echo "`basename $0`: invalid option \`$1'" 1>&2;
+		echo "Try \`$0 --help' for help." 1>&2;
 		exit 1;;
 	*)
 		break;;
Index: mgnuc.in
===================================================================
RCS file: /home/staff/zs/imp/mercury/scripts/mgnuc.in,v
retrieving revision 1.38
diff -u -r1.38 mgnuc.in
--- mgnuc.in	1997/01/16 18:41:44	1.38
+++ mgnuc.in	1997/02/07 14:07:10
@@ -6,36 +6,32 @@
 # Public License - see the file COPYING in the Mercury distribution.
 #---------------------------------------------------------------------------#
 #
-# MGNUC - Mercury GNU C
-#
-# Usage: mgnuc [<options>] [-- <gcc options>] files...
-# Options:
-# -v, --verbose
-#	Echo gcc command before executing it.
-# --no-ansi
-#	Don't pass -ansi.
-# --no-check
-#	Don't pass any of the -W options.
-# -s <grade>, --grade <grade>
-#	Select optimization/debug/gc options according to <grade>, which
-#	must be one of debug, none, jump, asm_jump, reg, fast, or asm_fast,
-#	or one of those with .gc appended.
-#
-# This runs gcc with all warnings enabled, except for the following
-# exceptions:
-#
-# -Wredundant-decls	causes too many complaints in system header files
-# -Wconversion		really only intended to help people using `unprotoize'
-# -Waggregate-return	not useful, IMHO
-#
-# -Wcast-align 		causes redundant warnings in memory.c
-# -pedantic		causes unsuppressable warnings about LVALUE_CAST()
-# -Wnested-externs	causes unsuppressable warnings about callentry()
-# -Wid-clash-31 	causes warnings about entry_mercury__xxx ...
-# -Wenum-clash 		is for C++ only
-# -Wunused		causes various spurious warnings
-#
-# Environment variables: MERCURY_C_INCL_DIR, MERCURY_DEFAULT_GRADE.
+# IMPORTANT: the manpage is produced automatically from this help
+# message, so if you change the help message, don't forget to check
+# that the manpage still looks OK.
+Help="\
+Name:	mgnuc - Mercury front-end to GNU C
+Usage:	mgnuc [<options>] [-- <gcc options>] files...
+Options:
+	-s <grade>, --grade <grade>
+		Select optimization/debug/gc options according to <grade>,
+		which must be one of debug, none, jump, asm_jump, reg, fast,
+		or asm_fast, or one of those with .gc and/or .prof appended.
+	-v, --verbose
+		Echo gcc command before executing it.
+	--no-ansi
+		Don't pass \`-ansi' to gcc.
+	--no-check
+		Don't enable any of gcc's warnings.
+Description:
+	This runs gcc with the appropriate options for compiling Mercury
+	programs in the specified grade.
+	Normally it invokes gcc in ANSI mode with almost all warnings enabled,
+	but this can be changed using the \`--no-ansi' or \`--no-check'
+	options.
+Environment variables:
+	MERCURY_C_INCL_DIR, MERCURY_DEFAULT_GRADE.
+"
 
 # *************************************************************************
 # *** IMPORTANT NOTE: any changes to this file may also require similar ***
@@ -59,6 +55,19 @@
 	CHECK_OPTS="
 	      -Wall -Wwrite-strings -Wpointer-arith -Wcast-qual -Wtraditional
 	      -Wshadow -Wstrict-prototypes -Wmissing-prototypes -Wno-unused"
+
+# Note: we do not enable the following gcc warnings:
+# -Wredundant-decls	causes too many complaints in system header files
+# -Wconversion		really only intended to help people using \`unprotoize'
+# -Waggregate-return	not useful, IMHO
+
+# -Wcast-align 		causes redundant warnings in memory.c
+# -pedantic		causes unsuppressable warnings about LVALUE_CAST()
+# -Wnested-externs	causes unsuppressable warnings about callentry()
+# -Wid-clash-31 		causes warnings about entry_mercury__xxx ...
+# -Wenum-clash 		is for C++ only
+# -Wunused		causes various spurious warnings
+
 	OPT_OPTS="-O2 -fomit-frame-pointer -DSPEED"
 	COMPILER=gcc
 	;;
@@ -86,6 +95,10 @@
 
 while : ; do
     case "$1" in
+	-h|--help|"-?")
+		echo "$Help"
+		exit 0
+		;;
 	--assemble)
 		assemble=true
 		shift
diff -u -r1.9 mmake.in
--- mmake.in	1996/05/25 03:42:17	1.9
+++ mmake.in	1997/02/07 13:51:14
@@ -12,37 +12,26 @@
 #
 #-----------------------------------------------------------------------------#
 
-MMAKE_MAKE=${MMAKE_MAKE=@GNU_MAKE@}
-MMAKE_DIR=${MMAKE_DIR=@LIBDIR@/mmake}
-MMAKE_VARS=${MMAKE_VARS=$MMAKE_DIR/Mmake.vars}
-MMAKE_RULES=${MMAKE_RULES=$MMAKE_DIR/Mmake.rules}
-MERCURY_INT_DIR=${MERCURY_INT_DIR=@LIBDIR@/ints}
-MERCURY_DEFAULT_GRADE=${MERCURY_DEFAULT_GRADE=@DEFAULT_GRADE@}
-
-MMAKE=$0
-verbose=false
-save_makefile=false
-
-while [ $# -gt 0 ]; do
-	case $1 in
-		-h|--help)
-#-----------------------------------------------------------------------------#
-			cat << 'EOF'
+# IMPORTANT: the manpage is produced automatically from this help
+# message, so if you change the help message, don't forget to check
+# that the manpage still looks OK.
+Help="\
+Name: mmake -- Mercury Make
 Usage: mmake [<mmake options>] [-- <make options>] <target>...
 Options:
 	-s, --save-makefile:
-		Save the generated makefile to `Mmake.makefile'.
+		Save the generated makefile to \`Mmake.makefile'.
 	-v, --verbose:
 		Print verbose progress messages.
 	-h, --help:
 		Print this usage message.
 Targets:
 	<module>.depend:
-		Make the file `<module>.dep'.  This step is required
+		Make the file \`<module>.dep'.  This step is required
 		in preparation for the targets below.
 	<module>:
 		Compile and link a Mercury program with main module
-		`<module>.m' to produce an executable.
+		\`<module>.m' to produce an executable.
 	<module>.nu:
 		Compile and link a Mercury program with NU-Prolog
 		rather than with the Mercury compiler.
@@ -57,9 +46,24 @@
 	realclean:
 		Remove all automatically-generated files: intermediate files,
 		dependency files, and executables.
-EOF
-#-----------------------------------------------------------------------------#
-			exit
+"
+
+MMAKE_MAKE=${MMAKE_MAKE=@GNU_MAKE@}
+MMAKE_DIR=${MMAKE_DIR=@LIBDIR@/mmake}
+MMAKE_VARS=${MMAKE_VARS=$MMAKE_DIR/Mmake.vars}
+MMAKE_RULES=${MMAKE_RULES=$MMAKE_DIR/Mmake.rules}
+MERCURY_INT_DIR=${MERCURY_INT_DIR=@LIBDIR@/ints}
+MERCURY_DEFAULT_GRADE=${MERCURY_DEFAULT_GRADE=@DEFAULT_GRADE@}
+
+MMAKE=$0
+verbose=false
+save_makefile=false
+
+while [ $# -gt 0 ]; do
+	case $1 in
+		-h|--help)
+			echo "$Help"
+			exit 0
 			;;
 		-s|--save-makefile)
 			save_makefile=true
Index: msc.in
===================================================================
RCS file: /home/staff/zs/imp/mercury/scripts/msc.in,v
retrieving revision 1.6
diff -u -r1.6 msc.in
--- msc.in	1997/02/05 05:58:43	1.6
+++ msc.in	1997/02/07 13:51:53
@@ -48,8 +48,11 @@
 done
 			
 if [ $# -lt 1 ] || $help; then
+	# IMPORTANT: the manpage is produced automatically from this help
+	# message, so if you change the help message, don't forget to check
+	# that the manpage still looks OK.
 	cat << 'EOF'
-MSC - Mercury SICStus Compiler.
+Name: msc - Mercury SICStus Compiler.
 Compiles Mercury programs to SICStus Prolog object code (*.ql).
 Usage: msc [<options>] file(s)
 Options:
cvs diff: Diffing .
Index: Mmake
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/Mmake,v
retrieving revision 1.23
diff -u -r1.23 Mmake
--- Mmake	1997/01/31 00:47:28	1.23
+++ Mmake	1997/02/07 13:14:10
@@ -38,10 +38,13 @@
 %_1.html: %.texi
 	$(TEXI2HTML_SPLIT) $<
 
+%.1: ../scripts/% make_manpage
+	./make_manpage $< > $@
+
 #-----------------------------------------------------------------------------#
 
 .PHONY: all
-all: info dvi html
+all: info dvi html manpages # ps text
 
 #-----------------------------------------------------------------------------#
 
@@ -68,6 +71,9 @@
 split_html: mercury.html user_guide_1.html reference_manual_1.html \
 	library_1.html faq_1.html transition_guide_1.html
 
+.PHONY: manpages
+manpages: c2init.1 mc.1 mgnuc.1 ml.1 mmake.1 msc.1 mprof.1
+
 #-----------------------------------------------------------------------------#
 
 mercury_user_guide.info: user_guide.texi
@@ -146,6 +152,22 @@
 install_dvi: dvi
 	-[ -d $(INSTALL_DVI_DIR) ] || mkdir -p $(INSTALL_DVI_DIR)
 	cp *.dvi $(INSTALL_DVI_DIR)
+
+.PHONY: install_text
+install_text: text
+	-[ -d $(INSTALL_TEXT_DIR) ] || mkdir -p $(INSTALL_TEXT_DIR)
+	cp *.txt $(INSTALL_TEXT_DIR)
+
+.PHONY: install_ps
+install_ps: ps
+	-[ -d $(INSTALL_PS_DIR) ] || mkdir -p $(INSTALL_PS_DIR)
+	cp *.ps $(INSTALL_PS_DIR)
+
+.PHONY: install_manpages
+install_manpages: manpages
+	-[ -d $(INSTALL_MAN_DIR)/man1 ] || \
+		mkdir -p $(INSTALL_MAN_DIR)/man1
+	cp *.1 $(INSTALL_MAN_DIR)/man1
 
 # The uninstall rule here only removes the info files; the others
 # are removed by the top-level uninstall rule.
cvs diff: make_manpage is a new entry, no comparison available
Index: Mmake.common.in
===================================================================
RCS file: /home/staff/zs/imp/mercury/Mmake.common.in,v
retrieving revision 1.15
diff -u -r1.15 Mmake.common.in
--- Mmake.common.in	1997/01/10 02:16:59	1.15
+++ Mmake.common.in	1997/02/07 11:55:09
@@ -27,6 +27,9 @@
 INSTALL_LIBDIR 		= $(INSTALL_PREFIX)/lib/mercury
 INSTALL_INFO_DIR 	= $(INSTALL_PREFIX)/info
 INSTALL_DVI_DIR 	= $(INSTALL_PREFIX)/lib/mercury/doc
+INSTALL_TEXT_DIR 	= $(INSTALL_PREFIX)/lib/mercury/doc
+INSTALL_PS_DIR 		= $(INSTALL_PREFIX)/lib/mercury/doc
+INSTALL_MAN_DIR 	= $(INSTALL_PREFIX)/man
 INSTALL_HTML_DIR 	= $(INSTALL_PREFIX)/lib/mercury/html
 
 # Specify the Mercury compiler to use for bootstrapping
-----------------------------------------------------------------------------
New file: make_manpage
-----------------------------------------------------------------------------
#!/bin/sh
#
# make_manpage: create Unix man page from help message.
#
# Usage: make_manpage <program>
#
# This file takes the output of `<program> --help'
# and turns it into a Unix-style man page by
# massaging it a bit and inserting some extra stuff that is
# the same for all the Mercury man pages.

# Section headings must match /[A-Za-z ]*:/.
# We insert the `.SH' command for them,
# convert them to uppercase, and replace "USAGE" with "SYNOPSIS".

# Option headings start with a tab and then a `-'.
# We put them in bold, and indent them differently.

program="$1"
name="`basename $program `"
quote="'"

manpage="`$program --help 2>&1 \
	| sed	\
		-e '/^[A-Za-z ]*:[ 	]/s//.SH &\\
/'			\
		-e '/^[A-Za-z ]*:/s//.SH &\\
/'			\
		-e '/^	-/s/^	.*$/	.Ve\\
.B\\
.Vb 1\\
\\\\\\& &\\
.Ve\\
.Vb 2/' 					\
		-e 's/\\\\& 	/\\\\\\& /' \
		-e 's/^		/	\\\\\\&	/g' 	\
		-e 's/^	//' \
	| sed	\
		-e '/^.SH [A-Za-z ]*:/y/\
abcdefghijklmnopqrstuvwxyz:/\
ABCDEFGHIJKLMNOPQRSTUVWXYZ /' \
		-e 's/^.SH USAGE/.SH SYNOPSYS/' \
	`"
uppername="$name"

first_half="`echo \"$manpage\" | sed '/^.SH OPTIONS/,$d'`"
last_half="`echo \"$manpage\" | sed -n '/^.SH OPTIONS/,$p'`"

cat <<EOF
.de Vb
.nf
.ne \\\$1
..
.de Ve

.fi
..
.TH $uppername 1 "`date`" "" "Mercury Programmer's Manual"
.AT 3
.Vb 2
$first_half
.fi
.SH NOTES
.I $name
is one of the development tools
that are part of the Mercury distribution.
.PP
This manual page is limited to a brief summary.
For further information see the Mercury User's Guide.
.Vb 2
$last_half
.fi
.SH AUTHORS
The Mercury team.
.P
See <http://www.cs.mu.oz.au/mercury/people.html>.
.SH COPYRIGHT
This program and its documentation are copyright by the University of Melbourne.
They may be copied only under the terms of the GNU General Public License \-
see the file COPYING in the Mercury distribution.
.SH "SEE ALSO"
<http://www.cs.mu.oz.au/mercury/doc>
.P
The Mercury User's Guide.
.P
The GNU General Public License.
.ex
EOF

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.
Previous message: [m-dev.] cvs diff: scripts/ml.in
Next message: cvs diff: SPARC position-indepenent code
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the developers mailing list