[3.0] RFC: generate java man pages from texi sources

Matthias Klose doko@cs.tu-berlin.de
Mon Jul 2 14:18:00 GMT 2001


This patch adds support for generation and installation of man pages
for the java tools (gcj, gcjh, jv-scan, jcf-convert, gij).

- texi2pod.pl is merged from binutils and extended to support the '-'
  in program names.

- unsure about how to handle the installation of gij.1. It's
  documented in gcc/java/gcj.1, but built in libjava. Unfortunately
  not for all targets that gcj is built for.

- gcc/configure and generated man pages are not included.

- gcj.texi: Added command options, that are output with --help.

bootstrap currently running. verified that the generated gcc man pages
are the same as with the old texi2pod.pl.


2001-07-02  Matthias Klose  <doko@debian.org>

	* texi2pod.pl: Merge changes from binutil's texi2pod.pl. allows
	generation of more than one man page from one source.
	Add '-' to set of valid chars for an identifier.

diff -b -r -u --exclude=Makefile --exclude=configure gcc-3.0/contrib/texi2pod.pl gcc-3.0.x/contrib/texi2pod.pl
--- gcc-3.0/contrib/texi2pod.pl	Fri May  4 00:01:39 2001
+++ gcc-3.0.x/contrib/texi2pod.pl	Mon Jul  2 21:50:03 2001
@@ -41,11 +41,20 @@
 	} else {
 	    $flag = shift;
 	}
+	$value=$flag;
+	$value =~ s,^[a-zA-Z0-9_-]+,,;
+	$value =~ s,.*=,,;
+	$flag =~ s,=.*$,,;
 	die "no flag specified for -D\n"
 	    unless $flag ne "";
+	# gcc's
 	die "flags may only contain letters, digits, hyphens, and underscores\n"
 	    unless $flag =~ /^[a-zA-Z0-9_-]+$/;
-	$defs{$flag} = "";
+
+	#print STDERR "FL = $flag, V = $value\n";
+	#$defs{$flag} = "";
+	$defs{$flag} = $value;
+
     } elsif (/^-/) {
 	usage();
     } else {
@@ -77,11 +86,25 @@
 
     # Look for filename and title markers.
     /^\@setfilename\s+([^.]+)/ and $fn = $1, next;
-    /^\@settitle\s+([^.]+)/ and $tl = $1, next;
+    /^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next;
+
+    # Identify a man title but keep only the one we are interested in.
+    /^\@c man title ([A-Za-z0-9-]+) (.+)/ and do {
+	if (exists $defs{$1}) {
+	    $fn = $1;
+	    $tl = postprocess($2);
+	}
+	next;
+    };
 
     # Look for blocks surrounded by @c man begin SECTION ... @c man end.
     # This really oughta be @ifman ... @end ifman and the like, but such
     # would require rev'ing all other Texinfo translators.
+    /^\@c man begin ([A-Z]+) ([A-Za-z0-9-]+)/ and do {
+	$output = 1 if exists $defs{$2};
+        $sect = $1;
+	next;
+    };
     /^\@c man begin ([A-Z]+)/ and $sect = $1, $output = 1, next;
     /^\@c man end/ and do {
 	$sects{$sect} = "" unless exists $sects{$sect};
@@ -266,6 +289,12 @@
     local $_ = $_[0];
 
     # @value{foo} is replaced by whatever 'foo' is defined as.
+    if (/\@value\{([a-zA-Z0-9_-]+)\}/) {
+	if (! exists $defs{$1}) {
+	    print STDERR "Option $1 not define\n";
+	}
+
+    }
     s/\@value\{([a-zA-Z0-9_-]+)\}/$defs{$1}/g;
 
     # Formatting commands.
@@ -348,4 +377,3 @@
     $sects{FOOTNOTES} .= $_[0];
     $sects{FOOTNOTES} .= "\n\n";
 }
-    

2001-07-02  Matthias Klose  <doko@debian.org>

	* configure.in: Add $(GENERATED_JAVA_MANPAGES) to GENERATED_MANPAGES.


diff -b -r -u --exclude=Makefile --exclude=configure gcc-3.0/gcc/configure.in gcc-3.0.x/gcc/configure.in
--- gcc-3.0/gcc/configure.in	Wed Jun 13 23:36:35 2001
+++ gcc-3.0.x/gcc/configure.in	Mon Jul  2 21:14:38 2001
@@ -479,7 +479,7 @@
 AC_MSG_CHECKING([for recent Pod::Man])
 if perl -e 'use 1.10 Pod::Man' >/dev/null 2>&1; then
   AC_MSG_RESULT(yes)
-  GENERATED_MANPAGES=generated-manpages		AC_SUBST(GENERATED_MANPAGES)
+  GENERATED_MANPAGES='generated-manpages $(GENERATED_JAVA_MANPAGES)'	AC_SUBST(GENERATED_MANPAGES)
 else
   AC_MSG_RESULT(no)
   GENERATED_MANPAGES=



2001-07-02  Matthias Klose  <doko@debian.org>

	* gcj.texi: Markup for man page generation. Document missing
	options printed by <tool> --help.
	* Make-lang.in (generated-java-manpages, $(srcdir)/java/*.1):
	New targets.
	(java.install-man, java.uninstall, java-maintainer-clean) Updated.


diff -b -r -u --exclude=Makefile --exclude=configure gcc-3.0/gcc/java/Make-lang.in gcc-3.0.x/gcc/java/Make-lang.in
--- gcc-3.0/gcc/java/Make-lang.in	Fri Jun  8 23:43:45 2001
+++ gcc-3.0.x/gcc/java/Make-lang.in	Mon Jul  2 22:40:55 2001
@@ -177,11 +177,15 @@
           fi ; \
        done
 
-java.install-man:
-
 java.uninstall:
 	-rm -rf $(bindir)/$(JAVA_INSTALL_NAME)$(exeext)
 	-rm -rf $(bindir)/$(JAVA_CROSS_NAME)$(exeext)
+	-rm -rf $(man1dir)/$(JAVA_INSTALL_NAME)$(manext)
+	-rm -rf $(man1dir)/$(JAVA_CROSS_NAME)$(manext)
+	-rm -rf $(man1dir)/gcjh$(manext)
+	-rm -rf $(man1dir)/jv-scan$(manext)
+	-rm -rf $(man1dir)/jcf-dump$(manext)
+	-rm -rf $(man1dir)/gij$(manext)
 
 java.install-info:
 	if [ -f jc1$(exeext) ] ; then \
@@ -215,6 +219,7 @@
 java.extraclean:
 java.maintainer-clean:
 	-rm -f java/parse.c java/parse-scan.c java/parse.output java/y.tab.c
+	-rm -f $(srcdir)/java/gcj.1 $(srcdir)/java/gcjh.1 $(srcdir)/java/jv-scan.1 $(srcdir)/java/jcf-dump.1 $(srcdir)/java/gij.1
 #
 # Stage hooks:
 # The main makefile has already created stage?/java.
@@ -303,3 +308,75 @@
 java/gcj.dvi: $(srcdir)/java/gcj.texi $(srcdir)/doc/fdl.texi
 	s=`cd $(srcdir); pwd`; export s; \
 	cd java && $(TEXI2DVI) -I $$s/doc $$s/java/gcj.texi
+
+GENERATED_JAVA_MANPAGES = generated-java-manpages
+
+generated-java-manpages: $(srcdir)/java/gcj.1 $(srcdir)/java/gcjh.1 \
+	 $(srcdir)/java/jv-scan.1 $(srcdir)/java/jcf-dump.1 \
+	 $(srcdir)/java/gij.1
+
+$(srcdir)/java/gcj.1: $(srcdir)/java/gcj.texi
+	$(STAMP) $(srcdir)/java/gcj.1
+	-$(TEXI2POD) -D gcj < $(srcdir)/java/gcj.texi > gcj.pod
+	-($(POD2MAN) gcj.pod > $(srcdir)/java/gcj.1.T$$$$ && \
+		mv -f $(srcdir)/java/gcj.1.T$$$$ $(srcdir)/java/gcj.1) || \
+		(rm -f $(srcdir)/java/gcj.1.T$$$$ && exit 1)
+	-rm -f gcj.pod
+
+$(srcdir)/java/gcjh.1: $(srcdir)/java/gcj.texi
+	$(STAMP) $(srcdir)/java/gcjh.1
+	-$(TEXI2POD) -D gcjh < $(srcdir)/java/gcj.texi > gcjh.pod
+	-($(POD2MAN) gcjh.pod > $(srcdir)/java/gcjh.1.T$$$$ && \
+		mv -f $(srcdir)/java/gcjh.1.T$$$$ $(srcdir)/java/gcjh.1) || \
+		(rm -f $(srcdir)/java/gcjh.1.T$$$$ && exit 1)
+	-rm -f gcjh.pod
+
+$(srcdir)/java/jv-scan.1: $(srcdir)/java/gcj.texi
+	$(STAMP) $(srcdir)/java/jv-scan.1
+	-$(TEXI2POD) -D jv-scan < $(srcdir)/java/gcj.texi > jv-scan.pod
+	-($(POD2MAN) jv-scan.pod > $(srcdir)/java/jv-scan.1.T$$$$ && \
+		mv -f $(srcdir)/java/jv-scan.1.T$$$$ $(srcdir)/java/jv-scan.1) || \
+		(rm -f $(srcdir)/java/jv-scan.1.T$$$$ && exit 1)
+	-rm -f jv-scan.pod
+
+$(srcdir)/java/jcf-dump.1: $(srcdir)/java/gcj.texi
+	$(STAMP) $(srcdir)/java/jcf-dump.1
+	-$(TEXI2POD) -D jcf-dump < $(srcdir)/java/gcj.texi > jcf-dump.pod
+	-($(POD2MAN) jcf-dump.pod > $(srcdir)/java/jcf-dump.1.T$$$$ && \
+		mv -f $(srcdir)/java/jcf-dump.1.T$$$$ $(srcdir)/java/jcf-dump.1) || \
+		(rm -f $(srcdir)/java/jcf-dump.1.T$$$$ && exit 1)
+	-rm -f jcf-dump.pod
+
+$(srcdir)/java/gij.1: $(srcdir)/java/gcj.texi
+	$(STAMP) $(srcdir)/java/gij.1
+	-$(TEXI2POD) -D gij < $(srcdir)/java/gcj.texi > gij.pod
+	-($(POD2MAN) gij.pod > $(srcdir)/java/gij.1.T$$$$ && \
+		mv -f $(srcdir)/java/gij.1.T$$$$ $(srcdir)/java/gij.1) || \
+		(rm -f $(srcdir)/java/gij.1.T$$$$ && exit 1)
+	-rm -f gij.pod
+
+# Install the man pages.
+java.install-man: installdirs $(GENERATED_JAVA_MANPAGES)
+	-if [ -f $(GCJ)$(exeext) ]; then \
+	  if [ -f $(GCJ)-cross$(exeext) ]; then \
+	    rm -f $(man1dir)/$(JAVA_CROSS_NAME)$(manext); \
+	    $(INSTALL_DATA) $(srcdir)/java/gcj.1 $(man1dir)/$(JAVA_CROSS_NAME)$(manext); \
+	    chmod a-x $(man1dir)/$(JAVA_CROSS_NAME)$(manext); \
+	  else \
+	    rm -f $(man1dir)/$(JAVA_INSTALL_NAME)$(manext); \
+	    $(INSTALL_DATA) $(srcdir)/java/gcj.1 $(man1dir)/$(JAVA_INSTALL_NAME)$(manext); \
+	    chmod a-x $(man1dir)/$(JAVA_INSTALL_NAME)$(manext); \
+	  fi ; \
+	fi
+	-rm -f $(man1dir)/gcjh$(manext)
+	-$(INSTALL_DATA) $(srcdir)/java/gcjh.1 $(man1dir)/gcjh$(manext)
+	-chmod a-x $(man1dir)/gcjh$(manext)
+	-rm -f $(man1dir)/jv-scan$(manext)
+	-$(INSTALL_DATA) $(srcdir)/java/jv-scan.1 $(man1dir)/jv-scan$(manext)
+	-chmod a-x $(man1dir)/jv-scan$(manext)
+	-rm -f $(man1dir)/jcf-dump$(manext)
+	-$(INSTALL_DATA) $(srcdir)/java/jcf-dump.1 $(man1dir)/jcf-dump$(manext)
+	-chmod a-x $(man1dir)/jcf-dump$(manext)
+	-rm -f $(man1dir)/gij$(manext)
+	-$(INSTALL_DATA) $(srcdir)/java/gij.1 $(man1dir)/gij$(manext)
+	-chmod a-x $(man1dir)/gij$(manext)
diff -b -r -u --exclude=Makefile --exclude=configure gcc-3.0/gcc/java/gcj.texi gcc-3.0.x/gcc/java/gcj.texi
--- gcc-3.0/gcc/java/gcj.texi	Fri Jun  8 23:43:45 2001
+++ gcc-3.0.x/gcc/java/gcj.texi	Mon Jul  2 22:56:13 2001
@@ -7,6 +7,10 @@
 @c This is necessary due to Sun's restrictions on the use of
 @c the word ``Java'.
 
+@macro gcctabopt{body}
+@code{\body\}
+@end macro
+
 @c When this manual is copyrighted.
 @set copyrights-gcj 2001
 
@@ -42,6 +46,21 @@
 texts being (a) (see below), and with the Back-Cover Texts being (b)
 (see below).  A copy of the license is included in the section entitled
 ``GNU Free Documentation License''.
+Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
+
+@ignore
+@c man begin COPYRIGHT
+Copyright (C) 2001 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below).  A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@c man end
+@end ignore
 
 (a) The FSF's Front-Cover Text is:
 
@@ -511,11 +530,32 @@
 @node Invoking gcj
 @chapter Invoking gcj
 
+@c man title gcj Ahead-of-time compiler for the Java language
+
+@ignore
+@c man begin SYNOPSIS gcj
+gcj [@option{-I}@var{dir}@dots{}] [@option{-d}@var{dir}@dots{}]
+    [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+    [@option{-f}@var{option}@dots{}] [@option{--encoding}@var{name}]
+    [@option{--main=}@var{classname}] [@option{-C}]
+    [@option{-W}@var{warn}@dots{}] [@option{-D}@var{name}[=@var{value}]@dots{}]
+    @var{sourcefile}@dots{}
+@c man end
+@c man begin SEEALSO gcj
+gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gcj
+
 As @code{gcj} is just another front end to @code{gcc}, it supports many
 of the same options as gcc.  @xref{Option Summary, , Option Summary,
 gcc, Using the GNU Compiler Collection}.  This manual only documents the
 options specific to @code{gcj}.
 
+@c man end
+
 @menu
 * Input and output files::
 * Input Options::		How gcj finds files
@@ -525,6 +565,8 @@
 * Configure-time Options::	Options you won't use
 @end menu
 
+@c man begin OPTIONS gcj
+
 @node Input and output files
 @section Input and output files
 
@@ -532,7 +574,7 @@
 consists of a number of options and file names.  The following kinds
 of input file names are supported:
 
-@table @code
+@table @gcctabopt
 @item @var{file}.java
 Java source files.
 @item @var{file}.class
@@ -583,7 +625,7 @@
 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
 file, which @code{gcj} will search as if it is a directory.
 
-@table @code
+@table @gcctabopt
 @item -I@var{dir}
 All directories specified by @code{-I} are kept in order and prepended
 to the class path constructed from all the other options.  Unless
@@ -636,7 +678,7 @@
 @code{-fforce-classes-archive-check} can be used to overide this
 behavior in this particular case.)
 
-@table @code
+@table @gcctabopt
 @item -fforce-classes-archive-check
 This forces the compiler to always check for the special zero length
 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
@@ -678,7 +720,7 @@
 document the form of the warning which will have an effect -- the
 default being the opposite of what is listed.
 
-@table @code
+@table @gcctabopt
 @item -Wredundant-modifiers
 With this flag, @code{gcj} will warn about redundant modifiers.  For
 instance, it will warn if an interface method is declared @code{public}.
@@ -707,7 +749,7 @@
 In addition to the many @code{gcc} options controlling code generation,
 @code{gcj} has several options specific to itself.
 
-@table @code
+@table @gcctabopt
 @item --main=@var{CLASSNAME}
 This option is used when linking to specify the name of the class whose
 @code{main} method should be invoked when the resulting executable is
@@ -760,7 +802,7 @@
 options are listed here for completeness; if you are using @code{libgcj}
 then you won't want to touch these options.
 
-@table @code
+@table @gcctabopt
 @item -fuse-boehm-gc
 This enables the use of the Boehm GC bitmap marking code.  In particular
 this causes @code{gcj} to put an object marking descriptor into each
@@ -778,6 +820,7 @@
 dividing by zero.
 @end table
 
+@c man end
 
 @node Compatibility
 @chapter Compatibility with the Java Platform
@@ -815,12 +858,37 @@
 @node Invoking gcjh
 @chapter Invoking gcjh
 
+@c man title gcjh generate header files from Java class files
+
+@c man begin DESCRIPTION gcjh
+
 The @code{gcjh} program is used to generate header files from class
 files.  It can generate both CNI and JNI header files, as well as stub
 implementation files which can be used as a basis for implementing the
 required native methods.
 
-@table @code
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gcjh
+gcjh [@option{-stubs}] [@option{-jni}]
+    [@option{-add}@var{text}] [@option{-append}@var{text}] [@option{-friend}@var{text}] [@option{-preprend}@var{text}]
+    [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+    [@option{-I}@var{dir}@dots{}] [@option{-d}@var{dir}@dots{}]
+    [@option{-o}@var{file}] [@option{-td}@var{dir}]
+    [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
+    [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
+    @var{classname}@dots{}
+@c man end
+@c man begin SEEALSO gcjh
+gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS gcjh
+
+@table @gcctabopt
 @item -stubs
 This causes @code{gcjh} to generate stub files instead of header files.
 By default the stub file will be named after the class, with a suffix of
@@ -860,24 +928,61 @@
 @item -td @var{directory}
 Sets the name of the directory to use for temporary files.
 
+@item -M
+Print all dependencies to stdout; suppress ordinary output.
+
+@item -MM
+Print non-system dependencies to stdout; suppress ordinary output.
+
+@item -MD
+Print all dependencies to stdout.
+
+@item -MMD
+Print non-system dependencies to stdout.
+
 @item --help
 Print help about @code{gcjh} and exit.  No further processing is done.
 
 @item --version
 Print version information for @code{gcjh} and exit.  No further
 processing is done.
+
+@item -v, --verbose
+Print extra information while running.
 @end table
 
 All remaining options are considered to be names of classes.
 
+@c man end
 
 @node Invoking jv-scan
 @chapter Invoking jv-scan
 
+@c man title jv-scan print information about Java source file
+
+@c man begin DESCRIPTION jv-scan
+
 The @code{jv-scan} program can be used to print information about a Java
 source file (@file{.java} file).
 
-@table @code
+@c man end
+
+@ignore
+@c man begin SYNOPSIS jv-scan
+jv-scan [@option{--complexity}] [@option{--encoding}@var{name}]
+    [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
+    [@option{--version}] [@option{--help}]
+    [@option{-o}@var{file}] @var{inputfile}@dots{}
+@c man end
+@c man begin SEEALSO jv-scan
+gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS jv-scan
+
+@table @gcctabopt
 @item --complexity
 This prints a complexity measure, related to cyclomatic complexity, for
 each input file.
@@ -898,17 +1003,46 @@
 
 @item -o @var{file}
 Print output to the named file.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
 @end table
 
+@c man end
 
 @node Invoking jcf-dump
 @chapter Invoking jcf-dump
 
+@c man title jcf-dump print information about Java class files
+
+@ignore
+@c man begin SYNOPSIS jcf-dump
+jcf-dump [@option{-c}] [@option{--javap}]
+    [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+    [@option{-I}@var{dir}@dots{}] [@option{-o}@var{file}]
+    [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
+    @var{classname}@dots{}
+@c man end
+@c man begin SEEALSO jcf-dump
+gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION jcf-dump
+
 This is a class file examiner, similar to @code{javap}.  It will print
 information about a number of classes, which are specifed by class name
 or file name.
 
-@table @code
+@c man end
+
+@c man begin OPTIONS jcf-dump
+
+@table @gcctabopt
 @item -c
 Disassemble method bodies.  By default method bodies are not printed.
 
@@ -921,12 +1055,42 @@
 @itemx -I@var{directory}
 @itemx -o @var{file}
 These options as the same as the corresponding @code{gcj} options.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
+
+@item -v, --verbose
+Print extra information while running.
 @end table
 
+@c man end
 
 @node Invoking gij
 @chapter Invoking gij
 
+@c man title gij GNU interpreter for Java bytecode
+
+@ignore
+@c man begin SYNOPSIS gij
+gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
+
+gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
+
+  [@option{-D}@var{name}[=@var{value}]@dots{}]
+  [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
+  [@option{--version}] [@option{--help}]
+@c man end
+@c man begin SEEALSO gij
+gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gij
+
 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
 @code{gij} is not available on every platform; porting it requires a
 small amount of assembly programming which has not been done for all the
@@ -952,7 +1116,11 @@
 objects, it is possible to give @code{gij} the name of a class which has
 been compiled and put into a shared library on the class path.
 
-@table @code
+@c man end
+
+@c man begin OPTIONS gij
+
+@table @gcctabopt
 @item -D@var{name}[=@var{value}]
 This defines a system property named @var{name} with value @var{value}.
 If @var{value} is not specified then it defaults to the empty string.
@@ -969,8 +1137,15 @@
 @item -jar
 This indicates that the name passed to @code{gij} should be interpreted
 as the name of a jar file, not a class.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
 @end table
 
+@c man end
 
 @node Resources
 @chapter Resources



More information about the Gcc-patches mailing list