COBOL: documentation updates for gcobol

gcc/
	* doc/contrib.texi: Update for gcobol.
	* doc/frontends.texi: Likewise.
	* doc/install.texi: Likewise.
	* doc/invoke.texi: Likewise.
	* doc/sourcebuild.texi: Likewise.
	* doc/standards.texi: Likewise.

6 files changed, 84 insertions, 22 deletions

diff --git a/gcc/doc/contrib.texi b/gcc/doc/contrib.texi
index 10dc643..17e0888 100644
--- a/gcc/doc/contrib.texi
+++ b/gcc/doc/contrib.texi
@@ -269,6 +269,10 @@ maintaining @code{complex<>}, sanity checking and disbursement, configuration
 architecture, libio maintenance, and early math work.
 
 @item
+Robert J. Dubner for his work on the COBOL front end, mating the
+parser output to the GENERIC tree.
+
+@item
 Fran@,{c}ois Dumont for his work on libstdc++-v3, especially maintaining and
 improving @code{debug-mode} and associative and unordered containers.
 
@@ -605,6 +609,10 @@ Dave Love for his ongoing work with the Fortran front end and
 runtime libraries.
 
 @item
+James K. Lowden for his work on the COBOL front end, mainly the parser
+and CDF.
+
+@item
 Martin von L@"owis for internal consistency checking infrastructure,
 various C++ improvements including namespace support, and tons of
 assistance with libstdc++/compiler merges.
diff --git a/gcc/doc/frontends.texi b/gcc/doc/frontends.texi
index 73c222c..acd0594 100644
--- a/gcc/doc/frontends.texi
+++ b/gcc/doc/frontends.texi
@@ -31,23 +31,23 @@ The language-independent component of GCC includes the majority of the
 optimizers, as well as the ``back ends'' that generate machine code for
 various processors.
 
-@cindex COBOL
 @cindex Mercury
 The part of a compiler that is specific to a particular language is
 called the ``front end''.  In addition to the front ends that are
 integrated components of GCC, there are several other front ends that
-are maintained separately.  These support languages such as
-Mercury, and COBOL@.  To use these, they must be built together with
-GCC proper.
+are maintained separately.  These support languages such as Mercury.
+To use these, they must be built together with GCC proper.
 
+@cindex Ada
 @cindex C++
+@cindex COBOL
 @cindex G++
-@cindex Ada
 @cindex GNAT
 Most of the compilers for languages other than C have their own names.
-The C++ compiler is G++, the Ada compiler is GNAT, and so on.  When we
-talk about compiling one of those languages, we might refer to that
-compiler by its own name, or as GCC@.  Either is correct.
+The C++ compiler is G++, the COBOL compiler is gcobol, the Ada
+compiler is GNAT, and so on.  When we talk about compiling one of
+those languages, we might refer to that compiler by its own name, or
+as GCC@.  Either is correct.
 
 @cindex compiler compared to C++ preprocessor
 @cindex intermediate C version, nonexistent
diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 189b5f9..994fadc 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -291,11 +291,39 @@ Ada runtime libraries. You can check that your build environment is clean
 by verifying that @samp{gnatls -v} lists only one explicit path in each
 section.
 
+@cindex cobol
+@item @anchor{GCOBOL-prerequisite}GCOBOL
+
+The COBOL compiler, gcobol, first appeared in GCC 15.  To build the
+COBOL parser, you need GNU Bison 3.5.1 or later (but not 3.8.0). To build
+the lexer requires GNU Flex 2.6.4, the current version as of this writing,
+released on 2017-05-06.
+
+The gcobol documentation is maintained as manpages using troff
+mdoc. GNU groff is required to convert them to PDF format.  Conversion
+to HTML is done with mandoc, available at
+@uref{http://mdocml.bsd.lv/}.
+
+Because ISO COBOL defines strict requirements for numerical precision,
+gcobol requires hardware with 128-bit computation instructions.  This
+requirement applies to both host and target. For integer and
+fixed-point computation, gcobol uses
+@deftp {Data type} __int128
+@end deftp
+meaning @code{16 == sizeof(long long int)}.
+For floating point, gcobol uses
+@deftp {Data type} _Float128
+@end deftp
+(On some architectures, GCC supports 128-bit floating point in software.)
+
+gcobol has so far been tested on two architectures only: x86_64 and
+aarch64 with little-endian encoding.
+
 @item @anchor{GDC-prerequisite}GDC
 
-In order to build GDC, the D compiler, you need a working GDC
-compiler (GCC version 9.4 or later) and D runtime library,
-@samp{libphobos}, as the D front end is written in D.
+In order to build GDC, the D compiler, you need a working GDC compiler
+(GCC version 9.4 or later) and D runtime library, @samp{libphobos}, as
+the D front end is written in D.
 
 Versions of GDC prior to 12 can be built with an ISO C++11 compiler, which can
 then be installed and used to bootstrap newer versions of the D front end.
@@ -568,6 +596,14 @@ Necessary to build GCC during development because the generated output
 files are not included in the version-controlled source repository.
 They are included in releases.
 
+@item Bison version 3.5.1 or later (but not 3.8.0)
+
+Necessary when modifying @file{*.y} files in the COBOL front end.
+
+Necessary to build GCC during development because the generated output
+files are not included in the version-controlled source repository.
+They are included in releases.
+
 @item Texinfo version 4.7 (or later)
 
 Necessary for running @command{makeinfo} when modifying @file{*.texi}
@@ -644,13 +680,14 @@ HTTPS as tarballs compressed with @command{gzip} or @command{bzip2}.
 Please refer to the @uref{https://gcc.gnu.org/releases.html,,releases web page}
 for information on how to obtain GCC@.
 
-The source distribution includes the Ada, C, C++, Objective-C, D (GCC 9
-and later), Fortran, Go, and Modula-2 (GCC 13 and later) compilers, as
-well as runtime libraries for C++, Objective-C, and Fortran.
-For previous versions these were downloadable as separate components such
-as the core GCC distribution, which included the C language front end and
-shared components, and language-specific distributions including the
-language front end and the language runtime (where appropriate).
+The source distribution includes the Ada, C, C++, Objective-C, COBOL
+(GCC 15 and later), D (GCC 9 and later), Fortran, Go, and Modula-2
+(GCC 13 and later) compilers, as well as runtime libraries for C++,
+Objective-C, COBOL, and Fortran.  For previous versions these were
+downloadable as separate components such as the core GCC distribution,
+which included the C language front end and shared components, and
+language-specific distributions including the language front end and
+the language runtime (where appropriate).
 
 If you also intend to build binutils (either to upgrade an existing
 installation or for use in place of the corresponding tools of your
@@ -2049,13 +2086,13 @@ their runtime libraries should be built.  For a list of valid values for
 grep ^language= */config-lang.in
 @end smallexample
 Currently, you can use any of the following:
-@code{all}, @code{default}, @code{ada}, @code{c}, @code{c++}, @code{d},
-@code{fortran}, @code{go}, @code{jit}, @code{lto}, @code{m2},
-@code{objc}, @code{obj-c++}.
+@code{all}, @code{default}, @code{ada}, @code{c}, @code{c++},
+@code{cobol}, @code{d}, @code{fortran}, @code{go}, @code{jit},
+@code{lto}, @code{m2}, @code{objc}, @code{obj-c++}.
 Building the Ada compiler has special requirements, see below.
 If you do not pass this flag, or specify the option @code{default}, then the
 default languages available in the @file{gcc} sub-tree will be configured.
-Ada, D, Go, Jit, Objective-C++ and Modula-2 are not default languages.
+Ada, COBOL, D, Go, Jit, Objective-C++ and Modula-2 are not default languages.
 LTO is not a
 default language, but is built by default because @option{--enable-lto} is
 enabled by default.  The other languages are default languages.  If
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 853cb34..afa269b 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1640,6 +1640,12 @@ Free form Fortran source code that should not be preprocessed.
 Free form Fortran source code that must be preprocessed (with the
 traditional preprocessor).
 
+@item @var{file}.cob
+@item @var{file}.COB
+@item @var{file}.cbl
+@item @var{file}.CBL
+COBOL source code.
+
 @item @var{file}.go
 Go source code.
 
@@ -1695,6 +1701,7 @@ objective-c  objective-c-header  objective-c-cpp-output
 objective-c++ objective-c++-header objective-c++-cpp-output
 assembler  assembler-with-cpp
 ada
+cobol
 d
 f77  f77-cpp-input f95  f95-cpp-input
 go
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index d44c2e8..1142039 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -94,6 +94,9 @@ The @code{libffi} library, used as part of the Go runtime library.
 @item libgcc
 The GCC runtime library.
 
+@item libgcobol
+The COBOL runtime library.
+
 @item libgfortran
 The Fortran runtime library.
 
diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi
index a8e9513..bbae350 100644
--- a/gcc/doc/standards.texi
+++ b/gcc/doc/standards.texi
@@ -336,6 +336,13 @@ The authoritative manual on Objective-C 2.0 is available from Apple:
 For more information concerning the history of Objective-C that is
 available online, see @uref{https://gcc.gnu.org/readings.html}
 
+@cindex COBOL
+@section COBOL Language
+
+As of the GCC 15 release, GCC supports the ISO COBOL language standard
+(ISO/IEC 1989:2023). It includes some support for compatibility with
+other COBOL compilers via the @option{-dialect} option.
+
 @section Go Language
 
 As of the GCC 4.7.1 release, GCC supports the Go 1 language standard,