This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[patch, fortran, docs] Reorganization of gfortran.texi.
- From: Brooks Moses <brooks dot moses at codesourcery dot com>
- To: gcc-patches at gcc dot gnu dot org
- Cc: fortran at gcc dot gnu dot org
- Date: Fri, 15 Dec 2006 17:44:06 -0800
- Subject: [patch, fortran, docs] Reorganization of gfortran.texi.
:ADDPATCH fortran:
This patch implements the reorganization to gfortran.texi that I
proposed a couple of weeks ago. For reference, the revised table of
contents (with the section numbers from the original version) is as follows:
----------------------------------------------------
0. Introduction (one paragraph intro)
Part I: About GNU Fortran
1. Getting Started (what gfortran does, components)
2. GFortran and GCC (what GCC is, gfortran is front-end)
3. GFortran and G77 (why this is not g77v4)
5. Project Status (one-paragraph intro)
5.1 Compiler and Library Status (what gfortran can do now)
10. Standards (a brief list of supported standards)
Part II: Invoking GNU Fortran
4. GFortran Command Options (command-line reference)
6. Runtime Environment Variables (reference)
Part III: Language Reference
10.1 F2003 Status (a list of F2003 features supported)
7. Extensions (a collection of reference bits)
8. Intrinsic Procedures (a long collection of reference bits)
9. Contributing
5.2 Proposed Extensions (a short eclectic list)
GPL, etc. as before
----------------------------------------------------
As noted earlier, this is _only_ a reorganization; there is no new text
anywhere other than the part headings, and nothing has been removed.
I'll work on adjustments to those in later patches.
There is one new complication to the patch -- Texinfo currently does not
include macros to divide documents into parts. I brought this up on the
Texinfo mailing list, and the maintainer (Karl Berry) says that it's
something that's been deep in the to-do list for a while, and he had
some suggestions for how to go about implementing them. I'm expecting
to work this into a proper patch to submit to the upstream Texinfo
distribution, but that will likely take a while; in the interim, the
first part of this patch contains a local implementation (based on his
suggestions) that works reasonably well.
Specifically, the division of the document into parts doesn't affect the
info side of things at all, other than the (non-linked) changes I've
made to the top-level @menu. On the TeX side, it adds a "Part N..."
line to the tables of contents, and creates a "title page" for each
part, which is fairly similar to the overall title page in style.
Changelog entry:
-----------------------------------------------------------
2006-12-15 Brooks Moses <brooks.moses@codesourcery.com>
* gfortran.texi: Added TeX support for document parts;
rearranged existing text into "About GNU Fortran",
"Invoking GNU Fortran", and "Language Reference" parts.
-----------------------------------------------------------
Tested with "make info", "make pdf", "make dvi", and, just to be sure I
haven't messed things up, "cd gcc; make man", on i686-pc-cygwin.
Ok for trunk? Ok to backport to 4.2, so that it remains easy to
synchronize later improvements/fixes to the manual?
- Brooks
Index: gfortran.texi
===================================================================
--- gfortran.texi (revision 119846)
+++ gfortran.texi (working copy)
@@ -16,6 +16,45 @@
@syncodeindex pg cp
@syncodeindex tp cp
+@c TODO: The following "Part" definitions are included here temporarily
+@c until they are incorporated into the official Texinfo distribution.
+@c They borrow heavily from Texinfo's \unnchapentry definitions.
+
+@tex
+\gdef\part#1#2{%
+ \pchapsepmacro
+ \gdef\thischapter{}
+ \begingroup
+ \vglue\titlepagetopglue
+ \titlefonts \rm
+ \leftline{Part #1:@* #2}
+ \vskip4pt \hrule height 4pt width \hsize \vskip4pt
+ \endgroup
+ \writetocentry{part}{#2}{#1}
+}
+\gdef\blankpart{%
+ \writetocentry{blankpart}{}{}
+}
+% Part TOC-entry definition for summary contents.
+\gdef\dosmallpartentry#1#2#3#4{%
+ \vskip .5\baselineskip plus.2\baselineskip
+ \begingroup
+ \let\rm=\bf \rm
+ \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup}
+ \endgroup
+}
+\gdef\dosmallblankpartentry#1#2#3#4{%
+ \vskip .5\baselineskip plus.2\baselineskip
+}
+% Part TOC-entry definition for regular contents. This has to be
+% equated to an existing entry to not cause problems when the PDF
+% outline is created.
+\gdef\dopartentry#1#2#3#4{%
+ \unnchapentry{Part #2: #1}{}{#3}{#4}
+}
+\gdef\doblankpartentry#1#2#3#4{}
+@end tex
+
@c %**end of header
@c Use with @@smallbook.
@@ -94,8 +133,22 @@
@sp 1
@insertcopying
@end titlepage
+
+@c TODO: The following "Part" definitions are included here temporarily
+@c until they are incorporated into the official Texinfo distribution.
+
+@tex
+\global\let\partentry=\dosmallpartentry
+\global\let\blankpartentry=\dosmallblankpartentry
+@end tex
@summarycontents
+
+@tex
+\global\let\partentry=\dopartentry
+\global\let\blankpartentry=\doblankpartentry
+@end tex
@contents
+
@page
@node Top
@@ -118,16 +171,23 @@
@comment better formatting.
@comment
@menu
+Part I: About GNU Fortran
* Getting Started:: What you should know about GNU Fortran.
* GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
* GNU Fortran and G77:: Why we chose to start from scratch.
-* Invoking GNU Fortran:: Command options supported by @command{gfortran}.
* Project Status:: Status of GNU Fortran, roadmap, proposed extensions.
-* Contributing:: How you can help.
* Standards:: Standards supported by GNU Fortran.
+
+Part II: Invoking GNU Fortran
+* Invoking GNU Fortran:: Command options supported by @command{gfortran}.
* Runtime:: Influencing runtime behavior with environment variables.
+
+Part III: Language Reference
+* Fortran 2003 status:: Fortran 2003 features supported by GNU Fortran.
* Extensions:: Language extensions implemented by GNU Fortran.
* Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
+
+* Contributing:: How you can help.
* Copying:: GNU General Public License says
how you can copy and share GNU Fortran.
* GNU Free Documentation License::
@@ -137,7 +197,14 @@
@end menu
+@c =====================================================================
+@c PART I: ABOUT GNU FORTRAN
+@c =====================================================================
+@tex
+\part{I}{About GNU Fortran}
+@end tex
+
@c ---------------------------------------------------------------------
@c Getting Started
@c ---------------------------------------------------------------------
@@ -255,7 +322,6 @@
@end itemize
-
@c ---------------------------------------------------------------------
@c GNU Fortran and GCC
@c ---------------------------------------------------------------------
@@ -308,7 +374,6 @@
command line options.
-
@c ---------------------------------------------------------------------
@c GNU Fortran and G77
@c ---------------------------------------------------------------------
@@ -349,7 +414,6 @@
develop ourselves than to do a major overhaul of @command{g77} first,
and then build a Fortran 95 compiler out of it.
-@include invoke.texi
@c ---------------------------------------------------------------------
@c Project Status
@@ -374,14 +438,6 @@
(even though Andy had already been working on it for a while,
of course).
-@menu
-* Compiler and Library Status::
-* Proposed Extensions::
-@end menu
-
-@node Compiler and Library Status
-@section Compiler and Library Status
-
The GNU Fortran compiler is able to compile nearly all
standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs,
including a number of standard and non-standard extensions, and can be
@@ -419,100 +475,41 @@
future standards---in particular, Fortran 2003.
-@node Proposed Extensions
-@section Proposed Extensions
+@c ---------------------------------------------------------------------
+@c Standards
+@c ---------------------------------------------------------------------
-Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
-order. Most of these are necessary to be fully compatible with
-existing Fortran compilers, but they are not part of the official
-J3 Fortran 95 standard.
+@node Standards
+@chapter Standards
+@cindex Standards
-@subsection Compiler extensions:
-@itemize @bullet
-@item
-User-specified alignment rules for structures.
+The GNU Fortran compiler implements
+ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all
+standard-compliant Fortran 90 and Fortran 77 programs. It also supports
+the ISO/IEC TR-15581 enhancements to allocatable arrays, and
+the @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
+OpenMP Application Program Interface v2.5} specification.
-@item
-Flag to generate @code{Makefile} info.
+In the future, the GNU Fortran compiler may also support other standard
+variants of and extensions to the Fortran language. These include
+ISO/IEC 1539-1:2004 (Fortran 2003).
-@item
-Automatically extend single precision constants to double.
-@item
-Compile code that conserves memory by dynamically allocating common and
-module storage either on stack or heap.
+@c =====================================================================
+@c PART II: INVOCATION REFERENCE
+@c =====================================================================
-@item
-Compile flag to generate code for array conformance checking (suggest -CC).
+@tex
+\part{II}{Invoking GNU Fortran}
+@end tex
-@item
-User control of symbol names (underscores, etc).
+@c ---------------------------------------------------------------------
+@c Compiler Options
+@c ---------------------------------------------------------------------
-@item
-Compile setting for maximum size of stack frame size before spilling
-parts to static or heap.
+@include invoke.texi
-@item
-Flag to force local variables into static space.
-@item
-Flag to force local variables onto stack.
-
-@item
-Flag for maximum errors before ending compile.
-
-@item
-Option to initialize otherwise uninitialized integer and floating
-point variables.
-@end itemize
-
-
-@subsection Environment Options
-@itemize @bullet
-@item
-Pluggable library modules for random numbers, linear algebra.
-LA should use BLAS calling conventions.
-
-@item
-Environment variables controlling actions on arithmetic exceptions like
-overflow, underflow, precision loss---Generate NaN, abort, default.
-action.
-
-@item
-Set precision for fp units that support it (i387).
-
-@item
-Variable for setting fp rounding mode.
-
-@item
-Variable to fill uninitialized variables with a user-defined bit
-pattern.
-
-@item
-Environment variable controlling filename that is opened for that unit
-number.
-
-@item
-Environment variable to clear/trash memory being freed.
-
-@item
-Environment variable to control tracing of allocations and frees.
-
-@item
-Environment variable to display allocated memory at normal program end.
-
-@item
-Environment variable for filename for * IO-unit.
-
-@item
-Environment variable for temporary file directory.
-
-@item
-Environment variable forcing standard output to be line buffered (unix).
-
-@end itemize
-
-
@c ---------------------------------------------------------------------
@c Runtime
@c ---------------------------------------------------------------------
@@ -688,7 +685,107 @@
setting a default data representation for the whole program. The
@code{CONVERT} specifier overrides the @code{-fconvert} compile options.
+
+@c =====================================================================
+@c PART III: LANGUAGE REFERENCE
+@c =====================================================================
+
+@tex
+\part{III}{Language Reference}
+@end tex
+
@c ---------------------------------------------------------------------
+@c Fortran 2003 Status
+@c ---------------------------------------------------------------------
+
+@node Fortran 2003 status
+@chapter Fortran 2003 Status
+
+Although GNU Fortran focuses on implementing the Fortran 95
+standard for the time being, a few Fortran 2003 features are currently
+available.
+
+@itemize
+@item
+Intrinsics @code{command_argument_count}, @code{get_command},
+@code{get_command_argument}, @code{get_environment_variable}, and
+@code{move_alloc}.
+
+@item
+@cindex Array constructors
+@cindex @code{[...]}
+Array constructors using square brackets. That is, @code{[...]} rather
+than @code{(/.../)}.
+
+@item
+@cindex @code{FLUSH} statement
+@code{FLUSH} statement.
+
+@item
+@cindex @code{IOMSG=} specifier
+@code{IOMSG=} specifier for I/O statements.
+
+@item
+@cindex @code{ENUM} statement
+@cindex @code{ENUMERATOR} statement
+@cindex @command{-fshort-enums}
+Support for the declaration of enumeration constants via the
+@code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
+@command{gcc} is guaranteed also for the case where the
+@command{-fshort-enums} command line option is given.
+
+@item
+@cindex TR 15581
+TR 15581:
+@itemize
+@item
+@cindex @code{ALLOCATABLE} dummy arguments
+@code{ALLOCATABLE} dummy arguments.
+@item
+@cindex @code{ALLOCATABLE} function results
+@code{ALLOCATABLE} function results
+@item
+@cindex @code{ALLOCATABLE} components of derived types
+@code{ALLOCATABLE} components of derived types
+@end itemize
+
+@item
+@cindex @code{STREAM} I/O
+@cindex @code{ACCESS='STREAM'} I/O
+The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
+allowing I/O without any record structure.
+
+@item
+Namelist input/output for internal files.
+
+@item
+@cindex @code{PROTECTED}
+The @code{PROTECTED} statement and attribute.
+
+@item
+@cindex @code{VALUE}
+The @code{VALUE} statement and attribute.
+
+@item
+@cindex @code{VOLATILE}
+The @code{VOLATILE} statement and attribute.
+
+@item
+@cindex @code{IMPORT}
+The @code{IMPORT} statement, allowing to import
+host-associated derived types.
+
+@item
+@cindex @code{USE, INTRINSIC}
+@cindex @code{ISO_FORTRAN_ENV}
+@code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
+attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
+@code{OMP_LIB} and @code{OMP_LIB_KINDS}.
+
+@end itemize
+
+
+@c ---------------------------------------------------------------------
@c Extensions
@c ---------------------------------------------------------------------
@@ -1176,15 +1273,22 @@
OpenMP Application Program Interface v2.5} specification.
@c ---------------------------------------------------------------------
-@include intrinsic.texi
+@c Intrinsic Procedures
@c ---------------------------------------------------------------------
+@include intrinsic.texi
+
+
+@tex
+\blankpart
+@end tex
+
@c ---------------------------------------------------------------------
@c Contributing
@c ---------------------------------------------------------------------
@node Contributing
-@chapter Contributing
+@unnumbered Contributing
@cindex Contributing
Free software is only possible if people contribute to efforts
@@ -1206,6 +1310,7 @@
@menu
* Contributors::
* Projects::
+* Proposed Extensions::
@end menu
@@ -1300,113 +1405,97 @@
@c TODO: email!
-@c ---------------------------------------------------------------------
-@c Standards
-@c ---------------------------------------------------------------------
+@node Proposed Extensions
+@section Proposed Extensions
-@node Standards
-@chapter Standards
-@cindex Standards
+Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
+order. Most of these are necessary to be fully compatible with
+existing Fortran compilers, but they are not part of the official
+J3 Fortran 95 standard.
-The GNU Fortran compiler implements
-ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all
-standard-compliant Fortran 90 and Fortran 77 programs. It also supports
-the ISO/IEC TR-15581 enhancements to allocatable arrays, and
-the @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
-OpenMP Application Program Interface v2.5} specification.
+@subsection Compiler extensions:
+@itemize @bullet
+@item
+User-specified alignment rules for structures.
-In the future, the GNU Fortran compiler may also support other standard
-variants of and extensions to the Fortran language. These include
-ISO/IEC 1539-1:2004 (Fortran 2003).
+@item
+Flag to generate @code{Makefile} info.
-@menu
-* Fortran 2003 status::
-@end menu
+@item
+Automatically extend single precision constants to double.
-@node Fortran 2003 status
-@section Fortran 2003 status
+@item
+Compile code that conserves memory by dynamically allocating common and
+module storage either on stack or heap.
-Although GNU Fortran focuses on implementing the Fortran 95
-standard for the time being, a few Fortran 2003 features are currently
-available.
+@item
+Compile flag to generate code for array conformance checking (suggest -CC).
-@itemize
-@item
-Intrinsics @code{command_argument_count}, @code{get_command},
-@code{get_command_argument}, @code{get_environment_variable}, and
-@code{move_alloc}.
+@item
+User control of symbol names (underscores, etc).
-@item
-@cindex Array constructors
-@cindex @code{[...]}
-Array constructors using square brackets. That is, @code{[...]} rather
-than @code{(/.../)}.
+@item
+Compile setting for maximum size of stack frame size before spilling
+parts to static or heap.
@item
-@cindex @code{FLUSH} statement
-@code{FLUSH} statement.
+Flag to force local variables into static space.
@item
-@cindex @code{IOMSG=} specifier
-@code{IOMSG=} specifier for I/O statements.
+Flag to force local variables onto stack.
@item
-@cindex @code{ENUM} statement
-@cindex @code{ENUMERATOR} statement
-@cindex @command{-fshort-enums}
-Support for the declaration of enumeration constants via the
-@code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
-@command{gcc} is guaranteed also for the case where the
-@command{-fshort-enums} command line option is given.
+Flag for maximum errors before ending compile.
@item
-@cindex TR 15581
-TR 15581:
-@itemize
+Option to initialize otherwise uninitialized integer and floating
+point variables.
+@end itemize
+
+
+@subsection Environment Options
+@itemize @bullet
@item
-@cindex @code{ALLOCATABLE} dummy arguments
-@code{ALLOCATABLE} dummy arguments.
+Pluggable library modules for random numbers, linear algebra.
+LA should use BLAS calling conventions.
+
@item
-@cindex @code{ALLOCATABLE} function results
-@code{ALLOCATABLE} function results
+Environment variables controlling actions on arithmetic exceptions like
+overflow, underflow, precision loss---Generate NaN, abort, default.
+action.
+
@item
-@cindex @code{ALLOCATABLE} components of derived types
-@code{ALLOCATABLE} components of derived types
-@end itemize
+Set precision for fp units that support it (i387).
@item
-@cindex @code{STREAM} I/O
-@cindex @code{ACCESS='STREAM'} I/O
-The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
-allowing I/O without any record structure.
+Variable for setting fp rounding mode.
@item
-Namelist input/output for internal files.
+Variable to fill uninitialized variables with a user-defined bit
+pattern.
@item
-@cindex @code{PROTECTED}
-The @code{PROTECTED} statement and attribute.
+Environment variable controlling filename that is opened for that unit
+number.
@item
-@cindex @code{VALUE}
-The @code{VALUE} statement and attribute.
+Environment variable to clear/trash memory being freed.
@item
-@cindex @code{VOLATILE}
-The @code{VOLATILE} statement and attribute.
+Environment variable to control tracing of allocations and frees.
@item
-@cindex @code{IMPORT}
-The @code{IMPORT} statement, allowing to import
-host-associated derived types.
+Environment variable to display allocated memory at normal program end.
@item
-@cindex @code{USE, INTRINSIC}
-@cindex @code{ISO_FORTRAN_ENV}
-@code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
-attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
-@code{OMP_LIB} and @code{OMP_LIB_KINDS}.
+Environment variable for filename for * IO-unit.
+@item
+Environment variable for temporary file directory.
+
+@item
+Environment variable forcing standard output to be line buffered (unix).
+
@end itemize