[Bug-gnupress] [DOCPATCH] Proposed changes to gcc006.txt (#1)

[Simon Law]

On Sat, May 03, 2003 at 09:33:36PM -0700, Paul A. Crable wrote:
> Is there a way I can get my section of the document (gcc006.txt) as 
> ASCII text or as an .RTF file?

        I'm not sure how you are getting each section as a text file
since I've been rendering PDFs.  These are generated from the Texinfo
source, that you can find on my web site as gcc.tar.bz2. [1]

> Is it possible to present data in the form of a table?

        Any form of representation is fine, as long as I can read it.
If you prepare a patch, then it saves me the work of interpreting what
you typed and editing the Texinfo myself.

> Might we not use a word processor, such as Open Office or ABI, to 
> submit changes?  This would allow us to mark up the document so 
> others could view the existing text and the proposed changes 
> together.  The 'Replace "Mumble" with "More mumble"' paradigm is 
> difficult to comprehend. Both Open Office and ABI are free.

        Hmm.  An interesting idea.  However, I suspect that neither of
those will suck in Texinfo and spit it back out again after you are
done.  So it seems to be a rather lossy solution.

> I find that I am making changes to virtually every paragraph, so I 
> intend to forward completely rewritten sections for your 
> consideration, rather than first quoting the old text and then the 
> replacement. 
> 
> In any case, this is the first set of modifications to gcc006.txt:
> 
> 1.  The section headings seem a little confusing to me.
> 
>     They are:
> 
>         3.17.1 M680x0 Options
>         3.17.2 M68hc1x Options
>         3.17.3 VAX Options
>         3.17.4 SPARC Options
>         3.17.5 ARM Options
>         3.17.6 MN10200 Options
>         3.17.7 MN10300 Options
>         3.17.8 M32R/D Options
>         3.17.9 M88K Options
>         3.17.10 IBM RS/6000 and PowerPC Options
> 
>     I suggest repartitioning the set of options as follows:
> 
>         3.17.1 Motorola Options
>               (to contain these existing sections merged as one:
>                       3.17.1 M680x0 Options
>                       3.17.2 M68hc1x Options
>                       3.17.8 M32R/D Options
>                       3.17.9 M88K Options)
>         3.17.2 VAX Options
>         3.17.3 SPARC Options
>         3.17.4 ARM Options
>         3.17.5 Mitsubishi Options
>               (to contain existing sections:
>                       3.17.6 MN10200 Options
>                       3.17.7 MN10300 Options)
>         3.17.6 IBM RS/6000 and PowerPC Options

        How would this work?  The options for M68hc1x are not available
for the M680x0.

> 2.  Throughout this section many option definitions begin with 
> "Generate output for a Mumble microprocessor...".  I propose making a 
> global substition, changing every instance to "Generate code for a 
> Mumble microprocessor...".  "Output" is too vague; the principal 
> output is object code so let's just say so.

        I disagree.  It may not be object code, as GCC is merely a
driver program.  It could be assembler or even a directed acyclic graph
for human consumption.

> 3.  This is the rewrite of existing section 3.17.1, M680x0 Options:

        Thank you for your reading.  I have prepared a patch with the
textual corrections you have provided.

Simon

--- invoke.texi.orig    2003-05-04 14:54:30.000000000 -0400
+++ invoke.texi 2003-05-04 15:22:05.000000000 -0400
@@ -5428,7 +5428,7 @@
 
 @item -m68881
 @opindex m68881
-Generate output containing 68881 instructions for floating point.
+Generate output containing 68881 floating point instructions.
 This is the default for most 68020 systems unless @option{--nfp} was
 specified when the compiler was configured.
 
@@ -5443,8 +5443,8 @@
 configured for 68040-based systems.
 
 This option inhibits the use of 68881/68882 instructions that have to be
-emulated by software on the 68040.  Use this option if your 68040 does not
-have code to emulate those instructions.
+emulated by software on the 68040.  Use this option if your 68040 cannot
+emulate those instructions by itself.
 
 @item -m68060
 @opindex m68060
@@ -5453,7 +5453,7 @@
 
 This option inhibits the use of 68020 and 68881/68882 instructions that
 have to be emulated by software on the 68060.  Use this option if your 68060
-does not have code to emulate those instructions.
+cannot emulate those instructions by itself.
 
 @item -mcpu32
 @opindex mcpu32
@@ -5466,7 +5466,7 @@
 
 @item -m5200
 @opindex m5200
-Generate output for a 520X ``coldfire'' family cpu.  This is the default
+Generate output for a 520X ``coldfire''-family CPU.  This is the default
 when the compiler is configured for 520X-based systems.
 
 Use this option for microcontroller with a 5200 core, including
@@ -5489,21 +5489,23 @@
 
 @item -mfpa
 @opindex mfpa
-Generate output containing Sun FPA instructions for floating point.
+Generate output containing Sun FPA instructions for floating point
+processing.
 
 @item -msoft-float
 @opindex msoft-float
-Generate output containing library calls for floating point.
+Generate output containing library calls for floating point processing.
 @strong{Warning:} the requisite libraries are not available for all m68k
-targets.  Normally the facilities of the machine's usual C compiler are
-used, but this can't be done directly in cross-compilation.  You must
+targets.  Normally the facilities of the native C compiler are
+used, but this cannot be done directly in cross-compilation.  You must
 make your own arrangements to provide suitable library functions for
 cross-compilation.  The embedded targets @samp{m68k-*-aout} and
 @samp{m68k-*-coff} do provide software floating point support.
 
 @item -mshort
 @opindex mshort
-Consider type @code{int} to be 16 bits wide, like @code{short int}.
+Force variables of type @code{int} to be 16 bits in width, like
address@hidden int}.
 
 @item -mnobitfield
 @opindex mnobitfield
@@ -5520,22 +5522,21 @@
 @opindex mrtd
 Use a different function-calling convention, in which functions
 that take a fixed number of arguments return with the @code{rtd}
-instruction, which pops their arguments while returning.  This
-saves one instruction in the caller since there is no need to pop
-the arguments there.
+instruction. @code{rtd} pops the arguments from the stack
+while returning, saving one instruction cycle.
 
-This calling convention is incompatible with the one normally
+This convention is incompatible with the one normally
 used on Unix, so you cannot use it if you need to call libraries
 compiled with the Unix compiler.
 
-Also, you must provide function prototypes for all functions that
-take variable numbers of arguments (including @code{printf});
-otherwise incorrect code will be generated for calls to those
-functions.
+If you set this option, you must provide function prototypes for 
+all functions that take variable numbers of arguments (such as 
address@hidden); otherwise those functions will not be called
+correctly.
 
 In addition, seriously incorrect code will result if you call a
-function with too many arguments.  (Normally, extra arguments are
-harmlessly ignored.)
+function with too many arguments.  This is unlike the normal 
+convention, where extra arguments are harmlessly ignored.
 
 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
@@ -5550,8 +5551,8 @@
 Aligning variables on 32-bit boundaries produces code that runs somewhat
 faster on processors with 32-bit busses at the expense of more memory.
 
address@hidden:} if you use the @option{-malign-int} switch, GCC will
-align structures containing the above types  differently than
address@hidden:} the @option{-malign-int} switch will cause GCC to
+align structures containing these types in a manner that differs from
 most published application binary interface specifications for the m68k.
 
 @item -mpcrel
@@ -5566,8 +5567,10 @@
 @itemx -mstrict-align
 @opindex mno-strict-align
 @opindex mstrict-align
-Do not (do) assume that unaligned memory references will be handled by
-the system.
+Control whether GCC will use strict memory alignment.  
address@hidden assumes that unaligned memory references will be
+handled by the system.  @option{-mstrict-align} may be required if
+the system cannot handle arbitrary memory references.
 
 @end table