RFC: Reorganization of gfortran.texi

[Brooks Moses <brooks dot moses at codesourcery dot com>]

As I mentioned in the IRC meeting last month, I'm proposing to do a fair 
amount of improvements and reworking to the GFortran manual.  As a first 
step in this, I'd like to propose the following reordering, which 
divides the manual into three major sections: "About GNU Fortran" (which 
discusses what the compiler is, what it can do, and so forth), 
"Invocation Reference" (containing command-line options, 
gfortran-specific environment options, and other aspects of invoking the 
compiler and compiled programs), and "Language Reference" (containing 
information on the Fortran dialect supported by GFortran).

The following proposed section listing has each item prefaced by its 
current section number in the existing manual, for easy reference, and 
the parenthetical notes are my descriptions of what's in the section in 
question.

----------------------------------------------------

0. Introduction                    (one paragraph intro)

(new) 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)

(new) Invocation Reference
        4. GFortran Command Options        (command-line reference)
        6. Runtime Environment Variables   (reference)

(new) 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)

----------------------------------------------------

Note that this proposal doesn't cover adding or removing any text (the 
"(new)" sections are just headings) or any micro-level rearrangements 
and mergers; I figure it's best to discuss those separately.

Comments?  Suggestions?  I'd like to give this about a week for people 
to make comments and suggestions and so forth, and then draw up an 
actual patch to implement the rearrangement so I can get started on the 
lower-level improvements.

I'm proposing to apply this rearrangement to both 4.2 and 4.3; at this 
point the differences between the documentation in the two versions are 
quite minimal, and I think it's good to keep it that way for a while. 
Thoughts?  (Note that documentation changes are exempt from the usual 
"no major changes outside stage 1" rules.)

- Brooks