tao_idl: Reorganize Documenting Files

15 files changed, 72 insertions, 684 deletions

diff --git a/TAO/TAO_IDL/INSTALL.sun b/TAO/TAO_IDL/INSTALL.sun
deleted file mode 100644
index 2b26b7fb597..00000000000
--- a/TAO/TAO_IDL/INSTALL.sun
+++ /dev/null
@@ -1,186 +0,0 @@
-========================================
-
-This file contains the original INSTALL file that came with the
-SunSoft IDL compiler release.  This information in this file is
-historical in nature and the much of the specific information probably
-is inaccurate with respect to the current state of TAO IDL.  Please
-see the ../TAO-INSTALL.html documentation that comes with TAO for
-up-to-date information on the installation process.
-
-Specifically, some of the files referred to below have been renamed in
-TAO IDL.
-
-INTERFACE DEFINITION LANGUAGE INSTALLATION GUIDE
--==============================================-
-
-INTRODUCTION
-
-This file describes the installation process for OMG_IDL_CFE version 1.3.
-This file explains how to:
-
-- install the source code
-- modify the sources to customize them for different configurations
-- modify the sources to implement your own back end
-
-TESTED CONFIGURATIONS
-
-This release has been tested and is believed to operate correctly on:
-- SunPro Sparcworks 2.x and 3.0 on SunOS 4.1.x
-- SunPro Sparcworks 2.x and 3.0 on Solaris 2.3
-- g++ 2.5.8 on SunOS 4.1.x
-- g++ 2.5.8 on Solaris 2.3
-
-This is the first release of OMG IDL CFE which is preconfigured to compile
-correctly for Solaris 2.x and with SunPro SparcWorks compilers.
-
-CUSTOMIZATION
-
-The release contains a file idl_make_vars in the current directory,
-which is included in each Makefile. This file defines all the
-customizable variables for the CFE.
-
-OSV should be set to a string denoting the operating system upon which
-you wish to build the CFE. The CFE as shipped is preconfigured to
-compile correctly on Solaris 2.x (OSV=SOLARIS2), and has also been
-tested on SunOS 4.1.x (OSV=SUNOS4). It contains code donated by HP
-which enables it to be compiled on Apollo Domain systems (OSV=apollo)
-and HPUX systems (OSV=hpux), but these two configurations have not
-been tested.
-
-C++ and CCC should be set to identify the C++ compiler you will use to
-compile this release. Their values should be identical. Both are set
-to address differences between various make programs - some predefine
-CCC, others use C++ to denote the C++ compiler. The possible values
-are CC (which uses the Sparcworks compilers on SunOS 4.1 and Solaris
-2.3) and g++, which uses the installed version of GNU C++.
-
-CCFLAGS should be set to a list of flags to pass to the C++
-compiler. As shipped, this list is -g. NOTE: We have not extensively
-tested the release with optimization turned on.
-
-CPP_FLAGS should be set to a list of flags to pass to the C++
-preprocessor.  Use this variable to enable or disable specific
-customizations you make to the BE or CFE sources.
-
-YFLAGS should be set to a list of flags to pass to the Yacc
-program. As shipped, the list is -d -t, which causes Yacc to generate
-y.tab.h and y.tab.c files.
-
-LEXFLAGS should be set to a list of flags to pass to the Lex
-program. As shipped, the list -t.
-
-RANLIB should be set to the location of the ranlib program on your
-system.  As shipped this is ranlib. If your system has no ranlib you
-can set this variable to ':' or /bin/true. As shipped the variable is
-preset to /bin/true since Solaris 2.x does not use ranlib.
-
-AR should be set to the location of the ar program on your system. As
-shipped this is ar. If your system has a different mechanism for
-creating libraries, you should modify the value of this variable
-accordingly.
-
-ARFLAGS should be set to the flags to be passed to the ar program. As
-shipped this is 'crv'.
-
-INSTALLATION
-
-a. Disk space requirements
-
-This distribution requires approximately 350 KBytes when
-compressed. When uncompressed, untarred and compiled, approximately 10
-MBytes of disk space are consumed on a Sun 4.
-
-b. Getting the software
-
-Use anonymous FTP to omg.org and supply your e-mail address as
-password.  Change directories to pub/OMG_IDL_CFE_1.3, set bin and get
-the compressed tar file OMG_IDL_CFE_1.3.tar.Z.
-
-The distribution may, in the future, be made available from other
-archives on the Internet. However, omg.org will always have the most
-up-to-date version of this software.
-
-After transferring this file, uncompress it and untar it in a
-directory of your choice.
-
-c. Compiling it
-
-If you are using a Sparcstation running Solaris 2.x and have the
-SunPro Sparcworks compilers installed, you may directly install the
-software. If your hardware or operating system configurations are
-different, read and follow the instructions in the previous section
-first.
-
-At the root directory of the release, issue
-
-   % make
-
-or
-
-   % make all
-
-This will compile the provided sources and the sources found in the be
-directory. Executing this make target causes 'make all' to be invoked
-in each subdirectory, resulting in building the libraries for each
-component and finally a link step producing an executable IDL
-compiler.
-
-In order to make only the compiler front end components, without
-compiling the sources found in the be directory and without building
-an executable, issue
-
-  % make libs
-
-This will build the libraries in the ast, fe, util, driver and narrow
-directories. To build only the be, issue
-
-  % make be
-
-To build all libraries without creating an executable, issue
-
-  % make all_libs
-
-To remove all files created by the build process, issue
-
-  % make clean
-
-This will not remove any files created by Yacc and Lex, because you
-may be using the ones provided in the distribution (see below).
-
-d. Yacc and Lex
-
-Some installations may not have a C++ aware Yacc and Lex
-processor. For these installations, we have included the output of
-yacc and lex in the release. If you need to use these files to build
-the release because you don't have access to a C++ capable Yacc or
-Lex, go to the "fe" directory, issue the command:
-
-   % touch lex.yy.cc y.tab.cc y.tab.hh
-
-This will ensure that the processed files appear to be newer than the
-source files they were produced from and will cause "make" to skip
-their production.
-
-NOTE: The files provided in the distribution have been produced on
-Solaris 2.3 and may contain OS-specific #include directives. If you
-intend to use these files, you may have to edit them to make them work
-in your environment. The provided files are known to compile cleanly
-without modification with both SunPro Sparcworks compilers and GNU C++
-on both SunOS 4.1 and Solaris 2.3.  We have not tested the grammar and
-lexer input files with bison or flex.
-
-IMPLEMENTING A BACK END
-
-To implement your own back end, you can start with the provided
-sources in the be directory and modify them. The Makefile understands
-the 'make all' target and will generate libbe.a in the demo_be
-directory. As set up, the variable CPP_FLAGS allows you to place
-include files either in the current directory or in the include
-directory. Alternatively, you can place your include files in a new
-directory and modify CPP_FLAGS to cause the C++ preprocessor to search
-this new directory for referenced include files, by adding a new -I
-directive.
-
-Additional detail on the structure and function of back ends, and on
-the protocol which a back end must implement, are found in the
-document entitled WRITING_A_BE.
diff --git a/TAO/TAO_IDL/README.md b/TAO/TAO_IDL/README.md
new file mode 100644
index 00000000000..7d76776c803
--- /dev/null
+++ b/TAO/TAO_IDL/README.md
@@ -0,0 +1,17 @@
+# TAO\_IDL
+
+TAO\_IDL/`tao_idl` is TAO's Interface Description Language (IDL) compiler. It
+is based on Sun Microsystems' OMG IDL Compiler Front End (CFE) version 1.3,
+which was released in 1994. It implements most IDL v3 features and, starting
+with TAO 2.5.4, some features from IDL v4.
+
+## User Documentation
+
+User documentation on using TAO\_IDL can be found at
+[../docs/compiler.html](../docs/compiler.html).
+
+## Developer Documentation
+
+For developers either making use of TAO\_IDL in a downstream compiler or
+contributing to TAO\_IDL, documentation can be found at
+[docs/README.md](docs/README.md).
diff --git a/TAO/TAO_IDL/README.sun b/TAO/TAO_IDL/README.sun
deleted file mode 100644
index b2b6e20d3d5..00000000000
--- a/TAO/TAO_IDL/README.sun
+++ /dev/null
@@ -1,245 +0,0 @@
-========================================
-
-This file contains the original README file that came with the SunSoft
-IDL compiler release.  This information in this file is historical in
-nature and the much of the specific information probably is inaccurate
-with respect to the current state of TAO IDL.  Please see the
-../docs/index.html documentation that comes with TAO for up-to-date
-information on TAO IDL compiler design and implementation.
-
-Specifically, some of the files referred to below have been renamed in
-TAO IDL.
-
-INTERFACE DEFINITION LANGUAGE COMPILER FRONT END
--==============================================-
-
-INTRODUCTION
-
-Welcome to the publicly available source release of SunSoft's
-implementation of the compiler front end (CFE) for OMG Interface Definition
-Language! This is Release 1.3 of the CFE.
-
-The Interface Definition Language (IDL) implementation is divided into
-three parts:
-
-- A main program for driving the compilation process
-- A parser and attendant utilities
-- One or more back ends (BEs) for taking the processed input and producing
-  output in a target language and target format
-
-WARNINGS
-
-This is a preliminary version. This software is made available AS IS and
-WITH NO GUARANTEES. Please read  the copyright notice attached at the
-bottom of this file.
-
-IMPORTANT NOTICE FOR USERS OF OMG IDL CFE VERSION 1.2.
-
-Please carefully read the file CHANGES to obtain IMPORTANT INFORMATION on
-changes in that may affect the manner in which a BE is constructed. You
-must follow instructions contained in the file CHANGES to obtain a
-functional BE if you are migrating an existing BE from OMG IDL CFE v. 1.2.
-
-TARGET AUDIENCE
-
-Who should use this release?
-
-- You can use this source release to create a stand alone parser for OMG
-  Interface Definition Language. This may be useful to verify the legality
-  of IDL input.
-- Developers of OMG Interface Definition Language compilers should use this
-  release as a basis for writing their back ends, to obtain a common
-  framework for their compiler and to provide portable and uniform
-  parsing of IDL input.
-
-HOW TO OBTAIN THIS SOFTWARE
-
-Please use anonymous FTP to omg.org and supply your e-mail address as the
-password. Then change directories to pub/OMG_IDL_CFE_1.3, set binary transfer
-and get the file OMG_IDL_CFE_1.3.TAR.Z. This file includes copies of all
-individual documentation files in the directory.
-
-Precompiled binaries constructed from the sources in this release will be
-made available shortly, in the directory pub/OMG_IDL_CFE_1.3/bin. These
-binaries are useful for parsing IDL source and for learning about the
-language. Precompiled binaries for Solaris 2.x and for SunOS 4.x will be
-provided.
-
-You can also use the mail server program to retrieve this software. Send
-email with the subject 'help' to omg_idl@omg.org, and the mail server will
-respond with instructions on how to retrieve the software.
-
-Copies of this software may be made available from archives other than
-omg.org. New versions made available by Sun will be placed on omg.org and a
-message will be sent to this newsgroup announcing its availability.
-
-Finally, the SunSoft OMG IDL CFE is also available on magnetic tape for a
-nominal media charge directly from SunSoft. Please refer to part number
-DIDL-100-STP when ordering.
-
-CONTACT POINT
-
-Please let us know who you are if you decide to use this software, and how
-you use it. Please send e-mail to:
-
-     idl-cfe@sun.com
-
-This address can also be used to report problems, bugs, suggestions and
-send general comments.
-
-WHAT IS PROVIDED IN THE RELEASE
-
-Provided in this release are:
-
-- A main program for driving an Interface Definition Language compiler
-- A parser for the Interface Definition Language grammar which builds an
-  internal representation of the input parsed. This internal
-  representation, named an Abstract Syntax Tree (AST), is used as input to
-  a back end
-- Some utility functions used by the parser
-- A demonstration back end (BE) which exercises the front end but produces
-  no translated output
-- Documentation of the public interfaces and of the contract between
-  the compiler front end and a back end
-
-OPERATION
-
-A complete compiler operates in two passes:
-
-- The first pass, provided in this release, parses the IDL input and
-  produces an internal representation, called an Abstract Syntax Tree (AST).
-  This pass also does a complete syntax and semantics check of the input
-  provided to ensure that exactly legal IDL input is accepted. If a syntax
-  or semantic error is discovered, the second pass is not invoked.
-- The second pass, provided by compiler developers, takes the AST and
-  produces output in the language and format of choice. A demonstration
-  back end is provided in the release.
-
-HOW TO USE THIS SOFTWARE
-
-To create a complete compiler from OMG Interface Definition Language to a
-target language, compiler developers will:
-
-- Write a back end (BE) to take the internal representation of the input
-  parsed and translate it to the target language and format. You will
-  probably want to replace the BE directory in this source tree with your
-  own BE directory
-- Link the BE with the sources provided here to produce a complete
-  compiler.
-
-DOCUMENTATION
-
-The OMG Interface Definition Language is fully described in the CORBA
-documentation, Chapter 4. This document may be obtained from OMG.
-
-This release also provides the following documents:
-
-- This README file, describing the release
-- INSTALL, describing installation of the software
-- WRITING_A_BE contains all the information needed to start writing a back
-  end for this distribution
-- CHANGES_IN_AST describes changes that affect migration of BEs written
-  against version 1.2 to version 1.3.
-- CLI, describing the command line interface to the CFE
-- ROADMAP, describing the directory structure for the source code. This
-  file will assist a developer in understanding the structure of the code
-  and navigating it
-- PROBLEMS, describing a list of issues that may be addressed in future
-  releases
-- BUG_REPORT, containing a form for use in reporting bugs and problems
-  with the IDL CFE
-
-ENVIRONMENT
-
-The INSTALL file explains how to customize the software for specific
-platforms. The source distribution expects the following environment:
-
-- Sparcstation 1, 2, or 10 hardware
-- SunPro SparcWorks 3.x or 4.0
-
-As preconfigured, it compiles on Solaris 2.x. It can be reconfigured to
-compile on SunOS 4.x, HPUX or Apollo Domain OS. As far as is known, no use
-is made of Sun Make-specific features, and the Makefiles should be usable
-with other make programs.
-
-This release has been tested and is believed to operate correctly with:
-- SunPro Sparcworks 2.x and 3.0 on SunOS 4.1.x
-- SunPro Sparcworks 2.x and 3.0 on Solaris 2.3
-- g++ 2.5.8 on SunOS 4.1.x
-- g++ 2.5.8 on Solaris 2.3
-
-INSTALLATION
-
-This release is targetted for Sun workstations running Solaris 2.x. The
-process of installing this software is described in detail in the file
-INSTALL in this directory. The INSTALL file also describes how to customize
-the release for your own environment if it is different.
-
-KNOWN PROBLEMS
-
-A list of known deficiencies is provided in the file PROBLEMS in this
-directory. If you find a problem which is not mentioned in it, please
-report it as described below. Please read this file now to be apprised of
-the problems found so far with this release.
-
-COPYRIGHT
-
-This copyright notice appears on all files. Please read it!
-
-Copyright 1992, 1993, 1994 Sun Microsystems, Inc.  Printed in the United
-States of America.  All Rights Reserved.
-
-This product is protected by copyright and distributed under the following
-license restricting its use.
-
-The Interface Definition Language Compiler Front End (CFE) is made
-available for your use provided that you include this license and copyright
-notice on all media and documentation and the software program in which
-this product is incorporated in whole or part. You may copy and extend
-functionality (but may not remove functionality) of the Interface
-Definition Language CFE without charge, but you are not authorized to
-license or distribute it to anyone else except as part of a product or
-program developed by you or with the express written consent of Sun
-Microsystems, Inc. ("Sun").
-
-The names of Sun Microsystems, Inc. and any of its subsidiaries or
-affiliates may not be used in advertising or publicity pertaining to
-distribution of Interface Definition Language CFE as permitted herein.
-
-This license is effective until terminated by Sun for failure to comply
-with this license.  Upon termination, you shall destroy or return all code
-and documentation for the Interface Definition Language CFE.
-
-INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED AS IS WITH NO WARRANTIES OF
-ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS
-FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR ARISING FROM A COURSE OF
-DEALING, USAGE OR TRADE PRACTICE.
-
-INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED WITH NO SUPPORT AND WITHOUT
-ANY OBLIGATION ON THE PART OF Sun OR ANY OF ITS SUBSIDIARIES OR AFFILIATES
-TO ASSIST IN ITS USE, CORRECTION, MODIFICATION OR ENHANCEMENT.
-
-SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES SHALL HAVE NO LIABILITY WITH
-RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY
-INTERFACE DEFINITION LANGUAGE CFE OR ANY PART THEREOF.
-
-IN NO EVENT WILL SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES BE LIABLE FOR
-ANY LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL
-DAMAGES, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-Use, duplication, or disclosure by the government is subject to
-restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in
-Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR
-52.227-19.
-
-Sun, Sun Microsystems and the Sun logo are trademarks or registered
-trademarks of Sun Microsystems, Inc.
-
-SunSoft, Inc.  
-2550 Garcia Avenue 
-Mountain View, California  94043
-
-NOTE:
-
-SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are
-trademarks or registered trademarks of Sun Microsystems, Inc.
diff --git a/TAO/TAO_IDL/docs/ANNOUNCEMENT b/TAO/TAO_IDL/docs/ANNOUNCEMENT
deleted file mode 100644
index 870db6f6006..00000000000
--- a/TAO/TAO_IDL/docs/ANNOUNCEMENT
+++ /dev/null
@@ -1,131 +0,0 @@
-WHAT:
-
-SunSoft, Inc., Mountain View, California, has placed the source code to
-Project DOE's Interface Definition Language (IDL) compiler front end
-(CFE) on OMG's file server, making the implementation publicly
-available. This release is identified by the version number 1.3.
-
-Project DOE is SunSoft's corporate-wide development effort to integrate
-distributed object technology into the Solaris O/S.  OMG (Object Management
-Group) is the industry wide body formed to create specifications for
-distributed object technology. It currently has more than 370 members. OMG
-IDL is part of OMG's CORBA 1.1 specification and provides a standardized
-way for defining object interfaces. OMG IDL forms the basis for distributed
-object interactionin Project DOE.
-
-The SunSoft OMG IDL CFE provides a complete framework for building
-CORBA 1.1-compliant preprocessors for OMG IDL.  By using this standard
-implementation, developers of OMG IDL compilers will save many months
-of work and enhance the portability and interoperability of OMG
-IDL-interfaced objects.
-
-The SunSoft OMG IDL CFE allows convenient and fast integration of new back
-ends to the compiler.  The release consists of a front end which converts
-OMG IDL to an intermediate format, a compiler framework driver, an example
-implementation of a compiler back end, and a set of protocols for
-interaction between the front and back ends.  The SunSoft OMG IDL CFE
-parser uses components generated by yacc and lex.
-
-The SunSoft OMG IDL CFE is designed to allow easy extension of OMG IDL
-without impacting existing back-end implementations.  As the CORBA
-specification evolves, any new updates to the IDE CFE will be placed
-by SunSoft on the OMG server.
-
-This release provides a directory with many examples of OMG IDL
-specifications to allow users to become familiar with the process of
-writing OMG IDL code.
-
-For more information send email to idl-cfe@sun.com.
-
-HOW:
-
-The SunSoft OMG IDL CFE is available at no charge through anonymous FTP
-in source form on the OMG file server, omg.org. Please retrieve the
-file OMG_IDL_CFE_1.3.tar.Z from the directory pub/OMG_IDL_CFE_1.3. Please
-let us know who you are if you retrieve the compiler front end using this
-method, by sending email to idl-cfe@sun.com.
-
-You can also retrieve the software by using the OMG mail server program.
-Send email with the subject 'help' to omg_idl@omg.org, and the mail server
-will respond with instructions on how to retrieve the software.
-
-WHEN:
-
-The SunSoft OMG IDL CFE is available now.
-
-CONTACT:
-
-Please let us know who you are if you decide to use this software, and how
-you use it. Please send email to:
-
-     idl-cfe@sun.com
-
-This address can also be used to report problems, bugs, suggestions and
-send general comments.
-
-We ask that if you make extensions or modifications to this source release,
-please make these extensions available to others using the OMG IDL compiler
-front end, by sending the modified sources to the above email address. This
-will help us evaluate your extensions for inclusion in a future version. It
-also ensures your investment in these extensions when new versions of the
-CFE are released.
-
-NOTE:
-
-SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are
-trademarks or registered trademarks of Sun Microsystems, Inc.
-
-COPYRIGHT NOTICE:
-
-Copyright 1992, 1993, 1994 Sun Microsystems, Inc.  Printed in the United
-States of America.  All Rights Reserved.
-
-This product is protected by copyright and distributed under the following
-license restricting its use.
-
-The Interface Definition Language Compiler Front End (CFE) is made
-available for your use provided that you include this license and copyright
-notice on all media and documentation and the software program in which
-this product is incorporated in whole or part. You may copy and extend
-functionality (but may not remove functionality) of the Interface
-Definition Language CFE without charge, but you are not authorized to
-license or distribute it to anyone else except as part of a product or
-program developed by you or with the express written consent of Sun
-Microsystems, Inc. ("Sun").
-
-The names of Sun Microsystems, Inc. and any of its subsidiaries or
-affiliates may not be used in advertising or publicity pertaining to
-distribution of Interface Definition Language CFE as permitted herein.
-
-This license is effective until terminated by Sun for failure to comply
-with this license.  Upon termination, you shall destroy or return all code
-and documentation for the Interface Definition Language CFE.
-
-INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED AS IS WITH NO WARRANTIES OF
-ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS
-FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR ARISING FROM A COURSE OF
-DEALING, USAGE OR TRADE PRACTICE.
-
-INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED WITH NO SUPPORT AND WITHOUT
-ANY OBLIGATION ON THE PART OF Sun OR ANY OF ITS SUBSIDIARIES OR AFFILIATES
-TO ASSIST IN ITS USE, CORRECTION, MODIFICATION OR ENHANCEMENT.
-
-SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES SHALL HAVE NO LIABILITY WITH
-RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY
-INTERFACE DEFINITION LANGUAGE CFE OR ANY PART THEREOF.
-
-IN NO EVENT WILL SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES BE LIABLE FOR
-ANY LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL
-DAMAGES, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-Use, duplication, or disclosure by the government is subject to
-restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in
-Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR
-52.227-19.
-
-Sun, Sun Microsystems and the Sun logo are trademarks or registered
-trademarks of Sun Microsystems, Inc.
-
-SunSoft, Inc.  
-2550 Garcia Avenue 
-Mountain View, California  94043
diff --git a/TAO/TAO_IDL/docs/CHANGES b/TAO/TAO_IDL/docs/CHANGES
deleted file mode 100644
index ae6fca7bcea..00000000000
--- a/TAO/TAO_IDL/docs/CHANGES
+++ /dev/null
@@ -1,122 +0,0 @@
-CHANGES WHICH AFFECT BE WRITERS
--=============================-
-
-INTRODUCTION
-
-This file describes changes that affect BE writers. It contains IMPORTANT
-INFORMATION for BE writers who wish to migrate a BE written to operate with
-release 1.2 to operate with release 1.3. It is likely that not following
-these instructions will result in a compilable but malfunctioning compiler.
-
-AST INHERITANCE CHANGES
-
-The AST has been reorganized so that AST_Union and AST_Exception now
-inherit from AST_Structure. This means that constructors of BE classes
-which inherit from AST_Union or AST_Exception now need to explicitly call
-an initializer for AST_Structure in their init section.
-
-We repeat below the information given in the file WRITING_A_BE, in the
-section entitled "WRITING A BE".
-
-AST_EXCEPTION
-
-The signature for constructors of classes inheriting from AST_Exception
-should now be:
-
-	BE_Exception::BE_Exception(UTL_ScopedName *n,
-				   UTL_StrList *p)
-		    : AST_Decl(AST_Decl::NT_except, n, p),
-		      AST_Structure(AST_Decl::NT_except, n, p),
-		      UTL_Scope(AST_Decl::NT_except)
-
-AST_UNION
-
-The signature for constructors of classes inheriting from AST_Union should
-now be:
-
-	BE_Union::BE_Union(AST_ConcreteType *dt,
-			   UTL_ScopedName *n,
-			   UTL_StrList *p)
-		: AST_Union(dt, n, p),
-		  AST_Structure(AST_Decl::NT_union, n, p),
-		  AST_Decl(AST_Decl::NT_union, n, p),
-		  UTL_Scope(AST_Decl::NT_union)
-
-IDL_BOOL TYPE
-
-To increase portability and reduce dependency of the sources on POSIX
-compliance in targets of ports, IDL now provides its own boolean type which
-is named idl_bool. It provides two truth values, I_TRUE and I_FALSE.
-
-UTL_SCOPEDNAME TYPE
-
-The UTL_ScopedName type is now a list of Identifier nodes; in previous
-releases it used to be a list of String nodes. If your BE constructs scoped
-names this change will prevent recompilation until you modify your
-constructor calls to invoke constructors for Identifier instead of for
-String. The signature of the constructor is:
-
-	Identifier::Identifier(char *, long x=1, long y=0, long z=I_FALSE)
-
-The additional arguments which can be defaulted to the values indicated are
-included for future use.
-
-COPYRIGHT
-
-Copyright 1992, 1993, 1994 Sun Microsystems, Inc.  Printed in the United
-States of America.  All Rights Reserved.
-
-This product is protected by copyright and distributed under the following
-license restricting its use.
-
-The Interface Definition Language Compiler Front End (CFE) is made
-available for your use provided that you include this license and copyright
-notice on all media and documentation and the software program in which
-this product is incorporated in whole or part. You may copy and extend
-functionality (but may not remove functionality) of the Interface
-Definition Language CFE without charge, but you are not authorized to
-license or distribute it to anyone else except as part of a product or
-program developed by you or with the express written consent of Sun
-Microsystems, Inc. ("Sun").
-
-The names of Sun Microsystems, Inc. and any of its subsidiaries or
-affiliates may not be used in advertising or publicity pertaining to
-distribution of Interface Definition Language CFE as permitted herein.
-
-This license is effective until terminated by Sun for failure to comply
-with this license.  Upon termination, you shall destroy or return all code
-and documentation for the Interface Definition Language CFE.
-
-INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED AS IS WITH NO WARRANTIES OF
-ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS
-FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR ARISING FROM A COURSE OF
-DEALING, USAGE OR TRADE PRACTICE.
-
-INTERFACE DEFINITION LANGUAGE CFE IS PROVIDED WITH NO SUPPORT AND WITHOUT
-ANY OBLIGATION ON THE PART OF Sun OR ANY OF ITS SUBSIDIARIES OR AFFILIATES
-TO ASSIST IN ITS USE, CORRECTION, MODIFICATION OR ENHANCEMENT.
-
-SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES SHALL HAVE NO LIABILITY WITH
-RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY
-INTERFACE DEFINITION LANGUAGE CFE OR ANY PART THEREOF.
-
-IN NO EVENT WILL SUN OR ANY OF ITS SUBSIDIARIES OR AFFILIATES BE LIABLE FOR
-ANY LOST REVENUE OR PROFITS OR OTHER SPECIAL, INDIRECT AND CONSEQUENTIAL
-DAMAGES, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-Use, duplication, or disclosure by the government is subject to
-restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in
-Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR
-52.227-19.
-
-Sun, Sun Microsystems and the Sun logo are trademarks or registered
-trademarks of Sun Microsystems, Inc.
-
-SunSoft, Inc.  
-2550 Garcia Avenue 
-Mountain View, California  94043
-
-NOTE:
-
-SunOS, SunSoft, Sun, Solaris, Sun Microsystems or the Sun logo are
-trademarks or registered trademarks of Sun Microsystems, Inc.
diff --git a/TAO/TAO_IDL/docs/README.md b/TAO/TAO_IDL/docs/README.md
new file mode 100644
index 00000000000..d8cfeac28ed
--- /dev/null
+++ b/TAO/TAO_IDL/docs/README.md
@@ -0,0 +1,50 @@
+# TAO\_IDL Developer Documentation
+
+## Topics
+
+- [Historical Document Describing How to Write a Backend](WRITING_A_BE).
+- [Less Relevant Historical Documents from Sun](historical)
+
+## TAO\_IDL File Layout
+
+TAO\_IDL is broken up into a few different modules, these can be generalized
+as:
+
+- AST
+  - "Abstract Syntax Tree"
+  - Nodes representing the Abstract Syntax Tree
+- FE
+  - "Front End"
+  - Parsing functionality that generates the Abstract Syntax Tree.
+  - Among other things, contains the Bison grammar `fe/idl.ypp` and Flex
+    token `fe/idl.ll` files.
+- BE
+  - "Back End"
+  - Transformed Abstract Syntax Tree
+- UTL
+  - "Util"
+  - Utility Classes and Functions.
+  - Contains `idl_global` class which is made up of `include/idl_global.h` and
+    `utl/utl_global.cpp`.
+- DRV
+  - "Driver"
+  - The `tao_idl` program it self which drives the other modules.
+
+These are broken into these places on the file system:
+
+- `include`
+  - Contains the header files for AST, FE, and UTL modules.
+- `ast`
+  - Contains the source files for AST modules classes.
+- `fe`
+  - Contains the source files and some header files for the FE module
+- `be_include`
+  - Contains the header files for the BE module.
+- `be`
+  - Contains the source files for the BE module.
+- `driver`
+  - Contains some parts of DRV.
+- `util`
+  - Contains the souce files for the UTL module.
+- `narrow`
+  - Leftover from a custom casting system.
diff --git a/TAO/TAO_IDL/docs/WRITING_A_BE b/TAO/TAO_IDL/docs/WRITING_A_BE
index 5c3c069f7a1..e0141e8987b 100644
--- a/TAO/TAO_IDL/docs/WRITING_A_BE
+++ b/TAO/TAO_IDL/docs/WRITING_A_BE
@@ -1,3 +1,8 @@
+WARNING! This document is historical but left out of the historical directory
+because it describes the basic architecture of the compiler that mostly still
+apply as of writing. Refer to the code itself for up to date information such
+as what AST Nodes are in use.
+
 OMG INTERFACE DEFINITION LANGUAGE COMPILER FRONT END PROTOCOLS
 ==============================================================
 
diff --git a/TAO/TAO_IDL/ANNOUNCEMENT b/TAO/TAO_IDL/docs/historical/ANNOUNCEMENT
index 870db6f6006..870db6f6006 100644
--- a/TAO/TAO_IDL/ANNOUNCEMENT
+++ b/TAO/TAO_IDL/docs/historical/ANNOUNCEMENT
diff --git a/TAO/TAO_IDL/docs/BUG_REPORT b/TAO/TAO_IDL/docs/historical/BUG_REPORT
index 28c34ae141d..28c34ae141d 100644
--- a/TAO/TAO_IDL/docs/BUG_REPORT
+++ b/TAO/TAO_IDL/docs/historical/BUG_REPORT
diff --git a/TAO/TAO_IDL/CHANGES b/TAO/TAO_IDL/docs/historical/CHANGES
index ae6fca7bcea..ae6fca7bcea 100644
--- a/TAO/TAO_IDL/CHANGES
+++ b/TAO/TAO_IDL/docs/historical/CHANGES
diff --git a/TAO/TAO_IDL/docs/CLI b/TAO/TAO_IDL/docs/historical/CLI
index a61c2bae365..a61c2bae365 100644
--- a/TAO/TAO_IDL/docs/CLI
+++ b/TAO/TAO_IDL/docs/historical/CLI
diff --git a/TAO/TAO_IDL/docs/INSTALL b/TAO/TAO_IDL/docs/historical/INSTALL
index 6fcaa710042..6fcaa710042 100644
--- a/TAO/TAO_IDL/docs/INSTALL
+++ b/TAO/TAO_IDL/docs/historical/INSTALL
diff --git a/TAO/TAO_IDL/docs/PROBLEMS b/TAO/TAO_IDL/docs/historical/PROBLEMS
index 65cfb6a1893..65cfb6a1893 100644
--- a/TAO/TAO_IDL/docs/PROBLEMS
+++ b/TAO/TAO_IDL/docs/historical/PROBLEMS
diff --git a/TAO/TAO_IDL/docs/README b/TAO/TAO_IDL/docs/historical/README
index 700c1c1a707..700c1c1a707 100644
--- a/TAO/TAO_IDL/docs/README
+++ b/TAO/TAO_IDL/docs/historical/README
diff --git a/TAO/TAO_IDL/docs/ROADMAP b/TAO/TAO_IDL/docs/historical/ROADMAP
index 5da0d83823c..5da0d83823c 100644
--- a/TAO/TAO_IDL/docs/ROADMAP
+++ b/TAO/TAO_IDL/docs/historical/ROADMAP