This is the mail archive of the binutils@sources.redhat.com mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

[RFC]: Generation of man pages from Texinfo files


Hi!

The following patch allows to generate the Binutils man pages from
the Texinfo files.  It uses texi2pod and pod2man tools in the same
manner as Gcc (see how gcc.1 is generated from invoke.texi).

 - texi2pod.pl comes from gcc/contrib.  I modified it a little bit
   because it assumed that a .texi file contained only one man page.
   This is not the case for Binutils, so I introduced the name of
   the man page in the @c man comments.  For the binutils, texi2pod
   is run for each man page and for each of them a variable is set
   (ie, -Dar, -Dnm, ...).  Texi2pod only outputs the corresponding man.

 - When the .texi files are processed by texi2pod, the variable 'man'
   must be defined.

 - I modified a little bit some .texi files to avoid to have cross
   references to some Info sections (ie, @ref{...}).  These cross
   references are put arround `@ifclear man' conditionals.

 - For ld.texi and as.texi, the man contains all platform options.
   For this, the texi files must define all the platform specific
   variables (ie, ARC, MIPS, ...).  I added these settings and they
   are enclosed by a `@ifset man' condition.

 - New man pages: readelf.1, dlltool.1, windres.1.

 - The Makefile.am now contain rules to rebuild the man pages 
   automatically (as in gcc).

 - I forgot the gprof man page (oops)


I checked the result man pages and  I've not seen problems, nor missing
sections, nor missing descriptions, nor strange/bad output.  Several 
man pages, as and ld in particular, are far more complete now.

However, I saw at least two differences between the generated man page
and the previous ones:

 - The title is always upper case (ie, `AR (1)').  This is due to pod2man.

 - In the man page, command names are now in \f(C font (courrier).
   In the original, they are in bold and no font change.

What do you think about all this?

	Stephane

ld/ChangeLog:
2001-03-23  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* ld.texinfo: Put @c man indications to generate the ld man page.
	When generating man, define all the variables.  Define SEEALSO
	and SYNOPSIS.  Re-organize some lines to avoid the cross references.
	* Makefile.am (MANCONF, TEXI2POD, POD2MAN): New variables.
	(ld.1): Generate from ld.texinfo.
	* Makefile.in: Regenerate.


binutils/ChangeLog:
2001-03-21  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* binutils.texi: Put @c man begin and @c man end indications
	to generate man pages using texi2pod and pod2man. Put @c man title
	to identify each man. Add SEEALSO entries.
	* Makefile.am (MANCONF, TEXI2POD, POD2MAN): New variable.
	(man_MANS): Add dlltool.1, nlmconv.1, readelf.1, windres.1,
	sort the list.
	(*.1): Build the man pages from binutils.texi.
	* Makefile.in: Regenerate.


etc/ChangeLog:
2001-03-23  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* texi2pod.pl: New file (from gcc/contrib).


gas/ChangeLog
2001-03-23  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* doc/as.texinfo: Put @c man begin to generate the as man page.
	When generating man, define all the variables. Re-organize some
	options to obtain better indentation of man page.
	* doc/Makefile.am (MANCONF, TEXI2POD, POD2MAN): New variable.
	(as.1): Build from as.texinfo.
	* doc/Makefile.in: Regenerate.
Index: binutils/Makefile.am
===================================================================
RCS file: /cvs/src/src/binutils/Makefile.am,v
retrieving revision 1.20
diff -u -p -r1.20 Makefile.am
--- Makefile.am	2001/02/27 06:43:53	1.20
+++ Makefile.am	2001/03/23 22:24:09
@@ -52,9 +52,29 @@ DLLWRAP_PROG=dllwrap
 
 SRCONV_PROG=srconv$(EXEEXT) sysdump$(EXEEXT) coffdump$(EXEEXT) 
 
-man_MANS = ar.1 nm.1 objdump.1 ranlib.1 size.1 strings.1 strip.1 objcopy.1 \
-	addr2line.1 nlmconv.1 $(DEMANGLER_NAME).1
+MANCONF  = -Dman
 
+TEXI2POD = perl $(srcdir)/../etc/texi2pod.pl
+
+POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
+
+# List of man pages generated from binutils.texi
+man_MANS = \
+	addr2line.1 \
+	ar.1 \
+	dlltool.1 \
+	nlmconv.1 \
+	nm.1 \
+	objcopy.1 \
+	objdump.1 \
+	ranlib.1 \
+	readelf.1 \
+	size.1 \
+	strings.1 \
+	strip.1 \
+	windres.1 \
+	$(DEMANGLER_NAME).1
+
 PROGS = $(SIZE_PROG) $(OBJDUMP_PROG) $(NM_PROG) $(AR_PROG) $(STRINGS_PROG) $(STRIP_PROG) $(RANLIB_PROG) $(DEMANGLER_PROG) $(OBJCOPY_PROG) @BUILD_NLMCONV@ @BUILD_SRCONV@ @BUILD_DLLTOOL@ @BUILD_WINDRES@ $(ADDR2LINE_PROG) $(READELF_PROG) @BUILD_DLLWRAP@ @BUILD_MISC@
 
 bin_PROGRAMS = $(SIZE_PROG) $(OBJDUMP_PROG) $(AR_PROG) $(STRINGS_PROG) $(RANLIB_PROG) $(OBJCOPY_PROG) @BUILD_NLMCONV@ @BUILD_SRCONV@ @BUILD_DLLTOOL@ @BUILD_WINDRES@ $(ADDR2LINE_PROG) $(READELF_PROG) @BUILD_DLLWRAP@ @BUILD_MISC@
@@ -338,6 +358,112 @@ config.texi: Makefile
 binutils.dvi: $(srcdir)/binutils.texi config.texi
 
 binutils.info: $(srcdir)/binutils.texi config.texi
+
+# Man page generation from texinfo
+$(srcdir)/addr2line.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Daddr2line < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/ar.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dar < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/dlltool.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Ddlltool < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/dlltool.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Ddlltool < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/nlmconv.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dnlmconv < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/nm.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dnm < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/objcopy.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dobjcopy < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/objdump.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dobjdump < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/ranlib.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dranlib < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/readelf.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dreadelf < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/size.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dsize < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/strings.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dstrings < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/strip.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dstrip < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/windres.1:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dwindres < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
+
+$(srcdir)/cxxfilt.man:	$(srcdir)/binutils.texi
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dcxxfilt < $< > $@.pod
+	-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f $@.pod
 
 MAINTAINERCLEANFILES = config.texi
 
Index: binutils/binutils.texi
===================================================================
RCS file: /cvs/src/src/binutils/binutils.texi,v
retrieving revision 1.34
diff -u -p -r1.34 binutils.texi
--- binutils.texi	2001/03/13 06:43:57	1.34
+++ binutils.texi	2001/03/23 22:24:26
@@ -28,15 +28,17 @@ END-INFO-DIR-ENTRY
 @end ifinfo
 
 @ifinfo
+@c man begin COPYRIGHT
 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 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 no Invariant Sections, with no Front-Cover Texts, and with no
-      Back-Cover Texts.  A copy of the license is included in the
-      section entitled "GNU Free Documentation License".
+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 no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".
 
+@c man end
 @ignore
 Permission is granted to process this file through TeX and print the
 results, provided the printed document carries a copying permission
@@ -173,11 +175,16 @@ section entitled "GNU Free Documentation
 @kindex ar
 @cindex archives
 @cindex collections of files
+
+@c man title ar create, modify, and extract from archives
+
 @smallexample
 ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
 ar -M [ <mri-script ]
 @end smallexample
 
+@c man begin DESCRIPTION ar
+
 The @sc{gnu} @code{ar} program creates, modifies, and extracts from
 archives.  An @dfn{archive} is a single file holding a collection of
 other files in a structure that makes it possible to retrieve
@@ -222,6 +229,8 @@ specify the single command-line option @
 with a script supplied via standard input, like the MRI ``librarian''
 program.
 
+@c man end
+
 @menu
 * ar cmdline::                  Controlling @code{ar} on the command line
 * ar scripts::                  Controlling @code{ar} with a script
@@ -232,7 +241,9 @@ program.
 @section Controlling @code{ar} on the command line
 
 @smallexample
+@c man begin SYNOPSIS ar
 ar [-X32_64] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
+@c man end
 @end smallexample
 
 @cindex Unix compatibility, @code{ar}
@@ -244,6 +255,8 @@ arguments to execute: one keyletter spec
 Most operations can also accept further @var{member} arguments,
 specifying particular files to operate on.
 
+@c man begin OPTIONS ar
+
 @sc{gnu} @code{ar} allows you to mix the operation code @var{p} and modifier
 flags @var{mod} in any order, within the first command-line argument.
 
@@ -455,6 +468,14 @@ default for GNU @code{ar}.  @code{ar} do
 @code{-X} options; in particular, it does not support @code{-X32}
 which is the default for AIX @code{ar}.
 
+@c man end
+
+@ignore
+@c man begin SEEALSO ar
+nm(1), ranlib(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node ar scripts
 @section Controlling @code{ar} with a script
 
@@ -632,7 +653,10 @@ The @sc{gnu} linker @code{ld} is now des
 @cindex symbols
 @kindex nm
 
+@c man title nm list symbols from object files
+
 @smallexample
+@c man begin SYNOPSIS nm
 nm [ -a | --debug-syms ]  [ -g | --extern-only ]
    [ -B ]  [ -C | --demangle[=@var{style}] ] [ -D | --dynamic ]
    [ -s | --print-armap ]  [ -A | -o | --print-file-name ]
@@ -642,8 +666,10 @@ nm [ -a | --debug-syms ]  [ -g | --exter
    [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
    [ --defined-only ] [-l | --line-numbers ]  [ --no-demangle ]
    [ -V | --version ]  [ -X 32_64 ]  [ --help ]  [ @var{objfile}@dots{} ]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION nm
 @sc{gnu} @code{nm} lists the symbols from object files @var{objfile}@dots{}.
 If no object files are listed as arguments, @code{nm} assumes the file
 @file{a.out}.
@@ -674,8 +700,11 @@ The symbol is in the uninitialized data 
 The symbol is common.  Common symbols are uninitialized data.  When
 linking, multiple common symbols may appear with the same name.  If the
 symbol is defined anywhere, the common symbols are treated as undefined
-references.  For more details on common symbols, see the discussion of
+references.
+@ifclear man
+For more details on common symbols, see the discussion of
 --warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
+@end man
 
 @item D
 The symbol is in the initialized data section.
@@ -732,6 +761,9 @@ The symbol type is unknown, or object fi
 The symbol name.
 @end itemize
 
+@c man end
+
+@c man begin OPTIONS nm
 The long and short forms of options, shown here as alternatives, are
 equivalent.
 
@@ -869,10 +901,21 @@ to @code{-X 32}, which is not supported 
 Show a summary of the options to @code{nm} and exit.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO nm
+ar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node objcopy
 @chapter objcopy
 
+@c man title objcopy copy and translate object files
+
 @smallexample
+@c man begin SYNOPSIS objcopy
 objcopy [ -F @var{bfdname} | --target=@var{bfdname} ]
         [ -I @var{bfdname} | --input-target=@var{bfdname} ]
         [ -O @var{bfdname} | --output-target=@var{bfdname} ]
@@ -902,8 +945,10 @@ objcopy [ -F @var{bfdname} | --target=@v
         [ --redefine-sym @var{old}=@var{new} ] [ --weaken ]
         [ -v | --verbose ] [ -V | --version ]  [ --help ]
         @var{infile} [@var{outfile}]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION objcopy
 The @sc{gnu} @code{objcopy} utility copies the contents of an object
 file to another.  @code{objcopy} uses the @sc{gnu} @sc{bfd} Library to
 read and write the object files.  It can write the destination object
@@ -939,6 +984,10 @@ files.  If the input format has an endia
 @code{objcopy} can only copy the inputs into file formats that have the
 same endianness or which have no endianness (eg @samp{srec}).
 
+@c man end
+
+@c man begin OPTIONS objcopy
+
 @table @code
 @item @var{infile}
 @itemx @var{outfile}
@@ -1203,13 +1252,24 @@ archives, @samp{objcopy -V} lists all me
 Show a summary of the options to @code{objcopy}.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO objcopy
+ld(1), objdump(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node objdump
 @chapter objdump
 
 @cindex object file information
 @kindex objdump
 
+@c man title objdump display information from object files.
+
 @smallexample
+@c man begin SYNOPSIS objdump
 objdump [ -a | --archive-headers ] 
         [ -b @var{bfdname} | --target=@var{bfdname} ] 
         [ -C | --demangle[=@var{style}] ]
@@ -1244,8 +1304,11 @@ objdump [ -a | --archive-headers ] 
         [ -V | --version ]
         [ -H | --help ]
         @var{objfile}@dots{}
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION objdump
+
 @code{objdump} displays information about one or more object files.
 The options control what particular information to display.  This
 information is mostly useful to programmers who are working on the
@@ -1256,6 +1319,10 @@ program to compile and work.
 specify archives, @code{objdump} shows information on each of the member
 object files.
 
+@c man end
+
+@c man begin OPTIONS objdump
+
 The long and short forms of options, shown here as alternatives, are
 equivalent.  At least one option from the list
 @samp{-a,-d,-D,-f,-g,-G,-h,-H,-p,-r,-R,-S,-t,-T,-V,-x} must be given. 
@@ -1481,8 +1548,11 @@ ELF file.  This is only useful on system
 @code{.stab} debugging symbol-table entries are carried in an ELF
 section.  In most other file formats, debugging symbol-table entries are
 interleaved with linkage symbols, and are visible in the @samp{--syms}
-output.  For more information on stabs symbols, see @ref{Top,Stabs,Stabs
+output.
+@ifclear man
+For more information on stabs symbols, see @ref{Top,Stabs,Stabs
 Overview,stabs.info, The ``stabs'' debug format}.
+@end ifclear
 
 @item --start-address=@var{address}
 @cindex start-address
@@ -1525,6 +1595,14 @@ relocation entries.  Using @samp{-x} is 
 Format some lines for output devices that have more than 80 columns.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO objdump
+nm(1), readelf(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node ranlib
 @chapter ranlib
 
@@ -1532,10 +1610,16 @@ Format some lines for output devices tha
 @cindex archive contents
 @cindex symbol index
 
+@c man title ranlib generate index to archive.
+
 @smallexample
+@c man begin SYNOPSIS ranlib
 ranlib [-vV] @var{archive}
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION ranlib
+
 @code{ranlib} generates an index to the contents of an archive and
 stores it in the archive.  The index lists each symbol defined by a
 member of an archive that is a relocatable object file.  
@@ -1550,6 +1634,10 @@ The @sc{gnu} @code{ranlib} program is an
 @code{ranlib} is completely equivalent to executing @samp{ar -s}.
 @xref{ar}.
 
+@c man end
+
+@c man begin OPTIONS ranlib
+
 @table @code
 @item -v
 @itemx -V
@@ -1557,19 +1645,33 @@ The @sc{gnu} @code{ranlib} program is an
 Show the version number of @code{ranlib}.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO ranlib
+ar(1), nm(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node size
 @chapter size
 
 @kindex size
 @cindex section sizes
 
+@c man title size list section sizes and total size.
+
 @smallexample
+@c man begin SYNOPSIS size
 size [ -A | -B | --format=@var{compatibility} ]
      [ --help ]  [ -d | -o | -x | --radix=@var{number} ]
      [ --target=@var{bfdname} ]  [ -V | --version ]  
      [ @var{objfile}@dots{} ]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION size
+
 The @sc{gnu} @code{size} utility lists the section sizes---and the total
 size---for each of the object or archive files @var{objfile} in its
 argument list.  By default, one line of output is generated for each
@@ -1578,6 +1680,10 @@ object file or each module in an archive
 @var{objfile}@dots{} are the object files to be examined.
 If none are specified, the file @code{a.out} will be used.
 
+@c man end
+
+@c man begin OPTIONS size
+
 The command line options have the following meanings:
 
 @table @code
@@ -1653,6 +1759,14 @@ automatically recognize many formats.
 Display the version number of @code{size}.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO size
+ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node strings
 @chapter strings
 @kindex strings
@@ -1660,13 +1774,19 @@ Display the version number of @code{size
 @cindex printing strings
 @cindex strings, printing
 
+@c man title strings print the strings of printable characters in files.
+
 @smallexample
+@c man begin SYNOPSIS strings
 strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-]
         [--all] [--print-file-name] [--bytes=@var{min-len}]
         [--radix=@var{radix}] [--target=@var{bfdname}]
         [--help] [--version] @var{file}@dots{}
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION strings
+
 For each @var{file} given, @sc{gnu} @code{strings} prints the printable
 character sequences that are at least 4 characters long (or the number
 given with the options below) and are followed by an unprintable
@@ -1677,6 +1797,10 @@ the strings from the whole file.
 @code{strings} is mainly useful for determining the contents of non-text
 files.
 
+@c man end
+
+@c man begin OPTIONS strings
+
 @table @code
 @item -a
 @itemx --all
@@ -1718,6 +1842,15 @@ Specify an object code format other than
 Print the program version number on the standard output and exit.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO strings
+ar(1), nm(1), objdump(1), ranlib(1), readelf(1)
+and the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node strip
 @chapter strip
 
@@ -1726,7 +1859,10 @@ Print the program version number on the 
 @cindex discarding symbols
 @cindex symbols, discarding
 
+@c man title strip Discard symbols from object files.
+
 @smallexample
+@c man begin SYNOPSIS strip
 strip [ -F @var{bfdname} | --target=@var{bfdname} ]
       [ -I @var{bfdname} | --input-target=@var{bfdname} ]
       [ -O @var{bfdname} | --output-target=@var{bfdname} ]
@@ -1738,8 +1874,11 @@ strip [ -F @var{bfdname} | --target=@var
       [ -o @var{file} ] [ -p | --preserve-dates ]
       [ -v | --verbose ]  [ -V | --version ]  [ --help ]
       @var{objfile}@dots{}
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION strip
+
 @sc{gnu} @code{strip} discards all symbols from object files
 @var{objfile}.  The list of object files may include archives.
 At least one object file must be given.
@@ -1747,6 +1886,10 @@ At least one object file must be given.
 @code{strip} modifies the files named in its argument,
 rather than writing modified copies under different names.
 
+@c man end
+
+@c man begin OPTIONS strip
+
 @table @code
 @item -F @var{bfdname}
 @itemx --target=@var{bfdname}
@@ -1825,20 +1968,34 @@ Verbose output: list all object files mo
 archives, @samp{strip -v} lists all members of the archive.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO strip
+the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node c++filt, addr2line, strip, Top
 @chapter c++filt
 
 @kindex c++filt
 @cindex demangling C++ symbols
 
+@c man title cxxfilt Demangle C++ and Java symbols.
+
 @smallexample
+@c man begin SYNOPSIS cxxfilt
 c++filt [ -_ | --strip-underscores ]
         [ -j | --java ]
 	[ -n | --no-strip-underscores ]
         [ -s @var{format} | --format=@var{format} ]
         [ --help ]  [ --version ]  [ @var{symbol}@dots{} ]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION cxxfilt
+
 @kindex cxxfilt
 The C++ and Java languages provides function overloading, which means
 that you can write many functions with the same name (providing each
@@ -1866,6 +2023,10 @@ If no @var{symbol} arguments are given, 
 names from the standard input and writes the demangled names to the
 standard output.  All results are printed on the standard output.
 
+@c man end
+
+@c man begin OPTIONS cxxfilt
+
 @table @code
 @item -_
 @itemx --strip-underscores
@@ -1911,6 +2072,14 @@ Print a summary of the options to @code{
 Print the version number of @code{c++filt} and exit.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO cxxfilt
+the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @quotation
 @emph{Warning:} @code{c++filt} is a new utility, and the details of its
 user interface are subject to change in future releases.  In particular,
@@ -1935,15 +2104,21 @@ c++filt @var{option} @var{symbol}
 @kindex addr2line
 @cindex address to file name and line number
 
+@c man title addr2line convert addresses into file names and line numbers.
+
 @smallexample
+@c man begin SYNOPSIS addr2line
 addr2line [ -b @var{bfdname} | --target=@var{bfdname} ]
           [ -C | --demangle[=@var{style} ]
           [ -e @var{filename} | --exe=@var{filename} ]
           [ -f | --functions ] [ -s | --basename ]
           [ -H | --help ] [ -V | --version ]
           [ addr addr ... ]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION addr2line
+
 @code{addr2line} translates program addresses into file names and line
 numbers.  Given an address and an executable, it uses the debugging
 information in the executable to figure out which file name and line
@@ -1973,6 +2148,10 @@ If the file name or function name can no
 @code{addr2line} will print two question marks in their place.  If the
 line number can not be determined, @code{addr2line} will print 0.
 
+@c man end
+
+@c man begin OPTIONS addr2line
+
 The long and short forms of options, shown here as alternatives, are
 equivalent.
 
@@ -2007,6 +2186,14 @@ Display function names as well as file a
 Display only the base of each file name.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO addr2line
+Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node nlmconv
 @chapter nlmconv
 
@@ -2027,15 +2214,21 @@ with the above formats.}.
 utilities, since it is only useful for NLM targets.
 @end quotation
 
+@c man title nlmconv converts object code into an NLM.
+
 @smallexample
+@c man begin SYNOPSIS nlmconv
 nlmconv [ -I @var{bfdname} | --input-target=@var{bfdname} ]
         [ -O @var{bfdname} | --output-target=@var{bfdname} ]
         [ -T @var{headerfile} | --header-file=@var{headerfile} ]
         [ -d | --debug]  [ -l @var{linker} | --linker=@var{linker} ]
         [ -h | --help ]  [ -V | --version ]
         @var{infile} @var{outfile}
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION nlmconv
+
 @code{nlmconv} converts the relocatable @samp{i386} object file
 @var{infile} into the NetWare Loadable Module @var{outfile}, optionally
 reading @var{headerfile} for NLM header information.  For instructions
@@ -2044,14 +2237,20 @@ on writing the NLM command file language
 Development and Tools Overview}, which is part of the NLM Software
 Developer's Kit (``NLM SDK''), available from Novell, Inc.
 @code{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read
-@var{infile}; see @ref{BFD,,BFD,ld.info,Using LD}, for
-more information.
+@var{infile};
+@ifclear man
+see @ref{BFD,,BFD,ld.info,Using LD}, for more information.
+@end ifclear
 
 @code{nlmconv} can perform a link step.  In other words, you can list
 more than one object file for input if you list them in the definitions
 file (rather than simply specifying one input file on the command line).
 In this case, @code{nlmconv} calls the linker for you.
 
+@c man end
+
+@c man begin OPTIONS nlmconv
+
 @table @code
 @item -I @var{bfdname}
 @itemx --input-target=@var{bfdname}
@@ -2092,6 +2291,14 @@ Prints a usage summary.
 Prints the version number for @code{nlmconv}.
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO nlmconv
+the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node windres
 @chapter windres
 
@@ -2102,10 +2309,16 @@ Prints the version number for @code{nlmc
 utilities, since it is only useful for Windows targets.
 @end quotation
 
+@c man title windres manipulate Windows resources.
+
 @smallexample
+@c man begin SYNOPSIS windres
 windres [options] [input-file] [output-file]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION windres
+
 @code{windres} reads resources from an input file and copies them into
 an output file.  Either file may be in one of three formats:
 
@@ -2148,6 +2361,10 @@ to convert it to a COFF object file, and
 your application.  This will make the resources described in the
 @code{rc} file available to Windows.
 
+@c man end
+
+@c man begin OPTIONS windres
+
 @table @code
 @item -i @var{filename}
 @itemx --input @var{filename}
@@ -2233,7 +2450,14 @@ If @code{windres} is compiled with @code
 this will turn on parser debugging.
 @end table
 
+@c man end
 
+@ignore
+@c man begin SEEALSO windres
+the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node dlltool
 @chapter Create files needed to build and use DLLs
 @cindex DLL
@@ -2247,7 +2471,10 @@ dynamic link libraries (DLLs).
 utilities, since it is only useful for those targets which support DLLs.
 @end quotation
 
+@c man title dlltool Create files needed to build and use DLLs.
+
 @smallexample
+@c man begin SYNOPSIS dlltool
 dlltool [-d|--input-def @var{def-file-name}]
         [-b|--base-file @var{base-file-name}]
         [-e|--output-exp @var{exports-file-name}]
@@ -2263,8 +2490,11 @@ dlltool [-d|--input-def @var{def-file-na
         [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork]
         [-n|--nodelete] [-v|--verbose] [-h|--help] [-V|--version]
         [object-file @dots{}]
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION dlltool
+
 @code{dlltool} reads its inputs, which can come from the @samp{-d} and
 @samp{-b} options as well as object files specified on the command
 line.  It then processes these inputs and if the @samp{-e} option has
@@ -2329,6 +2559,10 @@ that uses that DLL:
   gcc program.o dll.lib -o program
 @end smallexample
 
+@c man end
+
+@c man begin OPTIONS dlltool
+
 The command line options have the following meanings:
 
 @table @code
@@ -2478,13 +2712,24 @@ Displays dlltool's version number and th
 
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO dlltool
+the Info entries for @file{binutils}.
+@c man end
+@end ignore
+
 @node readelf
 @chapter readelf
 
 @cindex ELF file information
 @kindex readelf
 
+@c man title readelf Displays information about ELF files.
+
 @smallexample
+@c man begin SYNOPSIS readelf
 readelf [ -a | --all ] 
         [ -h | --file-header]
         [ -l | --program-headers | --segments]
@@ -2503,8 +2748,11 @@ readelf [ -a | --all ] 
         [ -v | --version]
         [ -H | --help]
         @var{elffile}@dots{}
+@c man end
 @end smallexample
 
+@c man begin DESCRIPTION readelf
+
 @code{readelf} displays information about one or more ELF format object
 files.  The options control what particular information to display.
 
@@ -2512,6 +2760,10 @@ files.  The options control what particu
 moment, @code{readelf} does not support examining archives, nor does it
 support examing 64 bit ELF files.
 
+@c man end
+
+@c man begin OPTIONS readelf
+
 The long and short forms of options, shown here as alternatives, are
 equivalent.  At least one option besides @samp{-v} or @samp{-H} must be
 given. 
@@ -2612,6 +2864,13 @@ Display the command line options underst
 
 @end table
 
+@c man end
+
+@ignore
+@c man begin SEEALSO readelf
+objdump(1), and the Info entries for @file{binutils}.
+@c man end
+@end ignore
 
 @node Selecting The Target System
 @chapter Selecting the target system
Index: etc/texi2pod.pl
===================================================================
RCS file: texi2pod.pl
diff -N texi2pod.pl
--- /dev/null	Tue May  5 13:32:27 1998
+++ texi2pod.pl	Fri Mar 23 14:24:30 2001
@@ -0,0 +1,356 @@
+#! /usr/bin/perl -w
+
+# This does trivial (and I mean _trivial_) conversion of Texinfo
+# markup to Perl POD format.  It's intended to be used to extract
+# something suitable for a manpage from a Texinfo document.
+
+$output = 0;
+$skipping = 0;
+%sects = ();
+$section = "";
+@icstack = ();
+@endwstack = ();
+@skstack = ();
+$shift = "";
+%defs = ();
+$fnno = 1;
+
+while ($_ = shift) {
+    if (/^-D(.*)$/) {
+	if ($1 ne "") {
+	    $flag = $1;
+	} 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 "";
+	#print STDERR "FL = $flag, V = $value\n";
+	$defs{$flag} = $value;
+
+    } elsif (/^-/) {
+	usage();
+    } else {
+	$in = $_, next unless defined $in;
+	$out = $_, next unless defined $out;
+	usage();
+    }
+}
+
+if (defined $in) {
+    open(STDIN, $in) or die "opening \"$in\": $!\n";
+}
+if (defined $out) {
+    open(STDOUT, ">$out") or die "opening \"$out\": $!\n";
+}
+
+while(<STDIN>)
+{
+    # Certain commands are discarded without further processing.
+    /^\@(?:
+	 [a-z]+index		# @*index: useful only in complete manual
+	 |need			# @need: useful only in printed manual
+	 |(?:end\s+)?group	# @group .. @end group: ditto
+	 |page			# @page: ditto
+	 |node			# @node: useful only in .info file
+	)\b/x and next;
+    
+    chomp;
+
+    # Look for filename and title markers.
+    /^\@setfilename\s+([^.]+)/ and $fn = $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};
+	$sects{$sect} .= postprocess($section);
+	$section = "";
+	$output = 0;
+	next;
+    };
+    next unless $output;
+
+    # Discard comments.  (Can't do it above, because then we'd never see
+    # @c man lines.)
+    /^\@c\b/ and next;
+
+    # End-block handler goes up here because it needs to operate even
+    # if we are skipping.
+    /^\@end\s+([a-z]+)/ and do {
+	# Ignore @end foo, where foo is not an operation which may
+	# cause us to skip, if we are presently skipping.
+	my $ended = $1;
+	next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu)$/;
+
+	die "\@end $ended without \@$ended at line $.\n" unless defined $endw;
+	die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw;
+
+	$endw = pop @endwstack;
+
+	if ($ended =~ /^(?:ifset|ifclear|ignore|menu)$/) {
+	    $skipping = pop @skstack;
+	    next;
+	} elsif ($ended =~ /^(?:example|smallexample)$/) {
+	    $shift = "";
+	    $_ = "";	# need a paragraph break
+	} elsif ($ended =~ /^(?:itemize|enumerate|table)$/) {
+	    $_ = "\n=back\n";
+	    $ic = pop @icstack;
+	} else {
+	    die "unknown command \@end $ended at line $.\n";
+	}
+    };
+
+    # We must handle commands which can cause skipping even while we
+    # are skipping, otherwise we will not process nested conditionals
+    # correctly.
+    /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = "ifset";
+	$skipping = 1 unless exists $defs{$1};
+	next;
+    };
+
+    /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = "ifclear";
+	$skipping = 1 if exists $defs{$1};
+	next;
+    };
+
+    /^\@(ignore|menu)\b/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = $1;
+	$skipping = 1;
+	next;
+    };
+
+    next if $skipping;
+
+    # Character entities.  First the ones that can be replaced by raw text
+    # or discarded outright:
+    s/\@copyright\{\}/(c)/g;
+    s/\@dots\{\}/.../g;
+    s/\@enddots\{\}/..../g;
+    s/\@([.!? ])/$1/g;
+    s/\@[:-]//g;
+    s/\@bullet(?:\{\})?/*/g;
+    s/\@TeX\{\}/TeX/g;
+    s/\@pounds\{\}/\#/g;
+    s/\@minus(?:\{\})?/-/g;
+    s/\\,/,/g;
+
+    # Now the ones that have to be replaced by special escapes
+    # (which will be turned back into text by unmunge())
+    s/&/&amp;/g;
+    s/\@\{/&lbrace;/g;
+    s/\@\}/&rbrace;/g;
+    s/\@\@/&at;/g;
+    # POD doesn't interpret E<> inside a verbatim block.
+    if ($shift eq "") {
+	s/</&lt;/g;
+	s/>/&gt;/g;
+    } else {
+	s/</&LT;/g;
+	s/>/&GT;/g;
+    }
+
+    # Single line command handlers.
+    /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and $defs{$1} = $2, next;
+    /^\@clear\s+([a-zA-Z0-9_-]+)/ and delete $defs{$1}, next;
+
+    /^\@section\s+(.+)$/ and $_ = "\n=head2 $1\n";
+    /^\@subsection\s+(.+)$/ and $_ = "\n=head3 $1\n";
+
+    # Block command handlers:
+    /^\@itemize\s+(\@[a-z]+|\*|-)/ and do {
+	push @endwstack, $endw;
+	push @icstack, $ic;
+	$ic = $1;
+	$_ = "\n=over 4\n";
+	$endw = "itemize";
+    };
+
+    /^\@enumerate(?:\s+([A-Z0-9]+))?/ and do {
+	push @endwstack, $endw;
+	push @icstack, $ic;
+	if (defined $1) {
+	    $ic = $1 . ".";
+	} else {
+	    $ic = "1.";
+	}
+	$_ = "\n=over 4\n";
+	$endw = "enumerate";
+    };
+
+    /^\@table\s+(\@[a-z]+)/ and do {
+	push @endwstack, $endw;
+	push @icstack, $ic;
+	$ic = $1;
+	$ic =~ s/\@(?:samp|strong|key|gcctabopt|env)/B/;
+	$ic =~ s/\@(?:code|kbd)/C/;
+	$ic =~ s/\@(?:dfn|var|emph|cite|i)/I/;
+	$ic =~ s/\@(?:file)/F/;
+	$_ = "\n=over 4\n";
+	$endw = "table";
+    };
+
+    /^\@((?:small)?example)/ and do {
+	push @endwstack, $endw;
+	$endw = $1;
+	$shift = "\t";
+	$_ = "";	# need a paragraph break
+    };
+
+    /^\@itemx?\s*(.+)?$/ and do {
+	if (defined $1) {
+	    # Entity escapes prevent munging by the <> processing below.
+	    $_ = "\n=item $ic\&LT;$1\&GT;\n";
+	} else {
+	    $_ = "\n=item $ic\n";
+	    $ic =~ y/A-Ya-y1-8/B-Zb-z2-9/;
+	}
+    };
+
+    $section .= $shift.$_."\n";
+}
+
+die "No filename or title\n" unless defined $fn && defined $tl;
+
+$sects{NAME} = "$fn \- $tl\n";
+$sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES};
+
+for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES
+	      BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
+    if(exists $sects{$sect}) {
+	$head = $sect;
+	$head =~ s/SEEALSO/SEE ALSO/;
+	print "=head1 $head\n\n";
+	print scalar unmunge ($sects{$sect});
+	print "\n";
+    }
+}
+
+sub usage
+{
+    die "usage: $0 [-D toggle...] [infile [outfile]]\n";
+}
+
+sub postprocess
+{
+    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.
+    # Temporary escape for @r.
+    s/\@r\{([^\}]*)\}/R<$1>/g;
+    s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g;
+    s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g;
+    s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g;
+    s/\@sc\{([^\}]*)\}/\U$1/g;
+    s/\@file\{([^\}]*)\}/F<$1>/g;
+    s/\@w\{([^\}]*)\}/S<$1>/g;
+    s/\@(?:dmn|math)\{([^\}]*)\}/$1/g;
+
+    # Handle @r inside bold.
+    1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B</g;
+
+    # Cross references are thrown away, as are @noindent and @refill.
+    # (@noindent is impossible in .pod, and @refill is unnecessary.)
+    # @* is also impossible in .pod; we discard it and any newline that
+    # follows it.  Similarly, our macro @gol must be discarded.
+
+    s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g;
+    s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g;
+    s/;\s+\@pxref\{(?:[^\}]*)\}//g;
+    s/\@noindent\s*//g;
+    s/\@refill//g;
+    s/\@gol//g;
+    s/\@\*\s*\n?//g;
+
+    # @uref can take one, two, or three arguments, with different
+    # semantics each time.  @url and @email are just like @uref with
+    # one argument, for our purposes.
+    s/\@(?:uref|url|email)\{([^\},]*)\}/&lt;B<$1>&gt;/g;
+    s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g;
+    s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g;
+
+    # Turn B<blah I<blah> blah> into B<blah> I<blah> B<blah> to
+    # match Texinfo semantics of @emph inside @samp.
+    s/&LT;/</g;
+    s/&GT;/>/g;
+    1 while (s/B<([^<>]*)I<([^>]+)>/B<$1>I<$2>B</g);
+    1 while (s/I<([^<>]*)B<([^>]+)>/I<$1>B<$2>I</g);
+    s/[BI]<>//g;
+    s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g;
+    s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g;
+
+    # Extract footnotes.  This has to be done after all other
+    # processing because otherwise the regexp will choke on formatting
+    # inside @footnote.
+    while (/\@footnote/g) {
+	s/\@footnote\{([^\}]+)\}/[$fnno]/;
+	add_footnote($1, $fnno);
+	$fnno++;
+    }
+
+    return $_;
+}
+
+sub unmunge
+{
+    # Replace escaped symbols with their equivalents.
+    local $_ = $_[0];
+
+    s/&lt;/E<lt>/g;
+    s/&gt;/E<gt>/g;
+    s/&lbrace;/\{/g;
+    s/&rbrace;/\}/g;
+    s/&at;/\@/g;
+    s/&amp;/&/g;
+    return $_;
+}
+
+sub add_footnote
+{
+    unless (exists $sects{FOOTNOTES}) {
+	$sects{FOOTNOTES} = "\n=over 4\n\n";
+    }
+
+    $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++;
+    $sects{FOOTNOTES} .= $_[0];
+    $sects{FOOTNOTES} .= "\n\n";
+}
+    
Index: gas/doc/Makefile.am
===================================================================
RCS file: /cvs/src/src/gas/doc/Makefile.am,v
retrieving revision 1.9
diff -u -p -r1.9 Makefile.am
--- Makefile.am	2001/02/18 23:33:03	1.9
+++ Makefile.am	2001/03/23 22:24:53
@@ -5,6 +5,13 @@ AUTOMAKE_OPTIONS = cygnus
 # What version of the manual you want; "all" includes everything
 CONFIG=all
 
+# Options to extract the man page from as.texinfo
+MANCONF = -Dman
+
+TEXI2POD = perl $(top_srcdir)/../etc/texi2pod.pl
+
+POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
+
 man_MANS = as.1
 
 info_TEXINFOS = as.texinfo gasp.texi
@@ -55,3 +62,17 @@ noinst_TEXINFOS = internals.texi
 DISTCLEANFILES = asconfig.texi
 
 MAINTAINERCLEANFILES = gasver.texi
+
+# Maintenance
+
+# Build the man page from the texinfo file
+# The sed command removes the no-adjust Nroff command so that
+# the man output looks standard.
+$(srcdir)/as.1: $(srcdir)/as.texinfo
+	touch $(srcdir)/as.1
+	-$(TEXI2POD) $(MANCONF) < $(srcdir)/as.texinfo > as.pod
+	-($(POD2MAN) as.pod | \
+		sed -e '/^.if n .na/d' > $(srcdir)/as.1.T$$$$ && \
+		mv -f $(srcdir)/as.1.T$$$$ $(srcdir)/as.1) || \
+		(rm -f $(srcdir)/as.1.T$$$$ && exit 1)
+
Index: gas/doc/as.texinfo
===================================================================
RCS file: /cvs/src/src/gas/doc/as.texinfo,v
retrieving revision 1.36
diff -u -p -r1.36 as.texinfo
--- as.texinfo	2001/03/23 19:35:02	1.36
+++ as.texinfo	2001/03/23 22:25:19
@@ -19,6 +19,38 @@
 @include asconfig.texi
 @include gasver.texi
 @c ---
+@c man begin NAME
+@ifset man
+@c Configure for the generation of man pages
+@set AS as
+@set TARGET TARGET
+@set GENERIC
+@set A29K
+@set ARC
+@set ARM
+@set D10V
+@set D30V
+@set H8/300
+@set H8/500
+@set HPPA
+@set I370
+@set I80386
+@set I860
+@set I960
+@set M32R
+@set M68HC11
+@set M680X0
+@set MCORE
+@set MIPS
+@set PDP11
+@set PJ
+@set SH
+@set SPARC
+@set C54X
+@set V850
+@set VAX
+@end ifset
+@c man end
 @c common OR combinations of conditions
 @ifset AOUT
 @set aout-bout
@@ -88,15 +120,18 @@ END-INFO-DIR-ENTRY
 @ifinfo
 This file documents the GNU Assembler "@value{AS}".
 
+@c man begin COPYRIGHT
 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 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 no Invariant Sections, with no Front-Cover Texts, and with no
-      Back-Cover Texts.  A copy of the license is included in the
-      section entitled "GNU Free Documentation License".
+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 no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".
 
+@c man end
+
 @ignore
 Permission is granted to process this file through Tex and print the
 results, provided the printed document carries copying permission
@@ -197,11 +232,19 @@ code for @value{TARGET} architectures.
 Here is a brief summary of how to invoke @code{@value{AS}}.  For details,
 @pxref{Invoking,,Comand-Line Options}.
 
+@c man title AS the portable GNU assembler.
+
+@c man begin SEEALSO
+gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
+@c man end
+
 @c We don't use deffn and friends for the following because they seem
 @c to be limited to one line for the header.
 @smallexample
+@c man begin SYNOPSIS
 @value{AS} [ -a[cdhlns][=file] ] [ -D ]  [ --defsym @var{sym}=@var{val} ]
- [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
+ [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I @var{dir} ] 
+ [ -J ] [ -K ] [ -L ]
  [ --listing--lhs-width=NUM ][ --listing-lhs-width2=NUM ]
  [ --listing-rhs-width=NUM ][ --listing-cont-lines=NUM ]
  [ --keep-locals ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ]
@@ -215,20 +258,22 @@ Here is a brief summary of how to invoke
  [ -EB | -EL ]
 @end ifset
 @ifset ARM
- [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]60 |
-   -m[arm]600 | -m[arm]610 | -m[arm]620 | -m[arm]7[t][[d]m[i]][fe] | -m[arm]70 |
-   -m[arm]700 | -m[arm]710[c] | -m[arm]7100 | -m[arm]7500 | -m[arm]8 |
-   -m[arm]810 | -m[arm]9 | -m[arm]920 | -m[arm]920t | -m[arm]9tdmi |
+ [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 |
+   -m[arm]6 | -m[arm]60 | -m[arm]600 | -m[arm]610 |
+   -m[arm]620 | -m[arm]7[t][[d]m[i]][fe] | -m[arm]70 |
+   -m[arm]700 | -m[arm]710[c] | -m[arm]7100 |
+   -m[arm]7500 | -m[arm]8 | -m[arm]810 | -m[arm]9 |
+   -m[arm]920 | -m[arm]920t | -m[arm]9tdmi |
    -mstrongarm | -mstrongarm110 | -mstrongarm1100 ]
- [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t |
-   -m[arm]v5 | -[arm]v5t | -[arm]v5te ]
+ [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m |
+   -m[arm]v4 | -m[arm]v4t | -m[arm]v5 | -[arm]v5t |
+   -[arm]v5te ]
  [ -mthumb | -mall ]
  [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ]
  [ -EB | -EL ]
- [ -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant ]
- [ -mthumb-interwork ]
- [ -moabi ]
- [ -k ]
+ [ -mapcs-32 | -mapcs-26 | -mapcs-float |
+   -mapcs-reentrant ]
+ [ -mthumb-interwork ] [ -moabi ] [ -k ]
 @end ifset
 @ifset D10V
  [ -O ]
@@ -249,7 +294,8 @@ Here is a brief summary of how to invoke
 @c The order here is important.  See c-sparc.texi.
  [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
    -Av8plus | -Av8plusa | -Av9 | -Av9a ]
- [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] [ -32 | -64 ]
+ [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ]
+ [ -32 | -64 ]
 @end ifset
 @ifset TIC54X
  [ -mcpu=54[123589] | -mcpu=54[56]lp ] [ -mfar-mode | -mf ] 
@@ -260,11 +306,13 @@ Here is a brief summary of how to invoke
 @end ifset
 @ifset I960
 @c see md_parse_option in tc-i960.c
- [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
+ [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB |
+   -AKC | -AMC ]
  [ -b ] [ -no-relax ]
 @end ifset
 @ifset M32R
- [ --m32rx | --[no-]warn-explicit-parallel-conflicts | --W[n]p ]
+ [ --m32rx | --[no-]warn-explicit-parallel-conflicts |
+   --W[n]p ]
 @end ifset
 @ifset M680X0
  [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
@@ -275,8 +323,9 @@ Here is a brief summary of how to invoke
 @end ifset
 @ifset M68HC11
  [ -m68hc11 | -m68hc12 ]
- [ --force-long-branchs ] [ --short-branchs ] [ --strict-direct-mode ]
- [ --print-insn-syntax ] [ --print-opcodes ] [ --generate-example ]
+ [ --force-long-branchs ] [ --short-branchs ]
+ [ --strict-direct-mode ] [ --print-insn-syntax ]
+ [ --print-opcodes ] [ --generate-example ]
 @end ifset
 @ifset MIPS
  [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ]
@@ -287,8 +336,11 @@ Here is a brief summary of how to invoke
  [ --emulation=@var{name} ]
 @end ifset
  [ -- | @var{files} @dots{} ]
+@c man end
 @end smallexample
 
+@c man begin OPTIONS
+
 @table @code
 @item -a[cdhlmns]
 Turn on listings, in any of a variety of ways:
@@ -546,8 +598,9 @@ Motorola 68000 series.
 @item -l
 Shorten references to undefined symbols, to one word instead of two.
 
-@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
-@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
+@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030
+@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332
+@itemx | -m68333 | -m68340 | -mcpu32 | -m5200
 Specify what processor in the 68000 family is the target.  The default
 is normally the 68020, but this can be changed at configuration time.
 
@@ -810,6 +863,8 @@ Assemble for a little endian target.
 @end table
 @end ifset
 
+@c man end
+
 @menu
 * Manual::                      Structure of this Manual
 * GNU Assembler::               The GNU Assembler
@@ -895,6 +950,8 @@ computer-readable series of instructions
 @node GNU Assembler
 @section The GNU Assembler
 
+@c man begin DESCRIPTION
+
 @sc{gnu} @code{as} is really a family of assemblers.
 @ifclear GENERIC
 This manual describes @code{@value{AS}}, a member of that family which is
@@ -923,6 +980,8 @@ assembler for the same architecture; for
 incompatible versions of 680x0 assembly language syntax.
 @end ifset
 
+@c man end
+
 Unlike older assemblers, @code{@value{AS}} is designed to assemble a source
 program in one pass of the source file.  This has a subtle impact on the
 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
@@ -960,6 +1019,7 @@ SOM or ELF format object files.
 @section Command Line
 
 @cindex command line conventions
+
 After the program name @code{@value{AS}}, the command line may contain
 options and file names.  Options may appear in any order, and may be
 before, after, or between file names.  The order of file names is
@@ -1003,6 +1063,7 @@ doesn't change the meaning of the source
 The source program is a concatenation of the text in all the files, in the
 order specified.
 
+@c man begin DESCRIPTION
 Each time you run @code{@value{AS}} it assembles exactly one source
 program.  The source program is made up of one or more files.
 (The standard input is also a file.)
@@ -1023,6 +1084,8 @@ in your command line.
 If the source is empty, @code{@value{AS}} produces a small, empty object
 file.
 
+@c man end
+
 @subheading Filenames and Line-numbers
 
 @cindex input file linenumbers
@@ -1080,6 +1143,8 @@ information for the debugger.
 @node Errors
 @section Error and Warning Messages
 
+@c man begin DESCRIPTION
+
 @cindex error messages
 @cindex warning messages
 @cindex messages from assembler
@@ -1089,6 +1154,8 @@ runs @code{@value{AS}} automatically.  W
 that @code{@value{AS}} could keep assembling a flawed program; errors report a
 grave problem that stops the assembly.
 
+@c man end
+
 @cindex format of warning messages
 Warning messages have the format
 
@@ -1139,6 +1206,8 @@ to the @value{TARGET}.
 to particular machine architectures.
 @end ifset
 
+@c man begin DESCRIPTION
+
 If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2),
 you can use the @samp{-Wa} option to pass arguments through to the assembler.
 The assembler arguments must be separated from each other (and the @samp{-Wa})
@@ -1158,6 +1227,8 @@ command-line options are automatically p
 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
 precisely what options it passes to each compilation pass, including the
 assembler.)
+
+@c man end
 
 @menu
 * a::             -a[cdhlns] enable listings
Index: ld/Makefile.am
===================================================================
RCS file: /cvs/src/src/ld/Makefile.am,v
retrieving revision 1.55
diff -u -p -r1.55 Makefile.am
--- Makefile.am	2001/02/27 06:43:55	1.55
+++ Makefile.am	2001/03/23 22:25:34
@@ -41,6 +41,13 @@ MKDEP = gcc -MM
 # What version of the manual to build
 DOCVER = gen
 
+# Options to extract the man page from ld.texinfo
+MANCONF = -Dman
+
+TEXI2POD = perl $(BASEDIR)/etc/texi2pod.pl
+
+POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
+
 #stuff for self hosting (can be overridden in config file).
 HOSTING_CRT0 = @HOSTING_CRT0@
 HOSTING_LIBS = @HOSTING_LIBS@
@@ -899,6 +906,17 @@ ld.info: $(srcdir)/ld.texinfo configdoc.
 ld.dvi: $(srcdir)/ld.texinfo configdoc.texi ldver.texi
 	TEXINPUTS=$(top_srcdir)/../texinfo:$$TEXINPUTS \
 	  MAKEINFO="$(MAKEINFO) -I $(srcdir) -I $(BFDDIR)/doc" $(TEXI2DVI) $(srcdir)/ld.texinfo
+
+# Build the man page from the texinfo file
+# The sed command removes the no-adjust Nroff command so that
+# the man output looks standard.
+$(srcdir)/ld.1: $(srcdir)/ld.texinfo
+	touch $(srcdir)/ld.1
+	-$(TEXI2POD) $(MANCONF) < $(srcdir)/ld.texinfo > ld.pod
+	-($(POD2MAN) ld.pod | \
+		sed -e '/^.if n .na/d' > $(srcdir)/ld.1.T$$$$ && \
+		mv -f $(srcdir)/ld.1.T$$$$ $(srcdir)/ld.1) || \
+		(rm -f $(srcdir)/ld.1.T$$$$ && exit 1)
 
 MAINTAINERCLEANFILES = ldver.texi
 
Index: ld/ld.texinfo
===================================================================
RCS file: /cvs/src/src/ld/ld.texinfo,v
retrieving revision 1.35
diff -u -p -r1.35 ld.texinfo
--- ld.texinfo	2001/03/17 21:24:26	1.35
+++ ld.texinfo	2001/03/23 22:25:59
@@ -9,6 +9,38 @@
 
 @c @smallbook
 
+@c man begin NAME
+@ifset man
+@c Configure for the generation of man pages
+@set UsesEnvVars
+@set GENERIC
+@set A29K
+@set ARC
+@set ARM
+@set D10V
+@set D30V
+@set H8/300
+@set H8/500
+@set HPPA
+@set I370
+@set I80386
+@set I860
+@set I960
+@set M32R
+@set M68HC11
+@set M680X0
+@set MCORE
+@set MIPS
+@set PDP11
+@set PJ
+@set SH
+@set SPARC
+@set C54X
+@set V850
+@set VAX
+@end ifset
+@c man end
+
 @ifinfo
 @format
 START-INFO-DIR-ENTRY
@@ -63,14 +95,16 @@ notice identical to this one except for 
 @end tex
 
 @vskip 0pt plus 1filll
+@c man begin COPYRIGHT
 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 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 no Invariant Sections, with no Front-Cover Texts, and with no
-      Back-Cover Texts.  A copy of the license is included in the
-      section entitled "GNU Free Documentation License".
+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 no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+@c man end
 
 @end titlepage
 @end iftex
@@ -123,6 +157,21 @@ section entitled "GNU Free Documentation
 
 @cindex @sc{gnu} linker
 @cindex what is this?
+
+@ifsef man
+@c man begin SYNOPSIS
+ld [ options ] objfile...
+@c man end
+
+@c man begin SEEALSO
+ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
+the Info entries for @file{binutils} and
+@file{ld}.
+@c man end
+@end ifset
+
+@c man begin DESCRIPTION
+
 @code{ld} combines a number of object and archive files, relocates
 their data and ties up symbol references. Usually the last step in
 compiling a program is to run @code{ld}.
@@ -131,6 +180,14 @@ compiling a program is to run @code{ld}.
 a superset of AT&T's Link Editor Command Language syntax,
 to provide explicit and total control over the linking process.
 
+@ifset man
+@c For the man only
+This man page does not describe the command language; see the 
+@code{ld} entry in @code{info}, or the manual
+ld: the GNU linker, for full details on the command language and 
+on other aspects of the GNU linker. 
+@end ifset
+
 @ifclear SingleFormat
 This version of @code{ld} uses the general purpose BFD libraries
 to operate on object files. This allows @code{ld} to read, combine, and
@@ -145,13 +202,19 @@ execution immediately upon encountering 
 @code{ld} continues executing, allowing you to identify other errors
 (or, in some cases, to get an output file in spite of the error).
 
+@c man end
+
 @node Invocation
 @chapter Invocation
 
+@c man begin DESCRIPTION
+
 The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations,
 and to be as compatible as possible with other linkers.  As a result,
 you have many choices to control its behavior.
 
+@c man end
+
 @ifset UsesEnvVars
 @menu
 * Options::                     Command Line Options
@@ -164,6 +227,9 @@ you have many choices to control its beh
 
 @cindex command line
 @cindex options
+
+@c man begin OPTIONS
+
 The linker supports a plethora of command-line options, but in actual
 practice few of them are used in any particular context.
 @cindex standard Unix system
@@ -309,8 +375,11 @@ The default format is taken from the env
 @xref{Environment}.
 @end ifset
 You can also define the input format from a script, using the command
-@code{TARGET}; see @ref{Format Commands}.
+@code{TARGET};
+@ifclear man
+see @ref{Format Commands}.
 @end ifclear
+@end ifclear
 
 @kindex -c @var{MRI-cmdfile}
 @kindex --mri-script=@var{MRI-cmdfile}
@@ -319,7 +388,13 @@ You can also define the input format fro
 @itemx --mri-script=@var{MRI-commandfile}
 For compatibility with linkers produced by MRI, @code{ld} accepts script
 files written in an alternate, restricted command language, described in
-@ref{MRI,,MRI Compatible Script Files}.  Introduce MRI script files with
+@ifclear man
+@ref{MRI,,MRI Compatible Script Files}.
+@end ifclear
+@ifset man
+the MRI Compatible Script Files section of GNU ld documentation.
+@end ifset
+Introduce MRI script files with
 the option @samp{-c}; use the @samp{-T} option to run linker
 scripts written in the general-purpose @code{ld} scripting language.
 If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
@@ -1443,8 +1518,12 @@ those options are only available for ELF
 
 @end table
 
+@c man end
+
 @subsection Options specific to i386 PE targets
 
+@c man begin OPTIONS
+
 The i386 PE linker supports the @code{-shared} option, which causes
 the output to be a dynamically linked library (DLL) instead of a
 normal executable.  You should name the output @code{*.dll} when you
@@ -1600,10 +1679,14 @@ subsystem version also.
 
 @end table
 
+@c man end
+
 @ifset UsesEnvVars
 @node Environment
 @section Environment Variables
 
+@c man begin ENVIRONMENT
+
 You can change the behavior of @code{ld} with the environment variables
 @code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}.
 
@@ -1631,7 +1714,6 @@ available emulations with the @samp{--ve
 the @samp{-m} option is not used, and the @code{LDEMULATION} environment
 variable is not defined, the default emulation depends upon how the
 linker was configured.
-@end ifset
 
 @kindex COLLECT_NO_DEMANGLE
 @cindex demangling, default
@@ -1641,6 +1723,9 @@ default to not demangling symbols.  This
 a similar fashion by the @code{gcc} linker wrapper program.  The default
 may be overridden by the @samp{--demangle} and @samp{--no-demangle}
 options.
+
+@c man end
+@end ifset
 
 @node Scripts
 @chapter Linker Scripts

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]