Initial revision

bfd/doc/Makefile

@@ -0,0 +1,56 @@
+.SUFFIXES: .texi .o .c .h .p .ip
+VPATH=..
+.c.texi:
+	scanit $< $@
+
+.h.texi:
+	scanit $< $@
+
+.c.p:
+	scanph $< $@
+
+.h.p:
+	scanph $< $@
+
+.c.ip:
+	scanph -i $< $@
+
+
+DOCFILES = syms.texi  bfd.texi  cache.texi \
+	 format.texi  section.texi  archive.texi \
+	 core.texi  libbfd.texi  archures.texi \
+	 reloc.texi  opncls.texi  targets.texi \
+	 aoutx.texi  coffcode.texi cache.texi
+
+PROTOS = opncls.p archures.p libbfd.p \
+	section.p syms.p bfd.p \
+	archive.p reloc.p targets.p \
+	format.p coffcode.p core.p
+
+IPROTOS = cache.ip libbfd.ip reloc.ip
+
+docs: $(DOCFILES)
+
+protos: $(PROTOS) $(IPROTOS)
+	sed -f intobfd bfd-in.h  > bfd.h
+	sed -f tolibbfd libbfd-in.h  > libbfd.h
+	sed -f tolibcoff libcoff-in.h  > libcoff.h
+
+
+
+clean:
+	rm -f $(PROTOS) *.p *.ip *.h bfd.?? $(DOCFILES) bfd.dvi bfd.ps *~* *# bfd.??? 
+
+bfd.info: $(DOCFILES) bfd.texinfo
+	makeinfo +no-validate bfd.texinfo
+
+bfd.dvi: $(DOCFILES) bfd.texinfo
+	tex bfd.texinfo
+	texindex bfd.??
+	tex bfd.texinfo
+
+bfd.ps: bfd.dvi
+	dvips bfd -o
+	
+quickdoc: $(DSRC) docs
+	tex bfd.texinfo

bfd/doc/awkscan

@@ -0,0 +1,12 @@
+# NOTE: BEGIN pattern gives errors if other than 1st line; 
+# END ditto if other than last.
+BEGIN { print "@c ------------------------------START TEXT FROM " FILENAME }
+#
+# Keep /*doc* blocks (terminated by either */ or *-*/)
+/^\/\*doc\*/,/^\*\/|^\*-\*\//
+#
+# Also keep two kinds of /*proto blocks
+/^\/\*proto\*/,/^\*\/|^\*-\*\//
+/^\/\*proto-internal\*/,/^\*\/|^\*-\*\//
+#
+END { print "@c ------------------------------END TEXT FROM " FILENAME }

bfd/doc/awkscan-ip

@@ -0,0 +1,8 @@
+# Awk filter, 1st filter for BFD internal prototype file extraction
+#
+# keep /*proto-internal blocks
+/^\/\*proto-internal\*/,/^\*\/|^\*-\*\//
+#
+# Apparent bug in sed can discard last line in some situations; therefore
+# make last line harmless.
+END { print "\n" }

bfd/doc/awkscan-p

@@ -0,0 +1,8 @@
+# Awk filter, 1st filter for BFD prototype file extraction
+#
+# keep /*proto blocks
+/^\/\*proto\*/,/^\*\/|^\*-\*\//
+#
+# Apparent bug in sed can discard last line in some situations; therefore
+# make last line harmless.
+END { print "\n" }

bfd/doc/bfd.texinfo

@@ -0,0 +1,430 @@
+\input texinfo
+@setfilename bfdinfo
+@c $Id$
+@synindex ky cp
+@ifinfo
+This file documents the BFD library.
+
+Copyright (C) 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, subject to the terms
+of the GNU General Public License, which includes the provision that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+@iftex
+@c@finalout
+@setchapternewpage on
+@c@setchapternewpage odd
+@settitle LIB BFD, the Binary File Descriptor Library
+@titlepage
+@title{libbfd}
+@subtitle{The Binary File Descriptor Library}
+@sp 1
+@subtitle First Edition---BFD version < 2.0
+@subtitle April 1991
+@author {Steve Chamberlain}
+@author {Cygnus Support}
+@page
+
+@tex
+\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$}  % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Support\par
+\hfill steve\@cygnus.com\par
+\hfill {\it BFD}, \manvers\par
+\hfill \TeX{}info \texinfoversion\par
+}
+\global\parindent=0pt % Steve likes it this way
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, subject to the terms
+of the GNU General Public License, which includes the provision that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+@end iftex
+
+@node Top, Overview, (dir), (dir)
+@ifinfo
+This file documents the binary file descriptor library libbfd.
+@end ifinfo
+
+@menu
+* Overview::			Overview of BFD
+* History::			History of BFD
+* Backends::			Backends
+* Porting::			Porting
+* Future::			Future
+* Index::			Index
+
+BFD body:
+* Memory usage::
+* Sections::
+* Symbols::
+* Archives::
+* Formats::
+* Relocations::
+* Core Files::
+* Targets::
+* Architecturs::
+* Opening and Closing::
+* Internal::
+* File Caching::
+
+BFD backends:
+* a.out backends::
+* coff backends::
+@end menu
+
+@node Overview, History, Top, Top
+@chapter Introduction
+@cindex BFD
+@cindex what is it?
+Simply put, BFD is a package which allows applications to use the
+same routines to operate on object files whatever the object file
+format.  A different object file format can be supported simply by
+creating a new BFD back end and adding it to the library.
+
+BFD is split into two parts; the front end and the many back ends.
+@itemize @bullet
+@item The front end of BFD provides the interface to the user. It manages
+memory, and various canonical data structures. The front end also
+decides which back end to use, and when to call back end routines.
+@item The back ends provide BFD its view of the real world. Each back
+end provides a set of calls which the BFD front end can use to maintain
+its canonical form. The back ends also may keep around information for
+their own use, for greater efficiency.
+@end itemize
+@node History, How It Works, Overview,Top
+@section History
+
+One spur behind BFD was the desire, on the part of the GNU 960 team at
+Intel Oregon, for interoperability of applications on their COFF and
+b.out file formats.  Cygnus was providing GNU support for the team, and
+Cygnus was contracted to provide the required functionality.
+
+The name came from a conversation David Wallace was having with Richard
+Stallman about the library: RMS said that it would be quite hard---David
+said ``BFD''.  Stallman was right, but the name stuck.
+
+At the same time, Ready Systems wanted much the same thing, but for
+different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
+coff.
+
+BFD was first implemented by Steve Chamberlain (steve@@cygnus.com),
+John Gilmore (gnu@@cygnus.com),  K. Richard Pixley (rich@@cygnus.com) and
+David Wallace (gumby@@cygnus.com) at Cygnus Support in Palo Alto,
+California.
+
+@node How It Works, History, Porting, Top
+@section How It Works
+
+To use the library, include @code{bfd.h} and link with @code{libbfd.a}.	
+
+BFD provides a common interface to the parts of an object file
+for a calling application. 
+
+When an application sucessfully opens a target file (object, archive or
+whatever) a pointer to an internal structure is returned. This pointer
+points to a structure called @code{bfd}, described in
+@code{include/bfd.h}.  Our convention is to call this pointer a BFD, and
+instances of it within code @code{abfd}.  All operations on
+the target object file are applied as methods to the BFD.  The mapping is
+defined within @code{bfd.h} in a set of macros, all beginning
+@samp{bfd}_.
+
+For example, this sequence would do what you would probably expect:
+return the number of sections in an object file attached to a BFD
+@code{abfd}. 
+
+@lisp
+@cartouche
+#include "bfd.h"
+
+unsigned int number_of_sections(abfd)
+bfd *abfd;
+@{
+  return bfd_count_sections(abfd);
+@}
+@end cartouche
+@end lisp
+
+The abstraction used within BFD is that an object file has a header,
+a number of sections containing raw data, a set of relocations, and some
+symbol information. Also, BFDs opened for archives have the
+additional attribute of an index and contain subordinate BFDs. This approach is
+fine for a.out and coff, but loses efficiency when applied to formats
+such as S-records and IEEE-695. 
+
+@section What BFD Version 1 Can Do
+As different information from the the object files is required,
+BFD reads from different sections of the file and processes them.
+For example a very common operation for the linker is processing symbol
+tables.  Each BFD back end provides a routine for converting
+between the object file's representation of symbols and an internal
+canonical format. When the linker asks for the symbol table of an object
+file, it calls through the memory pointer to the relevant BFD
+back end routine which reads and converts the table into a canonical
+form.  The linker then operates upon the canonical form. When the link is
+finished and the linker writes the output file's symbol table,
+another BFD back end routine is called which takes the newly
+created symbol table and converts it into the chosen output format.
+
+@node BFD information loss, Mechanism, BFD outline, BFD
+@subsection Information Loss
+@emph{Some information is lost due to the nature of the file format.} The output targets
+supported by BFD do not provide identical facilities, and
+information which may be described in one form has nowhere to go in
+another format. One example of this is alignment information in
+@code{b.out}. There is nowhere in an @code{a.out} format file to store
+alignment information on the contained data, so when a file is linked
+from @code{b.out} and an @code{a.out} image is produced, alignment
+information will not propagate to the output file. (The linker will
+still use the alignment information internally, so the link is performed
+correctly).
+
+Another example is COFF section names. COFF files may contain an
+unlimited number of sections, each one with a textual section name. If
+the target of the link is a format which does not have many sections (eg
+@code{a.out}) or has sections without names (eg the Oasys format) the
+link cannot be done simply. You can circumvent this problem by
+describing the desired input-to-output section mapping with the linker command
+language.
+
+@emph{Information can be lost during canonicalization.} The BFD
+internal canonical form of the external formats is not exhaustive; there
+are structures in input formats for which there is no direct
+representation internally.  This means that the BFD back ends
+cannot maintain all possible data richness through the transformation
+between external to internal and back to external formats.
+
+This limitation is only a problem when an application reads one
+format and writes another.  Each BFD back end is responsible for
+maintaining as much data as possible, and the internal BFD
+canonical form has structures which are opaque to the BFD core,
+and exported only to the back ends. When a file is read in one format,
+the canonical form is generated for BFD and the application. At the
+same time, the back end saves away any information which may otherwise
+be lost. If the data is then written back in the same format, the back
+end routine will be able to use the canonical form provided by the
+BFD core as well as the information it prepared earlier.  Since
+there is a great deal of commonality between back ends, this mechanism
+is very useful. There is no information lost for this reason when
+linking or copying big endian COFF to little endian COFF, or @code{a.out} to
+@code{b.out}.  When a mixture of formats is linked, the information is
+only lost from the files whose format differs from the destination.
+
+@node Mechanism,  , BFD information loss, BFD
+@subsection Mechanism 
+The greatest potential for loss of information is when there is least
+overlap between the information provided by the source format, that
+stored by the canonical format, and the information needed by the
+destination format. A brief description of the canonical form may help
+you appreciate what kinds of data you can count on preserving across
+conversions.
+@cindex BFD canonical format
+@cindex internal object-file format
+
+@table @emph
+@item files
+Information on target machine architecture, particular implementation
+and format type are stored on a per-file basis. Other information
+includes a demand pageable bit and a write protected bit.  Note that
+information like Unix magic numbers is not stored here---only the magic
+numbers' meaning, so a @code{ZMAGIC} file would have both the demand
+pageable bit and the write protected text bit set.  The byte order of
+the target is stored on a per-file basis, so that big- and little-endian
+object files may be linked with one another.
+@c FIXME: generalize above from "link"?
+
+@item sections
+Each section in the input file contains the name of the section, the
+original address in the object file, various flags, size and alignment
+information and pointers into other BFD data structures.
+
+@item symbols
+Each symbol contains a pointer to the object file which originally
+defined it, its name, its value, and various flag bits.  When a
+BFD back end reads in a symbol table, the back end relocates all
+symbols to make them relative to the base of the section where they were
+defined.  This ensures that each symbol points to its containing
+section.  Each symbol also has a varying amount of hidden data to contain
+private data for the BFD back end.  Since the symbol points to the
+original file, the private data format for that symbol is accessible.
+@code{gld} can operate on a collection of symbols of wildly different
+formats without problems.
+
+Normal global and simple local symbols are maintained on output, so an
+output file (no matter its format) will retain symbols pointing to
+functions and to global, static, and common variables.  Some symbol
+information is not worth retaining; in @code{a.out} type information is
+stored in the symbol table as long symbol names.  This information would
+be useless to most COFF debuggers; the linker has command line switches
+to allow users to throw it away.
+
+There is one word of type information within the symbol, so if the
+format supports symbol type information within symbols (for example COFF,
+IEEE, Oasys) and the type is simple enough to fit within one word
+(nearly everything but aggregates) the information will be preserved.
+
+@item relocation level
+Each canonical BFD relocation record contains a pointer to the symbol to
+relocate to, the offset of the data to relocate, the section the data
+is in and a pointer to a relocation type descriptor. Relocation is
+performed effectively by message passing through the relocation type
+descriptor and symbol pointer. It allows relocations to be performed
+on output data using a relocation method only available in one of the
+input formats. For instance, Oasys provides a byte relocation format.
+A relocation record requesting this relocation type would point
+indirectly to a routine to perform this, so the relocation may be
+performed on a byte being written to a COFF file, even though 68k COFF
+has no such relocation type.
+
+@item line numbers
+Object formats can contain, for debugging purposes, some form of mapping
+between symbols, source line numbers, and addresses in the output file.
+These addresses have to be relocated along with the symbol information.
+Each symbol with an associated list of line number records points to the
+first record of the list.  The head of a line number list consists of a
+pointer to the symbol, which allows divination of the address of the
+function whose line number is being described. The rest of the list is
+made up of pairs: offsets into the section and line numbers. Any format
+which can simply derive this information can pass it successfully
+between formats (COFF, IEEE and Oasys).
+@end table
+
+@c FIXME: what is this line about?  Do we want introductory remarks 
+@c FIXME... on back ends?  commented out for now.
+@c What is a backend
+@node BFD front end, BFD back end, Mechanism, Top
+@chapter BFD front end
+@include  bfd.texi
+
+@node Memory Usage, Sections, bfd, Top
+@section Memory Usage
+BFD keeps all its internal structures in obstacks. There is one obstack
+per open BFD file, into which the current state is stored. When a BFD is
+closed, the obstack is deleted, and so everything which has been
+allocated by libbfd for the closing file will be thrown away.
+
+BFD will not free anything created by an application, but pointers into
+@code{bfd} structures will be invalidated on a @code{bfd_close}; for example,
+after a @code{bfd_close} the vector passed to
+@code{bfd_canonicalize_symtab} will still be around, since it has been
+allocated by the application, but the data that it pointed to will be
+lost.
+
+The general rule is not to close a BFD until all operations dependent
+upon data from the BFD have been completed, or all the data from within
+the file has been copied. To help with the management of memory, there is a function
+(@code{bfd_alloc_size}) which returns the number of bytes in obstacks
+associated with the supplied BFD. This could be used to select the
+greediest open BFD, close it to reclaim the memory, perform some
+operation and reopen the BFD again, to get a fresh copy of the data structures.
+
+@node Sections,Symbols ,Memory Usage, Top
+@include  section.texi
+
+@node Symbols, Archives ,Sections, To
+@include  syms.texi
+
+@node Archives, Formats, Symbols, Top
+@include  archive.texi
+
+@node Formats, Relocations, Archives, Top
+@include  format.texi
+
+@node Relocations, Core Files,Formats, Top
+@include  reloc.texi
+
+@node Core Files, Targets,  Relocations, Top
+@include  core.texi
+
+@node Targets, Architectures, Core Files, Top
+@include  targets.texi
+
+@node Architectures, Opening and Closing, Targets, Top
+@include  archures.texi
+
+@node Opening and Closing, Internal, Architectures, Top
+@include  opncls.texi
+
+@node Internal, File Caching, Opening and Closing, Top
+@include  libbfd.texi
+
+@node File Caching, Top, Internal, Top
+@include  cache.texi
+
+@chapter BFD back end
+@node BFD back end, ,BFD front end, Top
+@menu
+* What to put where
+* a.out backends::
+* coff backends::
+* oasys backend::
+* ieee backend::
+* srecord backend::
+@end menu
+@node What to Put Where, aout backends, BFD back end, BFD back end
+All of BFD lives in one directory.
+
+@node aout backends, coff backends, What to Put Where, BFD back end
+@include  aoutx.texi
+
+@node coff backends, oasys backends, aout backends, BFD back end
+@include  coffcode.texi
+
+@node Index,  , BFD, Top
+@unnumbered Function Index
+@printindex  fn
+@unnumbered Index
+@printindex cp
+
+@tex
+% I think something like @colophon should be in texinfo.  In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/} and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: pesch@cygnus.com, 28mar91.
+@end tex
+
+
+@contents
+@bye
+
+

bfd/doc/blins-p

@@ -0,0 +1,8 @@
+# sed script for BFD header files
+# Merge adjacent blank lines.  Loop til no change.
+:blin
+/^$/,/^ *[^ ]*.*$/{
+/^$/N
+s/^ *\n *$//
+}
+t blin

bfd/doc/exfil1-p

@@ -0,0 +1,5 @@
+#
+# Locate and coalesce adjacent comments
+/\*\/$/N
+s/\*\/\n\/\*/\
+/

bfd/doc/exfil3-p

@@ -0,0 +1,16 @@
+# blank-line activity:
+# Merge adjacent blank lines.  Loop til no change.
+:blin
+/^$/,/^ *[^ ]*.*$/{
+/^$/N
+s/^ *\n *$//
+}
+t blin
+#
+/^$/,/^ *[^ ]*.*$/{
+/^$/N
+# Transpose <blank line> <end comment>
+/^ *\n\*\/$/c\
+*\/\
+
+}

bfd/doc/exfilter

@@ -0,0 +1,14 @@
+# SED script for preprocessing embedded doc from source (S. Chamberlain markup)
+# Final pass; cleanup work is done here.
+#
+# Within examples, make '{' and '}' printable:
+/^@lisp$/,/^@end lisp$/s/{/@{/
+/^@lisp$/,/^@end lisp$/s/}/@}/
+/^@example$/,/^@end example$/s/{/@{/
+/^@example$/,/^@end example$/s/}/@}/
+#
+# Delete empty @findex and @subsubsection entries (resulting from *proto*
+# with no further text on same line, in middle pass)
+/^@findex $/d
+/^@subsubsection @code{}/d
+#

bfd/doc/exfilter-p

@@ -0,0 +1,12 @@
+# SED script for preprocessing embedded headers from C source comments 
+# (S. Chamberlain markup)
+# beginning of many passes of cleanup work 
+#
+# Delete empty comment blocks
+/^\/\*$/N
+/^\/\*\n\*\/ *$/d
+#
+# Locate and coalesce adjacent comments
+/\*\/$/N
+s/\*\/\n\/\*/\
+/

bfd/doc/exfiltst

@@ -0,0 +1,8 @@
+# Merge adjacent blank lines.  Loop til no change.
+:blin
+/^$/,/^ *[^ ]*.*$/{
+/^$/N
+s/^ *\n *$//
+}
+t blin
+

bfd/doc/exmerge

@@ -0,0 +1,4 @@
+# SED script for preprocessing embedded doc from source (S. Chamberlain markup)
+# Locate and coalesce adjacent @example blocks
+/^@end example/N
+/^@end example\n@example$/d

bfd/doc/intobfd

@@ -0,0 +1,11 @@
+/\/\*:archive.c\*\//r archive.p
+/\/\*:archures.c\*\//r archures.p
+/\/\*:bfd.c\*\//r bfd.p
+/\/\*:core.c\*\//r core.p
+/\/\*:format.c\*\//r format.p
+/\/\*:libbfd.c\*\//r libbfd.p
+/\/\*:opncls.c\*\//r opncls.p
+/\/\*:reloc.c\*\//r reloc.p
+/\/\*:section.c\*\//r section.p
+/\/\*:syms.c\*\//r syms.p
+/\/\*:targets.c\*\//r targets.p

bfd/doc/mergecom-p

@@ -0,0 +1,5 @@
+# SED script for preprocessing embedded headers from C source comments 
+# Locate and coalesce adjacent comments
+/\*\/$/N
+s/\*\/\n\/\*/\
+/

bfd/doc/movecom-p

@@ -0,0 +1,8 @@
+# sed script for BFD header files:
+# Transpose <blank line> <end comment>
+/^$/,/^ *[^ ]*.*$/{
+/^$/N
+/^ *\n\*\/$/c\
+*\/\
+
+}

bfd/doc/scanit

@@ -0,0 +1,25 @@
+#!/bin/sh
+# Script to coordinate parsing of S. Chamberlain source-embedded 
+# documentation markup language.
+
+# Four passes:
+#	1) awk discards lines not intended for docn, and marks blocks of
+#	   text with comments identifying source file;
+#	2) first sed pass interprets Chamberlain markup;
+#	3) second sed pass does cleanup that involves merging lines
+#	4) third sed pass does remaining cleans up---making {}
+#	   printable within examples, and eliminating empty index entries and
+#          headings.
+#Third and second sed passes are separate because order of execution is hard
+#to control otherwise, making one or another of the things involving @example
+#inoperative.
+
+base=`echo $1 | cut -d '.' -f 1`
+out=`echo $2 | cut -d '.' -f 1`
+
+awk -f awkscan $1 | \
+sed -f sedscript | \
+sed -f unPROTO | \
+sed -f exmerge  | \
+sed -f exfilter  >$out.texi
+

bfd/doc/scanph

@@ -0,0 +1,26 @@
+#!/bin/sh
+# Script to coordinate parsing of S. Chamberlain source-embedded 
+# header-file markup language. 
+
+# '-i' option means use *proto-internal* segments, else just *proto*
+SFX=p
+if [ $1 = "-i" ]; then
+	SFX=ip
+	shift
+fi
+
+base=`echo $1 | cut -d '.' -f 1`
+out=`echo $2 | cut -d '.' -f 1`
+
+#  passes:
+#	1) awk discards lines not intended for header, and marks blocks of
+#	   text with comments identifying source file;
+#	2) first sed pass interprets Chamberlain markup;
+#	3) further sed passes clean up---merging adjacent comments etc.
+
+awk -f awkscan-$SFX $1 |\
+sed -f sedscript-p |\
+sed -f mergecom-p |\
+sed -f startcom-p  |\
+sed -f blins-p |\
+sed -f movecom-p  >$out.$SFX

bfd/doc/sedscript

@@ -0,0 +1,85 @@
+# SED script for preprocessing embedded doc from source (S. Chamberlain markup)
+# middle pass; most of the work is done here.
+#
+# First, get rid of /*doc* markers; they've done their job in the first pass.
+/^\/\*doc\*/d
+#
+# /*proto* markers may be optionally followed by a *i-style subsubsec, findex
+# entry.  This will generate empty @findex and @subsubsection entries if
+# the *proto* is on a line by itself; third pass removes them.
+/^\/\*proto\*/s/^\/\*proto\* *\(.*\)$/@findex \1\
+@subsubsection @code{\1}/
+#
+# /*proto-internal* is just like /*proto* from doc point of view.
+/^\/\*proto-internal\*/s/^\/\*proto-internal\* *\(.*\)$/@findex \1\
+@subsubsection @code{\1}/
+#
+# *i at beginning of line: rest of line is both a subsubsection heading
+#   and an entry in function index.
+/^\*i/s/^\*i *\(.*\)$/@findex \1\
+@subsubsection @code{\1}/
+#
+# Two alternative docn block ends, '*/' and '*-*/' on lines by themselves;
+# replace by blank lines (for texinfo source readability).
+/^\*\/$/c\
+
+/^\*-\*\/$/c\
+
+# {* and *} are standins for comment markers (originally embedded in .c 
+# comments)---turn into real comment markers:
+s/{\*/\/\*/
+s/\*}/\*\//
+#
+# '*+++' and '*---' span a block of text that includes both example lines 
+# (marked by leading '$') and explanatory text (to be italicized).
+# Italicize lines lacking '$':
+/\*\+\+\+/,/\*---/s/^\([^$].*\)$/@i{\1}/
+#
+# We don't need *+++ and *--- markers any more; kill them (trailing marker
+# becomes blank line for readability)
+/\*\+\+\+/d
+/\*---/c\
+
+# Any line beginning with '$' is made an example line; third pass later 
+# coalesces adjacent example blocks.  *DO NOT* introduce extra space after
+# @end example, so we can spot adjacent ones in third pass.
+/^\$/i\
+@example
+/^\$/a\
+@end example
+#
+# In any example line, turn '{' and '}' into '@{' and '@}'
+###/^\$/s/{/@{/g
+###/^\$/s/}/@}/g
+#
+# Now delete the '$' markers themselves:
+/^\$/s/\$//
+#
+# *+ and *- delimit large examples to be enclosed in cartouches.
+/^\*\+$/c\
+@lisp\
+@cartouche
+/^\*-$/c\
+@end cartouche\
+@end lisp\
+
+# '*;' introduces an example which may have a single line or multiple lines;
+# it extends until the next semicolon (which is also printed).
+# One-line case: (do this first; else second line address for multi-line case
+# will include random text til we happen to end a line in a doc comment with
+# a semicolon)
+/^\*;.*;$/{
+s/^\*;/@example\
+/
+s/;$/;\
+@end example\
+/
+}
+# Multi-line case:
+/^\*;/,/.*;$/{
+s/^\*;/@example\
+/
+s/;$/;\
+@end example\
+/
+}

bfd/doc/sedscript-p

@@ -0,0 +1,63 @@
+# SED script for preprocessing embedded headers from source 
+# (S. Chamberlain markup)
+# middle pass; most of the work is done here.
+#
+# First, get rid of /*proto* markers; they've done their job in the first pass.
+# (They remain comment-introducers)
+/^\/\*proto\*/s/^\/\*proto\*/\/*/
+/^\/\*proto-internal\*/s/^\/\*proto-internal\*/\/*/
+#
+# *-*/ is an alternative (older) comment-block end.  Remap for uniformity:
+s/^\*-\*\//\*\//
+#
+# {* and *} are standins for comment markers (originally embedded in .c 
+# comments)---turn into real comment markers:
+s/{\*/\/\*/
+s/\*}/\*\//
+#
+# '*+++' and '*---' span a block of text that includes both header lines 
+# (marked by leading '$') and explanatory text (to be comments).
+# No need to start comment at "*+++", or end it at "*---", since we're 
+# already in a *proto* comment block.  Just delete.
+/\*\+\+\+/d
+/\*---/d
+#
+# Any line beginning with '$' is made a line of code in the header; 
+#  stuff in between is comments, so *precede* each '$' line with 
+#  END-comment, *follow* each '$' line with START-comment; third pass later 
+#  eliminates empty comment blocks.
+/^\$/i\
+*/
+/^\$/a\
+/*
+#
+# Now delete the '$' markers themselves:
+/^\$/s/\$//
+#
+# *+ and *- delimit larger blocks of code, treated the same as '$' lines
+/^\*\+$/c\
+*/
+/^\*-$/c\
+/*
+#
+# '*;' introduces code which may have a single line or multiple lines;
+# it extends until the next semicolon (which is also printed).
+#
+# One-line case: (do this first; else second line address for multi-line case
+# will include random text til we happen to end a line in a proto comment with
+# a semicolon)
+/^\*;.*;$/{
+s/^\*;/*\/\
+/
+s/;$/;\
+\/*\
+/
+}
+# Multi-line case:
+/^\*;/,/.*;$/{
+s/^\*;/*\/\
+/
+s/;$/;\
+\/*\
+/
+}

bfd/doc/startcom-p

@@ -0,0 +1,12 @@
+# sed script for preprocessing BFD header files
+# <start comment> activity:
+/^\/\*$/{
+N
+# Delete empty comment blocks
+/^\/\*\n\*\/ *$/d
+# Transpose <start comment><blank line>
+s/^\/\*\n *$/\
+\/*/
+# merge <start comment> on line by itself with following line
+s/^\/\*\n\(.*\)/\/* \1/
+}

bfd/doc/tolibbfd

@@ -0,0 +1,4 @@
+/---------------START FROM/,/---------------END FROM/d
+/\/\*:libbfd.c\*\//r libbfd.ip
+/\/\*:cache.c\*\//r cache.ip
+/\/\*:reloc.c\*\//r reloc.ip

bfd/doc/tolibcoff

@@ -0,0 +1 @@
+/\/\*:coffcode.h\*\//r coffcode.p

bfd/doc/unPROTO

@@ -0,0 +1,18 @@
+#
+# The PROTO macro is a subterfuge to be compatible with both ANSI and K&R 
+# declaration syntax.  It's not widely known, so for the docn just map the 
+# thing to ANSI declaration syntax.
+# 
+# First, join up defns broken across multiple lines in source---but leave
+# any linebreaks, to prettify our examples 
+:pbegn
+/PROTO(.*, *$/N
+s/\n/?/
+t pbegn
+s/?/\
+/g
+# Now actually do the PROTO interpretation.
+# A PROTO invocation looks like
+#   PROTO( resulttype, function, (arglist));
+s/[ 	]*PROTO(\(.*\),[\n 	]*\(.*\),[\n 	]*\((.*)\));/\1 \2\3;/
+