New documentation style

8 files changed, 1034 insertions, 1041 deletions

diff --git a/bfd/archive.c b/bfd/archive.c
index efd18a3..2bfc70b 100644
--- a/bfd/archive.c
+++ b/bfd/archive.c
@@ -20,18 +20,21 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
 /*doc*
 @setfilename archive-info
-@section Archives
+SECTION
+	Archives
 
-Gumby, you promised to write this bit...
+DESCRIPTION
+	Gumby, you promised to write this bit...
 
-Archives are supported in BFD in @code{archive.c}.
+	Archives are supported in BFD in <<archive.c>>.
 
-An archive is represented internally just like another BFD, with a
-pointer to a chain of contained BFDs. Archives can be created by
-opening BFDs, linking them together and attaching them as children to
-another BFD and then closing the parent BFD. 
+	An archive is represented internally just like another BFD,
+	with a pointer to a chain of contained BFDs. Archives can be
+	created by opening BFDs, linking them together and attaching
+	them as children to another BFD and then closing the parent
+	BFD. 
 
-*-*/
+*/
 
 /* Assumes:
    o - all archive elements start on an even boundary, newline padded;
@@ -84,9 +87,15 @@ _bfd_generic_mkarchive (abfd)
   return true;
 }
 
-/*proto* bfd_get_next_mapent
-What this does
-*; PROTO(symindex, bfd_get_next_mapent, (bfd *, symindex, carsym **));
+/*
+FUNCTION
+	bfd_get_next_mapent
+
+DESCRIPTION
+	What this does
+
+SYNOPSIS
+	symindex bfd_get_next_mapent(bfd *, symindex, carsym **);
 */
 symindex
 bfd_get_next_mapent (abfd, prev, entry)
@@ -123,12 +132,17 @@ _bfd_create_empty_archive_element_shell (obfd)
   return nbfd;
 }
 
-/*proto* bfd_set_archive_head
+/*
+FUNCTION
+	bfd_set_archive_head
 
-Used whilst processing archives. Sets the head of the chain of BFDs
-contained in an archive to @var{new_head}. (see chapter on archives)
+DESCRIPTION
+	Used whilst processing archives. Sets the head of the chain of
+	BFDs contained in an archive to @var{new_head}. (see chapter
+	on archives)
 
-*; PROTO(boolean, bfd_set_archive_head, (bfd *output, bfd *new_head));
+SYNOPSIS
+	boolean bfd_set_archive_head(bfd *output, bfd *new_head);
 
 */
 
@@ -342,10 +356,15 @@ get_elt_at_filepos (archive, filepos)
   return NULL;
 }
 
-/*proto* bfd_get_elt_at_index
-Return the sub bfd contained within the archive at archive index n.
+/*
+FUNCTION
+	bfd_get_elt_at_index
 
-*; PROTO(bfd *, bfd_get_elt_at_index, (bfd *, int));
+DESCRIPTION
+	Return the sub bfd contained within the archive at archive index n.
+
+SYNOPSIS
+	bfd *bfd_get_elt_at_index(bfd *, int);
 
 */
 bfd *
@@ -359,15 +378,20 @@ bfd_get_elt_at_index (abfd, index)
   return result;
 }
 
-/*proto* bfd_openr_next_archived_file
-Initially provided a BFD containing an archive and NULL, opens a BFD
-on the first contained element and returns that. Subsequent calls to
-bfd_openr_next_archived_file should pass the archive and the previous
-return value to return a created BFD to the next contained element.
-NULL is returned when there are no more.
+/*
+FUNCTION
+	bfd_openr_next_archived_file
+
+DESCRIPTION
+	Initially provided a BFD containing an archive and NULL, opens
+	a BFD on the first contained element and returns that.
+	Subsequent calls to bfd_openr_next_archived_file should pass
+	the archive and the previous return value to return a created
+	BFD to the next contained element. NULL is returned when there
+	are no more.
 
-*; PROTO(bfd*, bfd_openr_next_archived_file,
-               (bfd *archive, bfd *previous));
+SYNOPSIS
+	bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
 
 */
 
@@ -1234,7 +1258,7 @@ bsd_write_armap (arch, elength, map, orl_count, stridx)
 
 
 /* A coff armap looks like :
- ARMAG
+ lARMAG
  struct ar_hdr with name = '/' 
  number of symbols
  offset of file for symbol 0
diff --git a/bfd/core.c b/bfd/core.c
index 49fa7dc..993df11 100644
--- a/bfd/core.c
+++ b/bfd/core.c
@@ -18,22 +18,29 @@ You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
-/*doc*
-@section Core files
-Buff output this facinating topic
+/*
+SECTION
+	Core files
+
+DESCRIPTION
+	Buff output this facinating topic
 */
 
 #include "bfd.h"
 #include "sysdep.h"
 #include "libbfd.h"
 
-/** Some core file info commands */
 
-/*proto* bfd_core_file_failing_command
-Returns a read-only string explaining what program was running when
-it failed and produced the core file being read
+/*
+FUNCTION
+	bfd_core_file_failing_command
+
+DESCRIPTION
+	Returns a read-only string explaining what program was running
+	when it failed and produced the core file being read
 
-*; PROTO(CONST char *, bfd_core_file_failing_command, (bfd *));
+SYNOPSIS
+	CONST char *bfd_core_file_failing_command(bfd *);
 */
 
 CONST char *
@@ -47,12 +54,18 @@ DEFUN(bfd_core_file_failing_command,(abfd),
   return BFD_SEND (abfd, _core_file_failing_command, (abfd));
 }
 
-/*proto* bfd_core_file_failing_signal
-Returns the signal number which caused the core dump which generated
-the file the BFD is attached to.
+/*
+FUNCTION
+	bfd_core_file_failing_signal
 
-*; PROTO(int, bfd_core_file_failing_signal, (bfd *));
+DESCRIPTION
+	Returns the signal number which caused the core dump which
+	generated the file the BFD is attached to.
+
+SYNOPSIS
+	int bfd_core_file_failing_signal(bfd *);
 */
+
 int
 bfd_core_file_failing_signal (abfd)
      bfd *abfd;
@@ -65,21 +78,29 @@ bfd_core_file_failing_signal (abfd)
 }
 
 
-/*proto* core_file_matches_executable_p
-Returns @code{true} if the core file attached to @var{core_bfd} was
-generated by a run of the executable file attached to @var{exec_bfd},
-or else @code{false}.
-*; PROTO(boolean, core_file_matches_executable_p,
-    (bfd *core_bfd, bfd *exec_bfd));
+/*
+FUNCTION
+	core_file_matches_executable_p
+
+DESCRIPTION
+	Returns <<true>> if the core file attached to @var{core_bfd}
+	was generated by a run of the executable file attached to
+	@var{exec_bfd}, or else <<false>>.
+
+SYNOPSIS
+	boolean core_file_matches_executable_p
+		(bfd *core_bfd, bfd *exec_bfd);
 */
+
 boolean
 core_file_matches_executable_p (core_bfd, exec_bfd)
      bfd *core_bfd, *exec_bfd;
 {
-  if ((core_bfd->format != bfd_core) || (exec_bfd->format != bfd_object)) {
-    bfd_error = wrong_format;
-    return false;
-  }
+    if ((core_bfd->format != bfd_core) || (exec_bfd->format != bfd_object)) {
+	    bfd_error = wrong_format;
+	    return false;
+	}
 
-  return BFD_SEND (core_bfd, _core_file_matches_executable_p, (core_bfd, exec_bfd));
+    return BFD_SEND (core_bfd, _core_file_matches_executable_p,
+		     (core_bfd, exec_bfd));
 }
diff --git a/bfd/ctor.c b/bfd/ctor.c
index 6d20269..5aa75b7 100644
--- a/bfd/ctor.c
+++ b/bfd/ctor.c
@@ -21,62 +21,67 @@ You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
-/*doc*
-@section Constructors
-Classes in C++ have 'constructors' and 'destructors'.  These are
-functions which are called automatically by the language whenever data
-of a class is created or destroyed.  Class data which is static data
-may also be have a type which requires 'construction', the contructor
-must be called before the data can be referenced, so the contructor
-must be called before the program begins.
-
-The common solution to this problem is for the compiler to call a
-magic function as the first statement @code{main}.  This magic
-function, (often called @code{__main}) runs around calling the
-constructors for all the things needing it.
-
-With COFF the compile has a bargain with the linker et al.  All
-constructors are given strange names, for example
-@code{__GLOBAL__$I$foo} might be the label of a contructor for the
-class @var{foo}.  The solution on unfortunate systems (most system V
-machines) is to perform a partial link on all the .o files, do an
-@code{nm} on the result, run @code{awk} or some such over the result
-looking for strange @code{__GLOBAL__$} symbols, generate a C program
-from this, compile it and link with the partially linked input. This
-process is usually called @code{collect}.
-
-Some versions of @code{a.out} use something called the
-@code{set_vector} mechanism.  The constructor symbols are output from
-the compiler with a special stab code saying that they are
-constructors, and the linker can deal with them directly.
-
-BFD allows applications (ie the linker) to deal with constructor
-information independently of their external implimentation by
-providing a set of entry points for the indiviual object back ends to
-call which maintains a database of the contructor information.  The
-application can interrogate the database to find out what it wants.
-
-The construction data essential for the linker to be able to perform
-its job are:
-
-@itemize @bullet
-@item 	asymbol
-The asymbol of the contructor entry point contains all the information
-necessary to call the function.
-@item	table id
-The type of symbol, ie is it a contructor, a destructor or something
-else someone dreamed up to make our lives difficult.
-@end itemize
-
-This module takes this information and then builds extra sections
-attached to the bfds which own the entry points.  It creates these
-sections as if they were tables of pointers to the entry points, and
-builds relocation entries to go with them so that the tables can be
-relocated along with the data they reference.
-
-These sections are marked with a special bit (@code{SEC_CONSTRUCTOR})
-which the linker notices and do with what it wants.
-
+/*
+SECTION
+	Constructors
+
+DESCRIPTION
+	Classes in C++ have 'constructors' and 'destructors'.  These
+	are functions which are called automatically by the language
+	whenever data of a class is created or destroyed.  Class data
+	which is static data may also be have a type which requires
+	'construction', the contructor must be called before the data
+	can be referenced, so the contructor must be called before the
+	program begins. 
+
+	The common solution to this problem is for the compiler to
+	call a magic function as the first statement <<main>>.
+	This magic function, (often called <<__main>>) runs around
+	calling the constructors for all the things needing it.
+
+	With COFF the compile has a bargain with the linker et al.
+	All constructors are given strange names, for example
+	<<__GLOBAL__$I$foo>> might be the label of a contructor for
+	the class @var{foo}.  The solution on unfortunate systems
+	(most system V machines) is to perform a partial link on all
+	the .o files, do an <<nm>> on the result, run <<awk>> or some
+	such over the result looking for strange <<__GLOBAL__$>>
+	symbols, generate a C program from this, compile it and link
+	with the partially linked input. This process is usually
+	called <<collect>>. 
+
+	Some versions of <<a.out>> use something called the
+	<<set_vector>> mechanism.  The constructor symbols are output
+	from the compiler with a special stab code saying that they
+	are constructors, and the linker can deal with them directly. 
+
+	BFD allows applications (ie the linker) to deal with
+	constructor information independently of their external
+	implimentation by providing a set of entry points for the
+	indiviual object back ends to call which maintains a database
+	of the contructor information.  The application can
+	interrogate the database to find out what it wants.  The
+	construction data essential for the linker to be able to
+	perform its job are: 
+
+	o asymbol
+	The asymbol of the contructor entry point contains all the
+	information necessary to call the function. 
+
+	o table id
+	The type of symbol, ie is it a contructor, a destructor or
+	something else someone dreamed up to make our lives difficult.
+
+	This module takes this information and then builds extra
+	sections attached to the bfds which own the entry points.  It
+	creates these sections as if they were tables of pointers to
+	the entry points, and builds relocation entries to go with
+	them so that the tables can be relocated along with the data
+	they reference. 
+
+	These sections are marked with a special bit
+	(<<SEC_CONSTRUCTOR>>) which the linker notices and do with
+	what it wants.
 
 */
 
@@ -86,22 +91,23 @@ which the linker notices and do with what it wants.
 
 
 
-/*proto-internal* bfd_constructor_entry 
-
-This function is called with an a symbol describing the
-function to be called, an string which descibes the xtor type, eg
-something like "CTOR" or "DTOR" would be fine. And the bfd which owns
-the function.
-
-It's duty is to create a section called "CTOR" or "DTOR" or whatever
-if the bfd doesn't already have one, and grow a relocation table for
-the entry points as they accumulate.
+/*
+INTERNAL FUNCTION
+	bfd_constructor_entry 
 
+DESCRIPTION
+	This function is called with an a symbol describing the
+	function to be called, an string which descibes the xtor type,
+	eg something like "CTOR" or "DTOR" would be fine. And the bfd
+	which owns the function. Its duty is to create a section
+	called "CTOR" or "DTOR" or whatever if the bfd doesn't already
+	have one, and grow a relocation table for the entry points as
+	they accumulate.
 
-*; PROTO(void, bfd_constructor_entry,
-           (bfd *abfd, 
-	    asymbol **symbol_ptr_ptr,
-	    CONST char*type));
+SYNOPSIS
+	void bfd_constructor_entry(bfd *abfd, 
+		asymbol **symbol_ptr_ptr,
+		CONST char*type);
 
 */
 
diff --git a/bfd/libbfd.h b/bfd/libbfd.h
index 3c964ac..929b076 100644
--- a/bfd/libbfd.h
+++ b/bfd/libbfd.h
@@ -189,146 +189,32 @@ extern bfd *bfd_last_cache;
 /* THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/
 
 /*:init.c*/
-/* bfd_check_init
-
-This routine is called before any other bfd function using initialized
-data is used to ensure that the structures have been initialized.
-Soon this function will go away, and the bfd library will assume that
-bfd_init has been called.
-*/
-
- void EXFUN(bfd_check_init,(void));
-
-/*
-*/
+void EXFUN(bfd_check_init, (void));
 
 /*:libbfd.c*/
-/* bfd_xmalloc
-bfd_xmalloc -- Like malloc, but exit if no more memory.
-*/
- PROTO(PTR, bfd_xmalloc,( bfd_size_type size));
-
-/*
-
- bfd_write_bigendian_4byte_int
-*/
-
- PROTO(void, bfd_write_bigendian_4byte_int,( bfd *abfd,  int i));
-
-/*
-
-*i bfd_log2
-Return the log base 2 of the value supplied, rounded up. eg an arg
-of 1025 would return 11.
-*/
- PROTO(bfd_vma, bfd_log2,(bfd_vma x));
-
-/*
-*/
+bfd_vma EXFUN(bfd_log2, (bfd_vma x));
 
 /*:cache.c*/
-/* BFD_CACHE_MAX_OPEN
-The maxiumum number of files which the cache will keep open at one
-time.
-*/
 #define BFD_CACHE_MAX_OPEN 10
-
-/*
-
-  bfd_last_cache
-Zero, or a pointer to the topmost BFD on the chain.  This is used by
-the @code{bfd_cache_lookup} macro in @file{libbfd.h} to determine when
-it can avoid a function call.
-*/
 extern bfd *bfd_last_cache;
-
-/*
-
-  bfd_cache_lookup
-Checks to see if the required BFD is the same as the last one looked
-up. If so then it can use the iostream in the BFD with impunity, since
-it can't have changed since the last lookup, otherwise it has to
-perform the complicated lookup function
-*/
 #define bfd_cache_lookup(x) \
-     ((x)==bfd_last_cache? \
-        (FILE*)(bfd_last_cache->iostream): \
-         bfd_cache_lookup_worker(x))
-
-/*
-
-*i bfd_cache_init
-Initialize a BFD by putting it on the cache LRU.
-*/
- PROTO(void, bfd_cache_init, (bfd *));
-
-/*
-
-*i bfd_cache_close
-Remove the BFD from the cache. If the attached file is open, then close it too.
-*/
- PROTO(void, bfd_cache_close, (bfd *));
-
-/*
-
-*i bfd_open_file
-Call the OS to open a file for this BFD.  Returns the FILE *
-(possibly null) that results from this operation.  Sets up the
-BFD so that future accesses know the file is open. If the FILE *
-returned is null, then there is won't have been put in the cache, so
-it won't have to be removed from it.
-*/
- PROTO(FILE *, bfd_open_file, (bfd *));
-
-/*
-
-*i bfd_cache_lookup_worker
-Called when the macro @code{bfd_cache_lookup} fails to find a quick
-answer. Finds a file descriptor for this BFD.  If necessary, it open it.
-If there are already more than BFD_CACHE_MAX_OPEN files open, it trys to close
-one first, to avoid running out of file descriptors. 
-*/
- PROTO(FILE *, bfd_cache_lookup_worker, (bfd *));
-
-/*
-*/
-
+    ((x)==bfd_last_cache? \
+      (FILE*)(bfd_last_cache->iostream): \
+       bfd_cache_lookup_worker(x))
+void  EXFUN(bfd_cache_init , (bfd *));
+void EXFUN(bfd_cache_close , (bfd *));
+FILE* EXFUN(bfd_open_file, (bfd *));
+FILE *EXFUN(bfd_cache_lookup_worker, (bfd *));
 
 /*:ctor.c*/
-/* bfd_constructor_entry 
-
-This function is called with an a symbol describing the
-function to be called, an string which descibes the xtor type, eg
-something like "CTOR" or "DTOR" would be fine. And the bfd which owns
-the function.
-
-It's duty is to create a section called "CTOR" or "DTOR" or whatever
-if the bfd doesn't already have one, and grow a relocation table for
-the entry points as they accumulate.
-*/
-
- PROTO(void, bfd_constructor_entry,
-           (bfd *abfd, 
-	    asymbol **symbol_ptr_ptr,
-	    CONST char*type));
-
-/*
-*/
-
+void EXFUN(bfd_constructor_entry, (bfd *abfd, 
+asymbol **symbol_ptr_ptr,
+CONST char*type));
 
 /*:reloc.c*/
-/* bfd_default_reloc_type_lookup
-
-Provides a default relocation lookuperer for any architectue 
-*/
-
- CONST struct reloc_howto_struct *EXFUN(bfd_default_reloc_type_lookup,
-     (CONST struct bfd_arch_info *,
-      bfd_reloc_code_type  code));
-
-/*
-*/
-
+CONST struct reloc_howto_struct *EXFUN(bfd_default_reloc_type_lookup
+, (CONST struct bfd_arch_info *,
+bfd_reloc_code_type  code));
 
 /*:cpu-h8300.c*/
 
@@ -337,62 +223,13 @@ Provides a default relocation lookuperer for any architectue
 /*:cpu-empty.c*/
 
 /*:archures.c*/
-/* bfd_default_arch_struct
-
-What bfds are seeded with 
-*/
-
-extern bfd_arch_info_type bfd_default_arch_struct;
-
-/*
- bfd_default_set_arch_mach
-
-Set the architecture and machine type in a bfd. This finds the correct
-pointer to structure and inserts it into the arch_info pointer. 
-*/
-
-  boolean EXFUN(bfd_default_set_arch_mach,(bfd *abfd,
-          enum bfd_architecture arch,
-	 unsigned long mach));
-
-/*
-
-This routine initializes the architecture dispatch table by calling
-all installed architecture packages and getting them to poke around.
-*/
-
- PROTO(void, bfd_arch_init,(void));
-
-/*
-
- bfd_arch_linkin
-
-Link the provided arch info structure into the list
-*/
-
- void EXFUN(bfd_arch_linkin,(bfd_arch_info_type *));
-
-/*
-
- bfd_default_compatible
-
-The default function for testing for compatibility 
-*/
-
- CONST bfd_arch_info_type *EXFUN(bfd_default_compatible,
-     (CONST bfd_arch_info_type *a,
-     CONST bfd_arch_info_type *b));
-
-/*
-
- bfd_default_scan
-The default function for working out whether this is an architecture
-hit and a machine hit 
-*/
-
- boolean EXFUN(bfd_default_scan,(CONST struct bfd_arch_info *, CONST char *));
-
-/*
-*/
-
+boolean EXFUN(bfd_default_set_arch_mach, (bfd *abfd,
+enum bfd_architecture arch,
+unsigned long mach));
+void  EXFUN(bfd_arch_init, (void));
+void EXFUN(bfd_arch_linkin, (bfd_arch_info_type *));
+CONST bfd_arch_info_type *EXFUN(bfd_default_compatible
+, (CONST bfd_arch_info_type *a,
+CONST bfd_arch_info_type *b));
+boolean EXFUN(bfd_default_scan, (CONST struct bfd_arch_info *, CONST char *));
 
diff --git a/bfd/libcoff.h b/bfd/libcoff.h
index 43dc87b..b666e2e 100644
--- a/bfd/libcoff.h
+++ b/bfd/libcoff.h
@@ -29,7 +29,32 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 #define obj_relocbase(bfd)	(coff_data(bfd)->relocbase)
 #define obj_raw_syments(bfd)	(coff_data(bfd)->raw_syments)
 #define obj_convert(bfd)	(coff_data(bfd)->conversion_table)
+#if CFILE_STUFF
+#define obj_symbol_slew(bfd)	(coff_data(bfd)->symbol_index_slew)
+#else
+#define obj_symbol_slew(bfd) 0
+#endif
+
+#if 0
+typedef struct coff_ptr_struct
+{
+  unsigned int offset;
+  char fix_tag;
+  char fix_end;
+  union {
+    union internal_auxent auxent;
+    struct internal_syment syment;
+  } u;
+} combined_entry_type;
+
 
+typedef struct 
+{
+  asymbol symbol;
+  combined_entry_type *native;
+  struct lineno_cache_entry *lineno;
+} coff_symbol_type;
+#endif
 
 /* `Tdata' information kept for COFF files.  */
 
@@ -71,73 +96,20 @@ typedef struct coff_tdata
 /*THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/
 
 /*:coffcode.h*/
-
-/*
-The hidden information for an asymbol is:
-*/
-
- typedef struct coff_ptr_struct
- {
-
-/*
-Remembers the offset from the first symbol in the file for this
-symbol. Generated by @code{coff_renumber_symbols}.
-*/
-
-   unsigned int offset;
-
-/*
-Should the tag field of this symbol be renumbered.
-Created by @code{coff_pointerize_aux}.
-*/
-
-   char fix_tag;
-
-/*
-Should the endidx field of this symbol be renumbered.
-Created by @code{coff_pointerize_aux}.
-*/
-
-   char fix_end;
-
-/*
-The container for the symbol structure as read and translated from the file.
-*/
-
-   union {
-     union internal_auxent auxent;
-     struct internal_syment syment;
-   } u;
- } combined_entry_type;
-
-/*
-
-Each canonical asymbol really looks like this:
-*/
-
- typedef struct coff_symbol_struct
- {
-
-/*
-The actual symbol which the rest of BFD works with
-*/
-
-   asymbol symbol;
-
-/*
-A pointer to the hidden information for this symbol
-*/
-
-   combined_entry_type *native;
-
-/*
-A pointer to the linenumber information for this symbol
-*/
-
-   struct lineno_cache_entry *lineno;
- } coff_symbol_type;
-
-/*
-*/
-
+typedef struct coff_ptr_struct 
+{
+unsigned int offset;
+char fix_tag;
+char fix_end;
+union {
+   union internal_auxent auxent;
+   struct internal_syment syment;
+ } u;
+} combined_entry_type;
+typedef struct coff_symbol_struct
+{
+asymbol symbol;
+combined_entry_type *native;
+struct lineno_cache_entry *lineno;
+} coff_symbol_type;
 
diff --git a/bfd/reloc.c b/bfd/reloc.c
index 4804e84..e22d920 100644
--- a/bfd/reloc.c
+++ b/bfd/reloc.c
@@ -18,162 +18,165 @@ You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
-/*doc*
-@section Relocations
+/*
+SECTION
+	Relocations
 
-BFD maintains relocations in much the same was as it maintains
-symbols; they are left alone until required, then read in en-mass and
-traslated into an internal form. There is a common routine
-@code{bfd_perform_relocation} which acts upon the canonical form to to
-the actual fixup.
+DESCRIPTION
+	BFD maintains relocations in much the same was as it maintains
+	symbols; they are left alone until required, then read in
+	en-mass and traslated into an internal form. There is a common
+	routine <<bfd_perform_relocation>> which acts upon the
+	canonical form to to the actual fixup.
 
-Note that relocations are maintained on a per section basis, whilst
-symbols are maintained on a per BFD basis.
+	Note that relocations are maintained on a per section basis,
+	whilst symbols are maintained on a per BFD basis.
 
-All a back end has to do to fit the BFD interface is to create as many
-@code{struct reloc_cache_entry} as there are relocations in a
-particuar section, and fill in the right bits:
+	All a back end has to do to fit the BFD interface is to create
+	as many <<struct reloc_cache_entry>> as there are relocations
+	in a particuar section, and fill in the right bits:
 
 @menu
 * typedef arelent::
-* reloc handling functions::
+* howto manager::
 @end menu
 
 */
-#include "sysdep.h"
 #include "bfd.h"
+#include "sysdep.h"
 #include "libbfd.h"
-/*doc
-@node typedef arelent, Relocations, reloc handling functions, Relocations
-@section typedef arelent
+/*doc*
+@node typedef arelent, howto manager, Relocations, Relocations
 
+SUBSECTION
+	typedef arelent
 
 */
 
-/*proto* bfd_perform_relocation
-The relocation routine returns as a status an enumerated type:
+/*
+FUNCTION
+	bfd_perform_relocation
 
-*+++
+DESCRIPTION
+	The relocation routine returns as a status an enumerated type:
 
-$typedef enum bfd_reloc_status {
-No errors detected
+.typedef enum bfd_reloc_status {
+	No errors detected
 
-$  bfd_reloc_ok,
+.  bfd_reloc_ok,
 
-The relocation was performed, but there was an overflow.
+	The relocation was performed, but there was an overflow.
 
-$  bfd_reloc_overflow,
+.  bfd_reloc_overflow,
 
-The address to relocate was not within the section supplied
+	The address to relocate was not within the section supplied
 
-$  bfd_reloc_outofrange,
+.  bfd_reloc_outofrange,
 
-Used by special functions
+	Used by special functions
 
-$  bfd_reloc_continue,
+.  bfd_reloc_continue,
 
-Unused 
+	Unused 
 
-$  bfd_reloc_notsupported,
+.  bfd_reloc_notsupported,
 
-Unsupported relocation size requested. 
+	Unsupported relocation size requested. 
 
-$  bfd_reloc_other,
+.  bfd_reloc_other,
 
-The symbol to relocate against was undefined.
+	The symbol to relocate against was undefined.
 
-$  bfd_reloc_undefined,
+.  bfd_reloc_undefined,
 
-The relocation was performed, but may not be ok - presently generated
-only when linking i960 coff files with i960 b.out symbols.
-
-$  bfd_reloc_dangerous
-$   }
-$ bfd_reloc_status_enum_type;
-
-*---
-
-*/
+	The relocation was performed, but may not be ok - presently
+	generated only when linking i960 coff files with i960 b.out symbols.
 
-/*proto*
+.  bfd_reloc_dangerous
+.   }
+. bfd_reloc_status_type;
 
-*+++
 
-$typedef struct reloc_cache_entry 
-${
+.typedef struct reloc_cache_entry 
+.{
 
-A pointer into the canonical table of pointers 
+	A pointer into the canonical table of pointers 
 
-$  struct symbol_cache_entry **sym_ptr_ptr;
+.  struct symbol_cache_entry **sym_ptr_ptr;
 
-offset in section                 
+	offset in section                 
 
-$  rawdata_offset address;
+.  rawdata_offset address;
 
-addend for relocation value        
+	addend for relocation value        
 
-$  bfd_vma addend;    
+.  bfd_vma addend;    
 
-if sym is null this is the section 
+	if sym is null this is the section 
 
-$  struct sec *section;
+.  struct sec *section;
 
-Pointer to how to perform the required relocation
+	Pointer to how to perform the required relocation
 
-$  CONST struct reloc_howto_struct *howto;
-$} arelent;
+.  CONST struct reloc_howto_struct *howto;
+.} arelent;
 
-*---
 
 */
 
-/*doc*
-@table @code
-@item sym_ptr_ptr
-The symbol table pointer points to a pointer to the symbol associated with the
-relocation request. This would naturally be the pointer into the table
-returned by the back end's get_symtab action. @xref{Symbols}. The
-symbol is referenced through a pointer to a pointer so that tools like
-the linker can fix up all the symbols of the same name by modifying
-only one pointer. The relocation routine looks in the symbol and uses
-the base of the section the symbol is attached to and the value of
-the symbol as the initial relocation offset. If the symbol pointer is
-zero, then the section provided is looked up.
-@item address
-The address field gives the offset in bytes from the base of the
-section data which owns the relocation record to the first byte of
-relocatable information. The actual data relocated will be relative to
-this point - for example, a relocation type which modifies the bottom
-two bytes of a four byte word would not touch the first byte pointed
-to in a big endian world.
-@item addend
-The addend is a value provided by the back end to be added (!) to the
-relocation offset. Its interpretation is dependent upon the howto.
-For example, on the 68k the code:
-
-*+
+/*
+DESCRIPTION
+
+	o sym_ptr_ptr
+	The symbol table pointer points to a pointer to the symbol
+	associated with the relocation request. This would naturally
+	be the pointer into the table returned by the back end's
+	get_symtab action. @xref{Symbols}. The symbol is referenced
+	through a pointer to a pointer so that tools like the linker
+	can fix up all the symbols of the same name by modifying only
+	one pointer. The relocation routine looks in the symbol and
+	uses the base of the section the symbol is attached to and the
+	value of the symbol as the initial relocation offset. If the
+	symbol pointer is zero, then the section provided is looked up.
+
+	o address
+	The address field gives the offset in bytes from the base of
+	the section data which owns the relocation record to the first
+	byte of relocatable information. The actual data relocated
+	will be relative to this point - for example, a relocation
+	type which modifies the bottom two bytes of a four byte word
+	would not touch the first byte pointed to in a big endian
+	world. @item addend The addend is a value provided by the back
+	end to be added (!) to the relocation offset. Its
+	interpretation is dependent upon the howto. For example, on
+	the 68k the code:
+
+EXAMPLE
+
         char foo[];
         main()
                 {
                 return foo[0x12345678];
                 }
-*-
-Could be compiled into:
 
-*+
+DESCRIPTION
+	Could be compiled into:
+
+EXAMPLE
         linkw fp,#-4
         moveb @@#12345678,d0
         extbl d0
         unlk fp
         rts
-*-
 
-This could create a reloc pointing to foo, but leave the offset in the data
-(something like)
+DESCRIPTION
+
+	This could create a reloc pointing to foo, but leave the
+	offset in the data (something like)
 
-*+
+EXAMPLE
 RELOCATION RECORDS FOR [.text]:
-OFFSET   TYPE      VALUE 
+offset   type      value 
 00000006 32        _foo
 
 00000000 4e56 fffc          ; linkw fp,#-4
@@ -181,54 +184,59 @@ OFFSET   TYPE      VALUE
 0000000a 49c0               ; extbl d0
 0000000c 4e5e               ; unlk fp
 0000000e 4e75               ; rts
-*-
-Using coff and an 88k, some instructions don't have enough space in them to
-represent the full address range, and pointers have to be loaded in
-two parts. So you'd get something like:
+DESCRIPTION
 
-*+
+	Using coff and an 88k, some instructions don't have enough
+	space in them to represent the full address range, and
+	pointers have to be loaded in two parts. So you'd get something like:
+
+EXAMPLE
         or.u     r13,r0,hi16(_foo+0x12345678)
         ld.b     r2,r13,lo16(_foo+0x12345678)
         jmp      r1
-*-
-This whould create two relocs, both pointing to _foo, and with 0x12340000
-in their addend field. The data would consist of:
 
-*+
+DESCRIPTION
+	This whould create two relocs, both pointing to _foo, and with
+	0x12340000 in their addend field. The data would consist of:
 
+EXAMPLE
 RELOCATION RECORDS FOR [.text]:
-OFFSET   TYPE      VALUE 
+offset   type      value 
 00000002 HVRT16    _foo+0x12340000
 00000006 LVRT16    _foo+0x12340000
 
 00000000 5da05678           ; or.u r13,r0,0x5678
 00000004 1c4d5678           ; ld.b r2,r13,0x5678
 00000008 f400c001           ; jmp r1
-*-
-The relocation routine digs out the value from the data, adds it to
-the addend to get the original offset and then adds the value of _foo.
-Note that all 32 bits have to be kept around somewhere, to cope with
-carry from bit 15 to bit 16.
-
-On further example is the sparc and the a.out format. The sparc has a
-similar problem to the 88k, in that some instructions don't have
-room for an entire offset, but on the sparc the parts are created odd
-sized lumps. The designers of the a.out format chose not to use the
-data within the section for storing part of the offset; all the offset
-is kept within the reloc. Any thing in the data should be ignored.
-
-*+
+
+DESCRIPTION
+	The relocation routine digs out the value from the data, adds
+	it to the addend to get the original offset and then adds the
+	value of _foo. Note that all 32 bits have to be kept around
+	somewhere, to cope with carry from bit 15 to bit 16.
+
+	On further example is the sparc and the a.out format. The
+	sparc has a similar problem to the 88k, in that some
+	instructions don't have room for an entire offset, but on the
+	sparc the parts are created odd sized lumps. The designers of
+	the a.out format chose not to use the data within the section
+	for storing part of the offset; all the offset is kept within
+	the reloc. Any thing in the data should be ignored. 
+EXAMPLE
         save %sp,-112,%sp
         sethi %hi(_foo+0x12345678),%g2
         ldsb [%g2+%lo(_foo+0x12345678)],%i0
         ret
         restore
-*-
-Both relocs contains a pointer to foo, and the offsets would contain junk.
 
-*+
+DESCRIPTION
+	Both relocs contains a pointer to foo, and the offsets would
+	contain junk.
+
+EXAMPLE
+
 RELOCATION RECORDS FOR [.text]:
-OFFSET   TYPE      VALUE 
+offset   type      value 
 00000004 HI22      _foo+0x12345678
 00000008 LO10      _foo+0x12345678
 
@@ -237,198 +245,214 @@ OFFSET   TYPE      VALUE
 00000008 f048a000     ; ldsb [%g2+%lo(_foo+0)],%i0
 0000000c 81c7e008     ; ret
 00000010 81e80000     ; restore
-*-
-@item section  
-The section field is only used when the symbol pointer field is null.
-It supplies the section into which the data should be relocated. The
-field's main use comes from assemblers which do most of the symbol fixups
-themselves; an assembler may take an internal reference to a label,
-but since it knows where the label is, it can turn the relocation
-request from a symbol lookup into a section relative relocation - the
-relocation emitted has no symbol, just a section to relocate against.
-
-I'm not sure what it means when both a symbol pointer an a section
-pointer are present. Some formats use this sort of mechanism to
-describe PIC relocations, but BFD can't to that sort of thing yet.
-@item howto
-The howto field can be imagined as a relocation instruction. It is a
-pointer to a struct which contains information on what to do with all
-the other information in the reloc record and data section. A back end
-would normally have a relocation instruction set and turn relocations
-into pointers to the correct structure on input - but it would be
-possible to create each howto field on demand.
-@end table
+
+DESCRIPTION
+
+	o section  
+	The section field is only used when the symbol pointer field
+	is null. It supplies the section into which the data should be
+	relocated. The field's main use comes from assemblers which do
+	most of the symbol fixups themselves; an assembler may take an
+	internal reference to a label, but since it knows where the
+	label is, it can turn the relocation request from a symbol
+	lookup into a section relative relocation - the relocation
+	emitted has no symbol, just a section to relocate against. I'm
+	not sure what it means when both a symbol pointer an a section
+	pointer are present. Some formats use this sort of mechanism
+	to describe PIC relocations, but BFD can't to that sort of
+	thing yet. @item howto The howto field can be imagined as a
+	relocation instruction. It is a pointer to a struct which
+	contains information on what to do with all the other
+	information in the reloc record and data section. A back end
+	would normally have a relocation instruction set and turn
+	relocations into pointers to the correct structure on input -
+	but it would be possible to create each howto field on demand.
+	
 */
 
 
-/*proto* reloc_howto_type
-The @code{reloc_howto_type} is a structure which contains all the
-information that BFD needs to know to tie up a back end's data.
+/*
+SUBSUBSECTION 
+	<<reloc_howto_type>>
 
-*+++
+DESCRIPTION
+	The <<reloc_howto_type>> is a structure which contains all the
+	information that BFD needs to know to tie up a back end's data.
 
-$typedef CONST struct reloc_howto_struct 
-${ 
-The type field has mainly a documetary use - the back end can to what
-it wants with it, though the normally the back end's external idea of
-what a reloc number would be would be stored in this field. For
-example, the a PC relative word relocation in a coff environment would
-have the type 023 - because that's what the outside world calls a
-R_PCRWORD reloc.
+.typedef CONST struct reloc_howto_struct 
+.{ 
+	The type field has mainly a documetary use - the back end can
+	to what it wants with it, though the normally the back end's
+	external idea of what a reloc number would be would be stored
+	in this field. For example, the a PC relative word relocation
+	in a coff environment would have the type 023 - because that's
+	what the outside world calls a R_PCRWORD reloc.
 
-$  unsigned int type;
+.  unsigned int type;
 
-The value the final relocation is shifted right by. This drops
-unwanted data from the relocation. 
+	The value the final relocation is shifted right by. This drops
+	unwanted data from the relocation.  
 
-$  unsigned int rightshift;
+.  unsigned int rightshift;
 
-The size of the item to be relocated - 0, is one byte, 1 is 2 bytes, 3
-is four bytes.
+	The size of the item to be relocated - 0, is one byte, 1 is 2
+	bytes, 3 is four bytes.
 
-$  unsigned int size;
+.  unsigned int size;
 
-Now obsolete
+	Now obsolete
 
-$  unsigned int bitsize;
+.  unsigned int bitsize;
 
-Notes that the relocation is relative to the location in the data
-section of the addend. The relocation function will subtract from the
-relocation value the address of the location being relocated.
+	Notes that the relocation is relative to the location in the
+	data section of the addend. The relocation function will
+	subtract from the relocation value the address of the location
+	being relocated.
 
-$  boolean pc_relative;
+.  boolean pc_relative;
 
-Now obsolete
+	Now obsolete
 
-$  unsigned int bitpos;
+.  unsigned int bitpos;
 
-Now obsolete
+	Now obsolete
 
-$  boolean absolute;
+.  boolean absolute;
 
-Causes the relocation routine to return an error if overflow is
-detected when relocating.
+	Causes the relocation routine to return an error if overflow
+	is detected when relocating.
 
-$  boolean complain_on_overflow;
+.  boolean complain_on_overflow;
 
-If this field is non null, then the supplied function is called rather
-than the normal function. This allows really strange relocation
-methods to be accomodated (eg, i960 callj instructions).
+	If this field is non null, then the supplied function is
+	called rather than the normal function. This allows really
+	strange relocation methods to be accomodated (eg, i960 callj
+	instructions).
 
-$  bfd_reloc_status_enum_type (*special_function)();
+.  bfd_reloc_status_type (*special_function)();
 
-The textual name of the relocation type.
+	The textual name of the relocation type.
 
-$  char *name;
+.  char *name;
 
-When performing a partial link, some formats must modify the
-relocations rather than the data - this flag signals this.
+	When performing a partial link, some formats must modify the
+	relocations rather than the data - this flag signals this.
 
-$  boolean partial_inplace;
+.  boolean partial_inplace;
 
-The src_mask is used to select what parts of the read in data are to
-be used in the relocation sum. Eg, if this was an 8 bit bit of data
-which we read and relocated, this would be 0x000000ff. When we have
-relocs which have an addend, such as sun4 extended relocs, the value
-in the offset part of a relocating field is garbage so we never use
-it. In this case the mask would be 0x00000000.
+	The src_mask is used to select what parts of the read in data
+	are to be used in the relocation sum. Eg, if this was an 8 bit
+	bit of data which we read and relocated, this would be
+	0x000000ff. When we have relocs which have an addend, such as
+	sun4 extended relocs, the value in the offset part of a
+	relocating field is garbage so we never use it. In this case
+	the mask would be 0x00000000. 
+.  bfd_word src_mask;
 
-$  bfd_word src_mask;
-The dst_mask is what parts of the instruction are replaced into the
-instruction. In most cases src_mask == dst_mask, except in the above
-special case, where dst_mask would be 0x000000ff, and src_mask would
-be 0x00000000.
+	The dst_mask is what parts of the instruction are replaced
+	into the instruction. In most cases src_mask == dst_mask,
+	except in the above special case, where dst_mask would be
+	0x000000ff, and src_mask would be 0x00000000.
+.  bfd_word dst_mask;           
 
-$  bfd_word dst_mask;           
+	When some formats create PC relative instructions, they leave
+	the value of the pc of the place being relocated in the offset
+	slot of the instruction, so that a PC relative relocation can
+	be made just by adding in an ordinary offset (eg sun3 a.out).
+	Some formats leave the displacement part of an instruction
+	empty (eg m88k bcs), this flag signals the fact.
+.  boolean pcrel_offset;
+.} reloc_howto_type;
 
-When some formats create PC relative instructions, they leave the
-value of the pc of the place being relocated in the offset slot of the
-instruction, so that a PC relative relocation can be made just by
-adding in an ordinary offset (eg sun3 a.out). Some formats leave the
-displacement part of an instruction empty (eg m88k bcs), this flag
-signals the fact.
+*/
 
-$  boolean pcrel_offset;
-$} reloc_howto_type;
-*---
+/*
+FUNCTION
+	HOWTO
+DESCRIPTION
+	The HOWTO define is horrible and will go away.
+
+
+.#define HOWTO(C, R,S,B, P, BI, ABS, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
+.  {(unsigned)C,R,S,B, P, BI, ABS,O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}
+
+DESCRIPTION
+	And will be replaced with the totally magic way. But for the
+	moment, we are compatible, so do it this way..
+
+
+.#define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,false,false,FUNCTION, NAME,false,0,0,IN)
+.
+DESCRIPTION
+	Helper routine to turn a symbol into a relocation value.
+
+.#define HOWTO_PREPARE(relocation, symbol) 	\
+.  {						\
+.  if (symbol != (asymbol *)NULL) {		\
+.    if (symbol->flags & BSF_FORT_COMM) {	\
+.      relocation = 0;				\
+.    }						\
+.    else {					\
+.      relocation = symbol->value;		\
+.    }						\
+.  }						\
+.  if (symbol->section != (asection *)NULL) {	\
+.    relocation += symbol->section->output_section->vma +	\
+.      symbol->section->output_offset;		\
+.  }						\
+.}			
 
 */
 
-/*proto* HOWTO
-The HOWTO define is horrible and will go away.
-*+
-#define HOWTO(C, R,S,B, P, BI, ABS, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
-  {(unsigned)C,R,S,B, P, BI, ABS,O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}
-*-
-
-And will be replaced with the totally magic way. But for the moment,
-we are compatible, so do it this way..
-
-*+
-#define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,false,false,FUNCTION, NAME,false,0,0,IN)
-*-
-
-Helper routine to turn a symbol into a relocation value.
-
-*+
-
-
-#define HOWTO_PREPARE(relocation, symbol) 	\
-  {						\
-  if (symbol != (asymbol *)NULL) {		\
-    if (symbol->flags & BSF_FORT_COMM) {	\
-      relocation = 0;				\
-    }						\
-    else {					\
-      relocation = symbol->value;		\
-    }						\
-  }						\
-  if (symbol->section != (asection *)NULL) {	\
-    relocation += symbol->section->output_section->vma +	\
-      symbol->section->output_offset;		\
-  }						\
-}			
-*-
-*/
+/*
+TYPEDEF
+	reloc_chain
 
-/*proto* reloc_chain
-*+
-typedef unsigned char bfd_byte;
+DESCRIPTION
 
-typedef struct relent_chain {
-  arelent relent;
-  struct   relent_chain *next;
-} arelent_chain;
+	How relocs are tied together
 
-*-
+.typedef unsigned char bfd_byte;
+.
+.typedef struct relent_chain {
+.  arelent relent;
+.  struct   relent_chain *next;
+.} arelent_chain;
 
 */
 
 
 
-/*proto*
-If an output_bfd is supplied to this function the generated image
-will be relocatable, the relocations are copied to the output file
-after they have been changed to reflect the new state of the world.
-There are two ways of reflecting the results of partial linkage in an
-output file; by modifying the output data in place, and by modifying
-the relocation record. Some native formats (eg basic a.out and basic
-coff) have no way of specifying an addend in the relocation type, so
-the addend has to go in the output data.  This is no big deal since in
-these formats the output data slot will always be big enough for the
-addend. Complex reloc types with addends were invented to solve just
-this problem.
-*; PROTO(bfd_reloc_status_enum_type,
-                bfd_perform_relocation,
+/*
+FUNCTION 
+	bfd_perform_relocation
+
+DESCRIPTION
+	If an output_bfd is supplied to this function the generated
+	image will be relocatable, the relocations are copied to the
+	output file after they have been changed to reflect the new
+	state of the world. There are two ways of reflecting the
+	results of partial linkage in an output file; by modifying the
+	output data in place, and by modifying the relocation record.
+	Some native formats (eg basic a.out and basic coff) have no
+	way of specifying an addend in the relocation type, so the
+	addend has to go in the output data.  This is no big deal
+	since in these formats the output data slot will always be big
+	enough for the addend. Complex reloc types with addends were
+	invented to solve just this problem.
+
+SYNOPSIS
+	bfd_reloc_status_type
+                bfd_perform_relocation
                         (bfd * abfd,
                         arelent *reloc_entry,
                         PTR data,
                         asection *input_section,
-                        bfd *output_bfd));
+                        bfd *output_bfd);
 */
 
 
-bfd_reloc_status_enum_type
+bfd_reloc_status_type
 DEFUN(bfd_perform_relocation,(abfd,
                               reloc_entry,
                               data,
@@ -441,7 +465,7 @@ DEFUN(bfd_perform_relocation,(abfd,
       bfd *output_bfd)
 {
   bfd_vma relocation;
-  bfd_reloc_status_enum_type flag = bfd_reloc_ok;
+  bfd_reloc_status_type flag = bfd_reloc_ok;
   bfd_vma addr = reloc_entry->address ;
   bfd_vma output_base = 0;
   reloc_howto_type *howto = reloc_entry->howto;
@@ -460,7 +484,7 @@ DEFUN(bfd_perform_relocation,(abfd,
   }
 
   if (howto->special_function){
-    bfd_reloc_status_enum_type cont;
+    bfd_reloc_status_type cont;
     cont = howto->special_function(abfd,
                                    reloc_entry,
                                    symbol,
@@ -671,67 +695,120 @@ DEFUN(bfd_perform_relocation,(abfd,
 
 
 
-/*doc*
+/*
+@node howto manager,  , typedef arelent, Relocations
+SECTION
+	The howto manager 
 
-@section The howto manager 
+DESCRIPTION
+	When an application wants to create a relocation, but doesn't
+	know what the target machine might call it, it can find out by
+	using this bit of code.
 
+*/
 
-When an application wants to create a relocation, but doesn't know
-what the target machine might call it, it can find out by using this
-bit of code.
+/*
+TYPEDEF
+	bfd_reloc_code_type
 
-*/
+DESCRIPTION
+	The insides of a reloc code
+
+.typedef enum bfd_reloc_code_real {
+
+	16 bits wide, simple reloc 
 
-/*proto* bfd_reloc_code_enum_type
+.  BFD_RELOC_16,	
 
-*+++
+	8 bits wide, but used to form an address like 0xffnn
 
-$typedef enum 
-${
+.  BFD_RELOC_8_FFnn,
 
-16 bits wide, simple reloc 
+	8 bits wide, simple
 
-$  BFD_RELOC_16,	
+.  BFD_RELOC_8,
 
-8 bits wide, but used to form an address like 0xffnn
+	8 bits wide, pc relative
 
-$  BFD_RELOC_8_FFnn,
+.  BFD_RELOC_8_PCREL,
 
-8 bits wide, simple
+	The type of reloc used to build a contructor table - at the
+	moment probably a 32 bit wide abs address, but the cpu can
+	choose.
 
-$  BFD_RELOC_8,
+.  BFD_RELOC_CTOR
 
-8 bits wide, pc relative
+. } bfd_reloc_code_real_type;
 
-$  BFD_RELOC_8_PCREL
-$ } bfd_reloc_code_enum_real_type;
 
-*---
 
 */
 
 
 
-/*proto* bfd_reloc_type_lookup
-This routine returns a pointer to a howto struct which when invoked,
-will perform the supplied relocation on data from the architecture
-noted.
+/*
+SECTION
+	bfd_reloc_type_lookup
 
-[Note] This function will go away.
+DESCRIPTION
+	This routine returns a pointer to a howto struct which when
+	invoked, will perform the supplied relocation on data from the
+	architecture noted.
 
-*; PROTO(CONST struct reloc_howto_struct *,
-	bfd_reloc_type_lookup,
-	(CONST bfd_arch_info_struct_type *arch, bfd_reloc_code_enum_type code));
+SYNOPSIS
+	CONST struct reloc_howto_struct *
+	bfd_reloc_type_lookup
+	(CONST bfd_arch_info_type *arch, bfd_reloc_code_type code);
 */
 
 
 CONST struct reloc_howto_struct *
 DEFUN(bfd_reloc_type_lookup,(arch, code),
-	CONST bfd_arch_info_struct_type *arch  AND
-	bfd_reloc_code_enum_type code)
+	CONST bfd_arch_info_type *arch  AND
+	bfd_reloc_code_type code)
 {
   return arch->reloc_type_lookup(arch, code);
 }
 
+static reloc_howto_type bfd_howto_32 =
+ HOWTO(0, 00,2,32,false,0,false,true,0,"VRT32", false,0xffffffff,0xffffffff,true);
 
 
+/*
+INTERNAL FUNCTION
+	bfd_default_reloc_type_lookup
+
+DESCRIPTION
+	Provides a default relocation lookuperer for any architectue 
+
+SYNOPSIS
+	CONST struct reloc_howto_struct *bfd_default_reloc_type_lookup
+	(CONST struct bfd_arch_info *,
+         bfd_reloc_code_type  code);
+
+*/
+CONST struct reloc_howto_struct *
+DEFUN(bfd_default_reloc_type_lookup,(arch,  code),
+     CONST struct bfd_arch_info *arch AND
+      bfd_reloc_code_type  code)
+{
+    switch (code) 
+    {
+       case BFD_RELOC_CTOR:
+	/* The type of reloc used in a ctor, which will be as wide as the
+	   address - so either a 64, 32, or 16 bitter.. */
+	switch (arch->bits_per_address) {
+	   case 64:
+	    BFD_FAIL();
+	   case 32:
+	    return &bfd_howto_32;
+	   case 16:
+	    BFD_FAIL();
+	   default:
+	    BFD_FAIL();
+	}
+       default:
+	BFD_FAIL();
+    }
+return (struct reloc_howto_struct *)NULL;
+}
diff --git a/bfd/syms.c b/bfd/syms.c
index c6a2b39..795a4a2 100644
--- a/bfd/syms.c
+++ b/bfd/syms.c
@@ -18,33 +18,34 @@ You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
-/*doc*
-@section Symbols
-BFD trys to maintain as much symbol information as it can when it
-moves information from file to file. BFD passes information to
-applications though the @code{asymbol} structure. When the application
-requests the symbol table, BFD reads the table in the native form and
-translates parts of it into the internal format. To maintain more than
-the infomation passed to applications some targets keep
-some information 'behind the sceans', in a structure only the
-particular back end knows about. For example, the coff back end keeps
-the original symbol table structure as well as the canonical structure
-when a BFD is read in. On output, the coff back end can reconstruct
-the output symbol table so that no information is lost, even
-information unique to coff which BFD doesn't know or understand. If a
-coff symbol table was read, but was written through an a.out back end,
-all the coff specific information would be lost. (.. until BFD 2 :).
-
-The symbol table of a BFD is not necessarily read in until a
-canonicalize request is made. Then the BFD back end fills in a table
-provided by the application with pointers to the canonical
-information.
-
-To output symbols, the application provides BFD with a table of
-pointers to pointers to @code{asymbol}s. This allows applications like
-the linker to output a symbol as read, since the 'behind the sceens'
-information will be still available.
-
+/*
+SECTION
+	Symbols
+
+DESCRIPTION
+	BFD trys to maintain as much symbol information as it can when
+	it moves information from file to file. BFD passes information
+	to applications though the <<asymbol>> structure. When the
+	applicationrequests the symbol table, BFD reads the table in
+	the native form and translates parts of it into the internal
+	format. To maintain more than the infomation passed to
+	applications some targets keep some information 'behind the
+	sceans', in a structure only the particular back end knows
+	about. For example, the coff back end keeps the original
+	symbol table structure as well as the canonical structure when
+	a BFD is read in. On output, the coff back end can reconstruct
+	the output symbol table so that no information is lost, even
+	information unique to coff which BFD doesn't know or
+	understand. If a coff symbol table was read, but was written
+	through an a.out back end, all the coff specific information
+	would be lost. (.. until BFD 2 :).  The symbol table of a BFD
+	is not necessarily read in until a canonicalize request is
+	made. Then the BFD back end fills in a table provided by the
+	application with pointers to the canonical information.  To
+	output symbols, the application provides BFD with a table of
+	pointers to pointers to <<asymbol>>s. This allows applications
+	like the linker to output a symbol as read, since the 'behind
+	the sceens' information will be still available. 
 @menu
 * Reading Symbols::
 * Writing Symbols::
@@ -53,12 +54,16 @@ information will be still available.
 @end menu
 
 @node Reading Symbols, Writing Symbols, Symbols, Symbols
-@subsection Reading Symbols
-There are two stages to reading a symbol table from a BFD; allocating
-storage, and the actual reading process. This is an excerpt from an
-appliction which reads the symbol table:
+SUBSECTION
+	Reading Symbols
+
+DESCRIPTION
+	There are two stages to reading a symbol table from a BFD;
+	allocating storage, and the actual reading process. This is an
+	excerpt from an appliction which reads the symbol table:
+
+EXAMPLE
 
-*+
   unsigned int storage_needed;
   asymbol **symbol_table;
   unsigned int number_of_symbols;
@@ -77,25 +82,29 @@ appliction which reads the symbol table:
   for (i = 0; i < number_of_symbols; i++) {
      process_symbol (symbol_table[i]);
   }
-*-
 
-All storage for the symbols themselves is in an obstack connected to
-the BFD, and is freed when the BFD is closed.
+DESCRIPTION
+
+	All storage for the symbols themselves is in an obstack
+	connected to the BFD, and is freed when the BFD is closed.
+
 
 @node Writing Symbols, typedef asymbol, Reading Symbols, Symbols
-@subsection Writing Symbols
-Writing of a symbol table is automatic when a BFD open for writing
-is closed. The application attaches a vector of pointers to pointers to symbols
-to the BFD being written, and fills in the symbol count. The close and
-cleanup code reads through the table provided and performs all the
-necessary operations. The outputing code must always be provided with
-an 'owned' symbol; one which has come from another BFD, or one which
-has been created using @code{bfd_make_empty_symbol}. 
-
-An example showing the creation of a symbol table with only one
-element:
-
-*+
+SUBSECTION
+	Writing Symbols
+
+DESCRIPTION
+	Writing of a symbol table is automatic when a BFD open for
+	writing is closed. The application attaches a vector of
+	pointers to pointers to symbols to the BFD being written, and
+	fills in the symbol count. The close and cleanup code reads
+	through the table provided and performs all the necessary
+	operations. The outputing code must always be provided with an
+	'owned' symbol; one which has come from another BFD, or one
+	which has been created using <<bfd_make_empty_symbol>>.   An
+	example showing the creation of a symbol table with only one element:
+
+EXAMPLE
 #include "bfd.h"
 main() 
 {
@@ -123,12 +132,13 @@ nm foo
 00012345 A dummy_symbol
 
 
-*-
+DESCRIPTION
+	Many formats cannot represent arbitary symbol information; for
+ 	instance the <<a.out>> object format does not allow an
+	arbitary number of sections. A symbol pointing to a section
+	which is not one  of <<.text>>, <<.data>> or <<.bss>> cannot
+	be described. 
 
-Many formats cannot represent arbitary symbol information; for
-instance the @code{a.out} object format does not allow an arbitary
-number of sections. A symbol pointing to a section which is not one of
-@code{.text}, @code{.data} or @code{.bss} cannot be described.
 */
 
 
@@ -136,130 +146,131 @@ number of sections. A symbol pointing to a section which is not one of
 @node typedef asymbol, symbol handling functions, Writing Symbols, Symbols
 
 */
-/*proto*
-@subsection typedef asymbol
-An @code{asymbol} has the form:
+/*
+TYPEDEF
+	typedef asymbol
 
-*+++
+DESCRIPTION
+	An <<asymbol>> has the form:
 
-$typedef struct symbol_cache_entry 
-${
-A pointer to the BFD which owns the symbol. This information is
-necessary so that a back end can work out what additional (invisible to
-the application writer) information is carried with the symbol. 
+.typedef struct symbol_cache_entry 
+.{
+	A pointer to the BFD which owns the symbol. This information
+	is necessary so that a back end can work out what additional
+	(invisible to the application writer) information is carried
+	with the symbol. 
 
-$  struct _bfd *the_bfd;
+.  struct _bfd *the_bfd;
 
 The text of the symbol. The name is left alone, and not copied - the
 application may not alter it. 
 
-$   CONST char *name;
+.   CONST char *name;
 
 The value of the symbol.
 
-$   symvalue value;
+.   symvalue value;
 
 Attributes of a symbol:
 
-$#define BSF_NO_FLAGS    0x00
+.#define BSF_NO_FLAGS    0x00
 
-The symbol has local scope; @code{static} in @code{C}. The value is
+The symbol has local scope; <<static>> in <<C>>. The value is
 the offset into the section of the data.
 
-$#define BSF_LOCAL	0x01
+.#define BSF_LOCAL	0x01
 
-The symbol has global scope; initialized data in @code{C}. The value
+The symbol has global scope; initialized data in <<C>>. The value
 is the offset into the section of the data.
 
-$#define BSF_GLOBAL	0x02
+.#define BSF_GLOBAL	0x02
 
 Obsolete
 
-$#define BSF_IMPORT	0x04
+.#define BSF_IMPORT	0x04
 
 The symbol has global scope, and is exported. The value is the offset
 into the section of the data.
 
-$#define BSF_EXPORT	0x08
+.#define BSF_EXPORT	0x08
 
-The symbol is undefined. @code{extern} in @code{C}. The value has no meaning.
+The symbol is undefined. <<extern>> in <<C>>. The value has no meaning.
 
-$#define BSF_UNDEFINED	0x10	
+.#define BSF_UNDEFINED	0x10	
 
-The symbol is common, initialized to zero; default in @code{C}. The
+The symbol is common, initialized to zero; default in <<C>>. The
 value is the size of the object in bytes.
 
-$#define BSF_FORT_COMM	0x20	
+.#define BSF_FORT_COMM	0x20	
 
-A normal @code{C} symbol would be one of:
-@code{BSF_LOCAL}, @code{BSF_FORT_COMM},  @code{BSF_UNDEFINED} or @code{BSF_EXPORT|BSD_GLOBAL}
+A normal <<C>> symbol would be one of:
+<<BSF_LOCAL>>, <<BSF_FORT_COMM>>,  <<BSF_UNDEFINED>> or <<BSF_EXPORT|BSD_GLOBAL>>
 
 The symbol is a debugging record. The value has an arbitary meaning.
 
-$#define BSF_DEBUGGING	0x40
+.#define BSF_DEBUGGING	0x40
 
 The symbol has no section attached, any value is the actual value and
 is not a relative offset to a section.
 
-$#define BSF_ABSOLUTE	0x80
+.#define BSF_ABSOLUTE	0x80
 
 Used by the linker
 
-$#define BSF_KEEP        0x10000
-$#define BSF_KEEP_G      0x80000
+.#define BSF_KEEP        0x10000
+.#define BSF_KEEP_G      0x80000
 
 Unused
 
-$#define BSF_WEAK        0x100000
-$#define BSF_CTOR        0x200000 
-$#define BSF_FAKE        0x400000 
+.#define BSF_WEAK        0x100000
+.#define BSF_CTOR        0x200000 
+.#define BSF_FAKE        0x400000 
 
 The symbol used to be a common symbol, but now it is allocated.
 
-$#define BSF_OLD_COMMON  0x800000  
+.#define BSF_OLD_COMMON  0x800000  
 
 The default value for common data.
 
-$#define BFD_FORT_COMM_DEFAULT_VALUE 0
+.#define BFD_FORT_COMM_DEFAULT_VALUE 0
 
 In some files the type of a symbol sometimes alters its location
-in an output file - ie in coff a @code{ISFCN} symbol which is also @code{C_EXT}
+in an output file - ie in coff a <<ISFCN>> symbol which is also <<C_EXT>>
 symbol appears where it was declared and not at the end of a section. 
 This bit is set by the target BFD part to convey this information. 
 
-$#define BSF_NOT_AT_END    0x40000
+.#define BSF_NOT_AT_END    0x40000
 
 Signal that the symbol is the label of constructor section.
 
-$#define BSF_CONSTRUCTOR   0x1000000
+.#define BSF_CONSTRUCTOR   0x1000000
 
 Signal that the symbol is a warning symbol. If the symbol is a warning
 symbol, then the value field (I know this is tacky) will point to the
 asymbol which when referenced will cause the warning.
 
-$#define BSF_WARNING       0x2000000
+.#define BSF_WARNING       0x2000000
 
 Signal that the symbol is indirect. The value of the symbol is a
 pointer to an undefined asymbol which contains the name to use
 instead.
 
-$#define BSF_INDIRECT     0x4000000
+.#define BSF_INDIRECT     0x4000000
 
-$  flagword flags;
+.  flagword flags;
 
 A pointer to the section to which this symbol is relative, or 0 if the
 symbol is absolute or undefined. Note that it is not sufficient to set
 this location to 0 to mark a symbol as absolute - the flag
-@code{BSF_ABSOLUTE} must be set also.
+<<BSF_ABSOLUTE>> must be set also.
 
-$  struct sec *section;
+.  struct sec *section;
 
 Back end special data. This is being phased out in favour of making
 this a union.
 
-$  PTR udata;	
-$} asymbol;
-*---
+.  PTR udata;	
+.} asymbol;
 
 */
 
@@ -268,44 +279,57 @@ $} asymbol;
 #include "libbfd.h"
 #include "stab.gnu.h"
  
-/*doc*
+/*
 @node symbol handling functions,  , typedef asymbol, Symbols
-@subsection Symbol Handling Functions
+SUBSECTION
+	Symbol Handling Functions
 
 */
 
-/*proto* get_symtab_upper_bound
-Returns the number of bytes required in a vector of pointers to
-@code{asymbols} for all the symbols in the supplied BFD, including a
-terminal NULL pointer. If there are no symbols in the BFD, then 0 is
-returned.
-*+
-#define get_symtab_upper_bound(abfd) \
-     BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
-*-
+/*
+FUNCTION
+	get_symtab_upper_bound
+
+DESCRIPTION
+	Returns the number of bytes required in a vector of pointers
+	to <<asymbols>> for all the symbols in the supplied BFD,
+	including a terminal NULL pointer. If there are no symbols in
+	the BFD, then 0 is returned.
+
+.#define get_symtab_upper_bound(abfd) \
+.     BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
 
 */
 
-/*proto* bfd_canonicalize_symtab
-Supplied a BFD and a pointer to an uninitialized vector of pointers.
-This reads in the symbols from the BFD, and fills in the table with
-pointers to the symbols, and a trailing NULL. The routine returns the
-actual number of symbol pointers not including the NULL.
+/*
+FUNCTION
+	bfd_canonicalize_symtab
+
+DESCRIPTION
+	Supplied a BFD and a pointer to an uninitialized vector of
+	pointers. This reads in the symbols from the BFD, and fills in
+	the table with pointers to the symbols, and a trailing NULL.
+	The routine returns the actual number of symbol pointers not
+	including the NULL.
 
-*+
-#define bfd_canonicalize_symtab(abfd, location) \
-     BFD_SEND (abfd, _bfd_canonicalize_symtab,\
-                  (abfd, location))
 
-*-
+.#define bfd_canonicalize_symtab(abfd, location) \
+.     BFD_SEND (abfd, _bfd_canonicalize_symtab,\
+.                  (abfd, location))
+
 */
 
 
-/*proto* bfd_set_symtab
-Provided a table of pointers to symbols and a count, writes to the
-output BFD the symbols when closed.
+/*
+FUNCTION
+	bfd_set_symtab
+
+DESCRIPTION
+	Provided a table of pointers to symbols and a count, writes to
+	the output BFD the symbols when closed.
 
-*; PROTO(boolean, bfd_set_symtab, (bfd *, asymbol **, unsigned int ));
+SYNOPSIS
+	boolean bfd_set_symtab (bfd *, asymbol **, unsigned int );
 */
 
 boolean
@@ -324,10 +348,15 @@ bfd_set_symtab (abfd, location, symcount)
   return true;
 }
 
-/*proto* bfd_print_symbol_vandf
-Prints the value and flags of the symbol supplied to the stream file.
+/*
+FUNCTION
+	bfd_print_symbol_vandf
 
-*; PROTO(void, bfd_print_symbol_vandf, (PTR file, asymbol *symbol));
+DESCRIPTION
+	Prints the value and flags of the symbol supplied to the stream file.
+
+SYNOPSIS
+	void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
 */
 void
 DEFUN(bfd_print_symbol_vandf,(file, symbol),
@@ -358,24 +387,33 @@ asymbol *symbol)
 }
 
 
-/*proto*  bfd_make_empty_symbol
-This function creates a new @code{asymbol} structure for the BFD, and
-returns a pointer to it.
+/*
+FUNCTION
+	bfd_make_empty_symbol
+
+DESCRIPTION
+	This function creates a new <<asymbol>> structure for the BFD,
+	and returns a pointer to it.
 
-This routine is necessary, since each back end has private information
-surrounding the @code{asymbol}. Building your own @code{asymbol} and
-pointing to it will not create the private information, and will cause
-problems later on.
-*+
-#define bfd_make_empty_symbol(abfd) \
-     BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
-*-
+	This routine is necessary, since each back end has private
+	information surrounding the <<asymbol>>. Building your own
+	<<asymbol>> and pointing to it will not create the private
+	information, and will cause problems later on.
+
+.#define bfd_make_empty_symbol(abfd) \
+.     BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
 */
 
-/*proto* bfd_decode_symclass
-Return a lower-case character corresponding to the symbol class of symbol.
+/*
+FUNCTION
+	bfd_decode_symclass
+
+DESCRIPTION
+	Return a lower-case character corresponding to the symbol
+	class of symbol.
 
-*; PROTO(int, bfd_decode_symclass, (asymbol *symbol));
+SYNOPSIS
+	int bfd_decode_symclass(asymbol *symbol);
 */
 int
 DEFUN(bfd_decode_symclass,(symbol),
diff --git a/bfd/targets.c b/bfd/targets.c
index 70c69ad..4e0bbcd 100644
--- a/bfd/targets.c
+++ b/bfd/targets.c
@@ -24,302 +24,309 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 #include "sysdep.h"
 #include "libbfd.h"
 
-/*doc*
-@section Targets
-Each port of BFD to a different machine requries the creation of a
-target back end. All the back end provides to the root part of BFD is
-a structure containing pointers to functions which perform certain low
-level operations on files. BFD translates the applications's requests
-through a pointer into calls to the back end routines.
-
-When a file is opened with @code{bfd_openr}, its format and target are
-unknown. BFD uses various mechanisms to determine how to interpret the
-file. The operations performed are:
-@itemize @bullet
-@item
-First a BFD is created by calling the internal routine
-@code{new_bfd}, then @code{bfd_find_target} is called with the target
-string supplied to @code{bfd_openr} and the new BFD pointer. 
-@item
-If a null target string was provided to
-@code{bfd_find_target}, it looks up the environment variable
-@code{GNUTARGET} and uses that as the target string. 
-@item
-If the target string is still NULL, or the target string
-is @code{default}, then the first item in the target vector is used as
-the target type. @xref{bfd_target}.
-@item
-Otherwise, the elements in the target vector are
-inspected one by one, until a match on target name is found. When
-found, that is used.
-@item 
-Otherwise the error @code{invalid_target} is returned to
-@code{bfd_openr}.
-@item 
-@code{bfd_openr} attempts to open the file using
-@code{bfd_open_file}, and returns the BFD.
-@end itemize
-Once the BFD has been opened and the target selected, the file format
-may be determined. This is done by calling @code{bfd_check_format} on
-the BFD with a suggested format. The routine returns @code{true} when
-the application guesses right.
-
+/*
+SECTION 
+	Targets
+
+DESCRIPTION
+	Each port of BFD to a different machine requries the creation
+	of a target back end. All the back end provides to the root
+	part of BFD is a structure containing pointers to functions
+	which perform certain low level operations on files. BFD
+	translates the applications's requests through a pointer into
+	calls to the back end routines. 
+
+	When a file is opened with <<bfd_openr>>, its format and
+	target are unknown. BFD uses various mechanisms to determine
+	how to interpret the file. The operations performed are:
+
+	o First a BFD is created by calling the internal routine
+	<<new_bfd>>, then <<bfd_find_target>> is called with the
+	target string supplied to <<bfd_openr>> and the new BFD pointer. 
+
+	o If a null target string was provided to <<bfd_find_target>>,
+	it looks up the environment variable <<GNUTARGET>> and uses
+	that as the target string. 
+
+	o If the target string is still NULL, or the target string is
+	<<default>>, then the first item in the target vector is used
+	as the target type. @xref{bfd_target}.
+
+	o Otherwise, the elements in the target vector are inspected
+	one by one, until a match on target name is found. When found,
+	that is used. 
+
+	o Otherwise the error <<invalid_target>> is returned to
+	<<bfd_openr>>.
+
+	o <<bfd_openr>> attempts to open the file using
+	<<bfd_open_file>>, and returns the BFD.
+
+	Once the BFD has been opened and the target selected, the file
+	format may be determined. This is done by calling
+	<<bfd_check_format>> on the BFD with a suggested format. The
+	routine returns <<true>> when the application guesses right.
 @menu
 * bfd_target::
 @end menu
 */
 
 
-/*proto* bfd_target
+/*
+
 @node bfd_target,  , Targets, Targets
-@subsection bfd_target
-This structure contains everything that BFD knows about a target.
-It includes things like its byte order, name, what routines to call
-to do various operations, etc.   
 
-Every BFD points to a target structure with its "xvec" member. 
+SUBSECTION
+	bfd_target
+
+DESCRIPTION
+	This structure contains everything that BFD knows about a
+	target. It includes things like its byte order, name, what
+	routines to call to do various operations, etc.   
 
+	Every BFD points to a target structure with its <<xvec>>
+	member. 
 
-Shortcut for declaring fields which are prototyped function pointers,
-while avoiding anguish on compilers that don't support protos.
+	Shortcut for declaring fields which are prototyped function
+	pointers, while avoiding anguish on compilers that don't
+	support protos.
 
-$#define SDEF(ret, name, arglist) \
-$                PROTO(ret,(*name),arglist)
-$#define SDEF_FMT(ret, name, arglist) \
-$                PROTO(ret,(*name[bfd_type_end]),arglist)
+.#define SDEF(ret, name, arglist) \
+.                PROTO(ret,(*name),arglist)
+.#define SDEF_FMT(ret, name, arglist) \
+.                PROTO(ret,(*name[bfd_type_end]),arglist)
 
-These macros are used to dispatch to functions through the bfd_target
-vector. They are used in a number of macros further down in @file{bfd.h}, and
-are also used when calling various routines by hand inside the BFD
-implementation.  The "arglist" argument must be parenthesized; it
-contains all the arguments to the called function.
+	These macros are used to dispatch to functions through the
+	bfd_target vector. They are used in a number of macros further
+	down in @file{bfd.h}, and are also used when calling various
+	routines by hand inside the BFD implementation.  The "arglist"
+	argument must be parenthesized; it contains all the arguments
+	to the called function. 
 
-$#define BFD_SEND(bfd, message, arglist) \
-$               ((*((bfd)->xvec->message)) arglist)
 
-For operations which index on the BFD format 
+.#define BFD_SEND(bfd, message, arglist) \
+.               ((*((bfd)->xvec->message)) arglist)
 
-$#define BFD_SEND_FMT(bfd, message, arglist) \
-$            (((bfd)->xvec->message[(int)((bfd)->format)]) arglist)
+	For operations which index on the BFD format 
 
-This is the struct which defines the type of BFD this is.  The
-"xvec" member of the struct @code{bfd} itself points here.  Each module
-that implements access to a different target under BFD, defines
-one of these.
+.#define BFD_SEND_FMT(bfd, message, arglist) \
+.            (((bfd)->xvec->message[(int)((bfd)->format)]) arglist)
 
-FIXME, these names should be rationalised with the names of the
-entry points which call them. Too bad we can't have one macro to
-define them both! 
+	This is the struct which defines the type of BFD this is.  The
+	<<xvec>> member of the struct <<bfd>> itself points here.  Each
+	module that implements access to a different target under BFD,
+	defines one of these.
 
-*+++
 
-$typedef struct bfd_target
-${
+	FIXME, these names should be rationalised with the names of
+	the entry points which call them. Too bad we can't have one
+	macro to define them both! 
+
+.typedef struct bfd_target
+.{
 
 identifies the kind of target, eg SunOS4, Ultrix, etc 
 
-$  char *name;
+.  char *name;
 
 The "flavour" of a back end is a general indication about the contents
 of a file.
 
-$  enum target_flavour {
-$    bfd_target_unknown_flavour,
-$    bfd_target_aout_flavour,
-$    bfd_target_coff_flavour,
-$    bfd_target_elf_flavour,
-$    bfd_target_ieee_flavour,
-$    bfd_target_oasys_flavour,
-$    bfd_target_srec_flavour} flavour;
+.  enum target_flavour {
+.    bfd_target_unknown_flavour,
+.    bfd_target_aout_flavour,
+.    bfd_target_coff_flavour,
+.    bfd_target_elf_flavour,
+.    bfd_target_ieee_flavour,
+.    bfd_target_oasys_flavour,
+.    bfd_target_srec_flavour} flavour;
 
 The order of bytes within the data area of a file.
 
-$  boolean byteorder_big_p;
+.  boolean byteorder_big_p;
 
 The order of bytes within the header parts of a file.
 
-$  boolean header_byteorder_big_p;
+.  boolean header_byteorder_big_p;
 
 This is a mask of all the flags which an executable may have set -
-from the set @code{NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}.
+from the set <<NO_FLAGS>>, <<HAS_RELOC>>, ...<<D_PAGED>>.
 
-$  flagword object_flags;       
+.  flagword object_flags;       
 
 This is a mask of all the flags which a section may have set - from
-the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}.
+the set <<SEC_NO_FLAGS>>, <<SEC_ALLOC>>, ...<<SET_NEVER_LOAD>>.
 
-$  flagword section_flags;
+.  flagword section_flags;
 
 The pad character for filenames within an archive header.
 
-$  char ar_pad_char;            
+.  char ar_pad_char;            
 
 The maximum number of characters in an archive header.
 
-$ unsigned short ar_max_namelen;
+. unsigned short ar_max_namelen;
 
 The minimum alignment restriction for any section.
 
-$  unsigned int align_power_min;
+.  unsigned int align_power_min;
 
 Entries for byte swapping for data. These are different to the other
 entry points, since they don't take BFD as first arg.  Certain other handlers
 could do the same.
 
-$  SDEF (bfd_vma,      bfd_getx64, (bfd_byte *));
-$  SDEF (void,         bfd_putx64, (bfd_vma, bfd_byte *));
-$  SDEF (bfd_vma, bfd_getx32, (bfd_byte *));
-$  SDEF (void,         bfd_putx32, (bfd_vma, bfd_byte *));
-$  SDEF (bfd_vma, bfd_getx16, (bfd_byte *));
-$  SDEF (void,         bfd_putx16, (bfd_vma, bfd_byte *));
+.  SDEF (bfd_vma,      bfd_getx64, (bfd_byte *));
+.  SDEF (void,         bfd_putx64, (bfd_vma, bfd_byte *));
+.  SDEF (bfd_vma, bfd_getx32, (bfd_byte *));
+.  SDEF (void,         bfd_putx32, (bfd_vma, bfd_byte *));
+.  SDEF (bfd_vma, bfd_getx16, (bfd_byte *));
+.  SDEF (void,         bfd_putx16, (bfd_vma, bfd_byte *));
 
 Byte swapping for the headers
 
-$  SDEF (bfd_vma,   bfd_h_getx64, (bfd_byte *));
-$  SDEF (void,          bfd_h_putx64, (bfd_vma, bfd_byte *));
-$  SDEF (bfd_vma,  bfd_h_getx32, (bfd_byte *));
-$  SDEF (void,          bfd_h_putx32, (bfd_vma, bfd_byte *));
-$  SDEF (bfd_vma,  bfd_h_getx16, (bfd_byte *));
-$  SDEF (void,          bfd_h_putx16, (bfd_vma, bfd_byte *));
+.  SDEF (bfd_vma,   bfd_h_getx64, (bfd_byte *));
+.  SDEF (void,          bfd_h_putx64, (bfd_vma, bfd_byte *));
+.  SDEF (bfd_vma,  bfd_h_getx32, (bfd_byte *));
+.  SDEF (void,          bfd_h_putx32, (bfd_vma, bfd_byte *));
+.  SDEF (bfd_vma,  bfd_h_getx16, (bfd_byte *));
+.  SDEF (void,          bfd_h_putx16, (bfd_vma, bfd_byte *));
 
 Format dependent routines, these turn into vectors of entry points
 within the target vector structure; one for each format to check.
 
 Check the format of a file being read.  Return bfd_target * or zero. 
 
-$  SDEF_FMT (struct bfd_target *, _bfd_check_format, (bfd *));
+.  SDEF_FMT (struct bfd_target *, _bfd_check_format, (bfd *));
 
 Set the format of a file being written.  
 
-$  SDEF_FMT (boolean,            _bfd_set_format, (bfd *));
+.  SDEF_FMT (boolean,            _bfd_set_format, (bfd *));
 
 Write cached information into a file being written, at bfd_close. 
 
-$  SDEF_FMT (boolean,            _bfd_write_contents, (bfd *));
+.  SDEF_FMT (boolean,            _bfd_write_contents, (bfd *));
 
-The following functions are defined in @code{JUMP_TABLE}. The idea is
-that the back end writer of @code{foo} names all the routines
-@code{foo_}@var{entry_point}, @code{JUMP_TABLE} will built the entries
+The following functions are defined in <<JUMP_TABLE>>. The idea is
+that the back end writer of <<foo>> names all the routines
+<<foo_>>@var{entry_point}, <<JUMP_TABLE>> will built the entries
 in this structure in the right order.
 
 Core file entry points
 
-$  SDEF (char *, _core_file_failing_command, (bfd *));
-$  SDEF (int,    _core_file_failing_signal, (bfd *));
-$  SDEF (boolean, _core_file_matches_executable_p, (bfd *, bfd *));
+.  SDEF (char *, _core_file_failing_command, (bfd *));
+.  SDEF (int,    _core_file_failing_signal, (bfd *));
+.  SDEF (boolean, _core_file_matches_executable_p, (bfd *, bfd *));
 
 Archive entry points
 
-$ SDEF (boolean, _bfd_slurp_armap, (bfd *));
-$ SDEF (boolean, _bfd_slurp_extended_name_table, (bfd *));
-$ SDEF (void,   _bfd_truncate_arname, (bfd *, CONST char *, char *));
-$ SDEF (boolean, write_armap, (bfd *arch, 
-$                              unsigned int elength,
-$                              struct orl *map,
-$                              unsigned int orl_count, 
-$                              int stridx));
+. SDEF (boolean, _bfd_slurp_armap, (bfd *));
+. SDEF (boolean, _bfd_slurp_extended_name_table, (bfd *));
+. SDEF (void,   _bfd_truncate_arname, (bfd *, CONST char *, char *));
+. SDEF (boolean, write_armap, (bfd *arch, 
+.                              unsigned int elength,
+.                              struct orl *map,
+.                              unsigned int orl_count, 
+.                              int stridx));
 
 Standard stuff.
 
-$  SDEF (boolean, _close_and_cleanup, (bfd *));
-$  SDEF (boolean, _bfd_set_section_contents, (bfd *, sec_ptr, PTR,
-$                                            file_ptr, bfd_size_type));
-$  SDEF (boolean, _bfd_get_section_contents, (bfd *, sec_ptr, PTR, 
-$                                            file_ptr, bfd_size_type));
-$  SDEF (boolean, _new_section_hook, (bfd *, sec_ptr));
+.  SDEF (boolean, _close_and_cleanup, (bfd *));
+.  SDEF (boolean, _bfd_set_section_contents, (bfd *, sec_ptr, PTR,
+.                                            file_ptr, bfd_size_type));
+.  SDEF (boolean, _bfd_get_section_contents, (bfd *, sec_ptr, PTR, 
+.                                            file_ptr, bfd_size_type));
+.  SDEF (boolean, _new_section_hook, (bfd *, sec_ptr));
 
 Symbols and reloctions
 
-$ SDEF (unsigned int, _get_symtab_upper_bound, (bfd *));
-$  SDEF (unsigned int, _bfd_canonicalize_symtab,
-$           (bfd *, struct symbol_cache_entry **));
-$  SDEF (unsigned int, _get_reloc_upper_bound, (bfd *, sec_ptr));
-$  SDEF (unsigned int, _bfd_canonicalize_reloc, (bfd *, sec_ptr, arelent **,
-$                                               struct symbol_cache_entry**));
-$  SDEF (struct symbol_cache_entry  *, _bfd_make_empty_symbol, (bfd *));
-$  SDEF (void,     _bfd_print_symbol, (bfd *, PTR, struct symbol_cache_entry  *,
-$                                      bfd_print_symbol_type));
-$#define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
-$  SDEF (alent *,   _get_lineno, (bfd *, struct symbol_cache_entry  *));
-$
-$  SDEF (boolean,   _bfd_set_arch_mach, (bfd *, enum bfd_architecture,
-$                                       unsigned long));
-$
-$  SDEF (bfd *,  openr_next_archived_file, (bfd *arch, bfd *prev));
-$  SDEF (boolean, _bfd_find_nearest_line,
-$        (bfd *abfd, struct sec  *section,
-$         struct symbol_cache_entry  **symbols,bfd_vma offset,
-$        CONST char **file, CONST char **func, unsigned int *line));
-$  SDEF (int,    _bfd_stat_arch_elt, (bfd *, struct stat *));
-$
-$  SDEF (int,    _bfd_sizeof_headers, (bfd *, boolean));
-$
-$  SDEF (void, _bfd_debug_info_start, (bfd *));
-$  SDEF (void, _bfd_debug_info_end, (bfd *));
-$  SDEF (void, _bfd_debug_info_accumulate, (bfd *, struct sec  *));
+.  SDEF (unsigned int, _get_symtab_upper_bound, (bfd *));
+.  SDEF (unsigned int, _bfd_canonicalize_symtab,
+.           (bfd *, struct symbol_cache_entry **));
+.  SDEF (unsigned int, _get_reloc_upper_bound, (bfd *, sec_ptr));
+.  SDEF (unsigned int, _bfd_canonicalize_reloc, (bfd *, sec_ptr, arelent **,
+.                                               struct symbol_cache_entry**));
+.  SDEF (struct symbol_cache_entry  *, _bfd_make_empty_symbol, (bfd *));
+.  SDEF (void,     _bfd_print_symbol, (bfd *, PTR, struct symbol_cache_entry  *,
+.                                      bfd_print_symbol_type));
+.#define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
+.  SDEF (alent *,   _get_lineno, (bfd *, struct symbol_cache_entry  *));
+.
+.  SDEF (boolean,   _bfd_set_arch_mach, (bfd *, enum bfd_architecture,
+.                                       unsigned long));
+.
+.  SDEF (bfd *,  openr_next_archived_file, (bfd *arch, bfd *prev));
+.  SDEF (boolean, _bfd_find_nearest_line,
+.        (bfd *abfd, struct sec  *section,
+.         struct symbol_cache_entry  **symbols,bfd_vma offset,
+.        CONST char **file, CONST char **func, unsigned int *line));
+.  SDEF (int,    _bfd_stat_arch_elt, (bfd *, struct stat *));
+.
+.  SDEF (int,    _bfd_sizeof_headers, (bfd *, boolean));
+.
+.  SDEF (void, _bfd_debug_info_start, (bfd *));
+.  SDEF (void, _bfd_debug_info_end, (bfd *));
+.  SDEF (void, _bfd_debug_info_accumulate, (bfd *, struct sec  *));
 
 Special entry points for gdb to swap in coff symbol table parts
 
-$  SDEF(void, _bfd_coff_swap_aux_in,(
-$       bfd            *abfd ,
-$       PTR             ext,
-$       int             type,
-$       int             class ,
-$       PTR             in));
-$
-$  SDEF(void, _bfd_coff_swap_sym_in,(
-$       bfd            *abfd ,
-$       PTR             ext,
-$       PTR             in));
-$
-$  SDEF(void, _bfd_coff_swap_lineno_in,  (
-$       bfd            *abfd,
-$       PTR            ext,
-$       PTR             in));
-$
+.  SDEF(void, _bfd_coff_swap_aux_in,(
+.       bfd            *abfd ,
+.       PTR             ext,
+.       int             type,
+.       int             class ,
+.       PTR             in));
+.
+.  SDEF(void, _bfd_coff_swap_sym_in,(
+.       bfd            *abfd ,
+.       PTR             ext,
+.       PTR             in));
+.
+.  SDEF(void, _bfd_coff_swap_lineno_in,  (
+.       bfd            *abfd,
+.       PTR            ext,
+.       PTR             in));
+.
 
 Special entry points for gas to swap coff parts
 
-$ SDEF(unsigned int, _bfd_coff_swap_aux_out,(
-$       bfd   	*abfd,
-$       PTR	in,
-$       int    	type,
-$       int    	class,
-$       PTR    	ext));
-$
-$ SDEF(unsigned int, _bfd_coff_swap_sym_out,(
-$      bfd      *abfd,
-$      PTR	in,
-$      PTR	ext));
-$
-$ SDEF(unsigned int, _bfd_coff_swap_lineno_out,(
-$      	bfd   	*abfd,
-$      	PTR	in,
-$	PTR	ext));
-$
-$ SDEF(unsigned int, _bfd_coff_swap_reloc_out,(
-$      	bfd     *abfd,
-$     	PTR	src,
-$	PTR	dst));
-$
-$ SDEF(unsigned int, _bfd_coff_swap_filehdr_out,(
-$      	bfd  	*abfd,
-$	PTR 	in,
-$	PTR 	out));
-$
-$ SDEF(unsigned int, _bfd_coff_swap_aouthdr_out,(
-$      	bfd 	*abfd,
-$	PTR 	in,
-$	PTR	out));
-$
-$ SDEF(unsigned int, _bfd_coff_swap_scnhdr_out,(
-$      	bfd  	*abfd,
-$      	PTR	in,
-$	PTR	out));
-$
-$} bfd_target;
-
-*---
+. SDEF(unsigned int, _bfd_coff_swap_aux_out,(
+.       bfd   	*abfd,
+.       PTR	in,
+.       int    	type,
+.       int    	class,
+.       PTR    	ext));
+.
+. SDEF(unsigned int, _bfd_coff_swap_sym_out,(
+.      bfd      *abfd,
+.      PTR	in,
+.      PTR	ext));
+.
+. SDEF(unsigned int, _bfd_coff_swap_lineno_out,(
+.      	bfd   	*abfd,
+.      	PTR	in,
+.	PTR	ext));
+.
+. SDEF(unsigned int, _bfd_coff_swap_reloc_out,(
+.      	bfd     *abfd,
+.     	PTR	src,
+.	PTR	dst));
+.
+. SDEF(unsigned int, _bfd_coff_swap_filehdr_out,(
+.      	bfd  	*abfd,
+.	PTR 	in,
+.	PTR 	out));
+.
+. SDEF(unsigned int, _bfd_coff_swap_aouthdr_out,(
+.      	bfd 	*abfd,
+.	PTR 	in,
+.	PTR	out));
+.
+. SDEF(unsigned int, _bfd_coff_swap_scnhdr_out,(
+.      	bfd  	*abfd,
+.      	PTR	in,
+.	PTR	out));
+.
+.} bfd_target;
 
 */
 
@@ -519,19 +526,24 @@ bfd_target *default_vector[] = {
 
 
 
-/*proto*
-*i bfd_find_target
-Returns a pointer to the transfer vector for the object target
-named target_name.  If target_name is NULL, chooses the one in the
-environment variable GNUTARGET; if that is null or not defined then
-the first entry in the target list is chosen.  Passing in the
-string "default" or setting the environment variable to "default"
-will cause the first entry in the target list to be returned,
-and "target_defaulted" will be set in the BFD.  This causes
-@code{bfd_check_format} to loop over all the targets to find the one
-that matches the file being read.  
-*; PROTO(bfd_target *, bfd_find_target,(CONST char *, bfd *));
-*-*/
+/*
+FUNCTION
+	bfd_find_target
+
+DESCRIPTION
+	Returns a pointer to the transfer vector for the object target
+	named target_name.  If target_name is NULL, chooses the one in
+	the environment variable GNUTARGET; if that is null or not
+	defined thenthe first entry in the target list is chosen.
+	Passing in the string "default" or setting the environment
+	variable to "default" will cause the first entry in the target
+	list to be returned, and "target_defaulted" will be set in the
+	BFD.  This causes <<bfd_check_format>> to loop over all the
+	targets to find the one that matches the file being read.   
+
+SYNOPSIS
+	bfd_target *bfd_find_target(CONST char *, bfd *);
+*/
 
 bfd_target *
 DEFUN(bfd_find_target,(target_name, abfd),
@@ -561,13 +573,19 @@ DEFUN(bfd_find_target,(target_name, abfd),
 }
 
 
-/*proto*
-*i bfd_target_list
-This function returns a freshly malloced NULL-terminated vector of the
-names of all the valid BFD targets. Do not modify the names 
-*; PROTO(CONST char **,bfd_target_list,());
+/*
+FUNCTION
+	bfd_target_list
+
+DESCRIPTION
+	This function returns a freshly malloced NULL-terminated
+	vector of the names of all the valid BFD targets. Do not
+	modify the names 
 
-*-*/
+SYNOPSIS
+	CONST char **bfd_target_list();
+
+*/
 
 CONST char **
 DEFUN_VOID(bfd_target_list)