This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[PATCH] Texinfo documentation improvements


This is a mostly obvious patch to improvement Texinfo documentation.
I separated it out from my other patch because these changes content.

* In contrib.texi, I removed the outer quotes on
	Richard Kenner's "``toy'' language".
Correct American English would be {``}{`}toy' language.''
Which, according to Knuth's TeXbook, should be typeset in TeX as
	``\thinspace`toy' language.''
but Texinfo don't have thin spaces.  In any case, the outer quotes
are unnecessary: I did some web searching, and "toy language"
does not appear to be the title of a book or paper.

* I marked the backends (cc1, etc.) with @file in invoke.texi.
The rest of the file uses @file, though some could be @command.

* In invoke.texi, the two "cpp" in the phrase
	use the integrated cpp (internal cpp)
seems weird to me.  Also, they're abbreviations.  I changed the first
to what it stands for, and the second to refer to the command.

* In invoke.texi, I commented out
	The semantics of this option will change if "cc1", "cc1plus", and
	"cc1obj" are merged.
Even if the recent thread on merging the frontends reaches a conclusion,
the comment seems inappropriate in the documentation now.

* For the pass manager, the file "passes.h" is does not exist and
is not mentioned in the change logs.  I think the sources should be
tree-optimize.c and tree-pass.h.

* The file configure.frag was removed according to the change log,
so I removed a reference from sourcebuild.texi.

* In tm.texi, "GCC -v" should be the command "gcc -v".

* tm.texi says "-m" is appended to options.  Should be prepend,
but that's not a word in my dictionary or aspell, so I used "add".

* In gcj.texi, I marked the current directory dot with @file
rather than @code.

* In treelang.texi, I marked up references to the gcc and gccint manuals
with @cite.  We should use @ref, but the Texinfo manual says that @ref's
must be followed by a comma or period, which would require rewriting that
whole paragraph.

* In treelang.texi, I changed the list of keywords/
into a table.

Tested along with my previous doc patch with 'make info' and 'make dvi'.

Please apply if approved. I do not have CVS write access.

Di-an Jan


[gcc/ChangeLog]


2004-11-01 Di-an Jan <dianj@freeshell.org>

	* doc/contrib.texi (Tim Josling): Remove nesting quotation marks.
	* doc/invoke.texi (-no-integrated-cpp, spec): Use @file for cc1, etc.
	(-no-integrated-cpp): Spell out cpp.  Comment out note predicated on
	merging cc1, cc1plus, and cc1obj.
	* doc/passes.texi (Pass Manager): Correct list of source files.
	* doc/sourcebuild.texi (configure.frag): Remove.
	* doc/tm.texi (THREAD_MODEL_SPEC): Mark up command.
	(TARGET_SWITCHES, TARGET_OPTIONS): Correctly describe adding -m.

[gcc/java/ChangeLog]

2004-11-01 Di-an Jan <dianj@freeshell.org>

* gcj.texi (CLASSPATH): Use @file for current directory.

[gcc/treelang/ChangeLog]

2004-11-01 Di-an Jan <dianj@freeshell.org>

	* treelang.texi: (Getting Started): Markup references with @cite.
	(Lexical Syntax): Make list into a table.  Use Texinfo markups.



Index: gcc/doc/contrib.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/doc/contrib.texi,v
retrieving revision 1.1.1.1
diff -c -3 -F@node -r1.1.1.1 contrib.texi
*** gcc/doc/contrib.texi	30 Oct 2004 16:45:38 -0000	1.1.1.1
--- gcc/doc/contrib.texi	30 Oct 2004 21:58:56 -0000
*************** @node Contributors
*** 400,406 ****

  @item
  Tim Josling for the sample language treelang based originally on Richard
! Kenner's "``toy'' language".

  @item
  Nicolai Josuttis for additional libstdc++ documentation.
--- 400,406 ----

  @item
  Tim Josling for the sample language treelang based originally on Richard
! Kenner's ``toy'' language.

  @item
  Nicolai Josuttis for additional libstdc++ documentation.
Index: gcc/doc/invoke.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.2
diff -c -3 -F@node -r1.2 invoke.texi
*** gcc/doc/invoke.texi	30 Oct 2004 20:58:23 -0000	1.2
--- gcc/doc/invoke.texi	31 Oct 2004 15:05:44 -0000
*************** @node C Dialect Options
*** 1238,1250 ****
  @item -no-integrated-cpp
  @opindex no-integrated-cpp
  Performs a compilation in two passes: preprocessing and compiling.  This
! option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
! @option{-B} option. The user supplied compilation step can then add in
  an additional preprocessing step after normal preprocessing but before
! compiling. The default is to use the integrated cpp (internal cpp)

! The semantics of this option will change if "cc1", "cc1plus", and
! "cc1obj" are merged.

  @cindex traditional C language
  @cindex C language, traditional
--- 1238,1251 ----
  @item -no-integrated-cpp
  @opindex no-integrated-cpp
  Performs a compilation in two passes: preprocessing and compiling.  This
! option allows a user supplied @file{cc1}, @file{cc1plus}, or @file{cc1obj} via the
! @option{-B} option.  The user supplied compilation step can then add in
  an additional preprocessing step after normal preprocessing but before
! compiling.  The default is to use the integrated C preprocessor
! (internal @command{cpp}).

! @c The semantics of this option will change if @file{cc1}, @file{cc1plus},
! @c and @file{cc1obj} are merged.

  @cindex traditional C language
  @cindex C language, traditional
*************** @node Spec Files
*** 6341,6351 ****

  @item %1
  Process the @code{cc1} spec.  This is used to construct the options to be
! passed to the actual C compiler (@samp{cc1}).

  @item %2
  Process the @code{cc1plus} spec.  This is used to construct the options to be
! passed to the actual C++ compiler (@samp{cc1plus}).

  @item %*
  Substitute the variable part of a matched option.  See below.
--- 6342,6352 ----

  @item %1
  Process the @code{cc1} spec.  This is used to construct the options to be
! passed to the actual C compiler (@file{cc1}).

  @item %2
  Process the @code{cc1plus} spec.  This is used to construct the options to be
! passed to the actual C++ compiler (@file{cc1plus}).

  @item %*
  Substitute the variable part of a matched option.  See below.
Index: gcc/doc/passes.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/doc/passes.texi,v
retrieving revision 1.2
diff -c -3 -F@node -r1.2 passes.texi
*** gcc/doc/passes.texi	30 Oct 2004 20:58:24 -0000	1.2
--- gcc/doc/passes.texi	30 Oct 2004 21:58:56 -0000
*************** @node Gimplification pass
*** 146,152 ****
  @node Pass manager
  @section Pass manager

! The pass manager is located in @file{passes.c} and @file{passes.h}.
  Its job is to run all of the individual passes in the correct order,
  and take care of standard bookkeeping that applies to every pass.

--- 146,153 ----
  @node Pass manager
  @section Pass manager

! The pass manager is located in @file{passes.c}, @file{tree-optimize.c}
! and @file{tree-pass.h}.
  Its job is to run all of the individual passes in the correct order,
  and take care of standard bookkeeping that applies to every pass.

Index: gcc/doc/sourcebuild.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/doc/sourcebuild.texi,v
retrieving revision 1.1.1.1
diff -c -3 -F@node -r1.1.1.1 sourcebuild.texi
*** gcc/doc/sourcebuild.texi 30 Oct 2004 16:45:38 -0000 1.1.1.1
--- gcc/doc/sourcebuild.texi 30 Oct 2004 23:01:32 -0000
*************** @node Config Fragments
*** 215,223 ****
@file{@var{language}/config-lang.in} that is used for
front-end-specific configuration. @xref{Front End Config, , The Front
End @file{config-lang.in} File}, for details of this file.
- - @item A helper script @file{configure.frag} is used as part of
- creating the output of @file{configure}.
@end itemize


  @node System Config
--- 215,220 ----
Index: gcc/doc/tm.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/doc/tm.texi,v
retrieving revision 1.2
diff -c -3 -F@node -r1.2 tm.texi
*** gcc/doc/tm.texi	30 Oct 2004 20:58:24 -0000	1.2
--- gcc/doc/tm.texi	31 Oct 2004 03:15:20 -0000
*************** @node Driver
*** 339,345 ****
  @end defmac

  @defmac THREAD_MODEL_SPEC
! GCC @code{-v} will print the thread model GCC was configured to use.
  However, this doesn't work on platforms that are multilibbed on thread
  models, such as AIX 4.3.  On such platforms, define
  @code{THREAD_MODEL_SPEC} such that it evaluates to a string without
--- 339,345 ----
  @end defmac

  @defmac THREAD_MODEL_SPEC
! @code{gcc -v} will print the thread model GCC was configured to use.
  However, this doesn't work on platforms that are multilibbed on thread
  models, such as AIX 4.3.  On such platforms, define
  @code{THREAD_MODEL_SPEC} such that it evaluates to a string without
*************** @node Run-time Target
*** 778,784 ****
  by the number are cleared instead of being set.  If the description
  string is present but empty, then no help information will be displayed
  for that option, but it will not count as an undocumented option.  The
! actual option name is made by appending @samp{-m} to the specified name.
  Non-empty description strings should be marked with @code{N_(@dots{})} for
  @command{xgettext}.  Please do not mark empty strings because the empty
  string is reserved by GNU gettext. @code{gettext("")} returns the header entry
--- 778,784 ----
  by the number are cleared instead of being set.  If the description
  string is present but empty, then no help information will be displayed
  for that option, but it will not count as an undocumented option.  The
! actual option name is made by adding @samp{-m} to the specified name.
  Non-empty description strings should be marked with @code{N_(@dots{})} for
  @command{xgettext}.  Please do not mark empty strings because the empty
  string is reserved by GNU gettext. @code{gettext("")} returns the header entry
*************** @node Run-time Target
*** 823,829 ****
  fixed part matches.  In other words, if the first part of the option
  matches what's in the table, the variable will be set to point to the
  rest of the option.  This allows the user to specify a value for that
! option.  The actual option name is made by appending @samp{-m} to the
  specified name.  Again, each option should also be documented in
  @file{invoke.texi}.

--- 823,829 ----
  fixed part matches.  In other words, if the first part of the option
  matches what's in the table, the variable will be set to point to the
  rest of the option.  This allows the user to specify a value for that
! option.  The actual option name is made by adding @samp{-m} to the
  specified name.  Again, each option should also be documented in
  @file{invoke.texi}.

Index: gcc/java/gcj.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/java/gcj.texi,v
retrieving revision 1.2
diff -c -3 -F@node -r1.2 gcj.texi
*** gcc/java/gcj.texi	30 Oct 2004 20:58:31 -0000	1.2
--- gcc/java/gcj.texi	30 Oct 2004 21:58:56 -0000
*************** @node Input Options
*** 266,272 ****
  If @option{--classpath} is specified, its value is appended.
  Otherwise, if the @code{CLASSPATH} environment variable is specified,
  then its value is appended.
! Otherwise, the current directory (@code{"."}) is appended.

  @item
  If @code{--bootclasspath} was specified, append its value.
--- 266,272 ----
  If @option{--classpath} is specified, its value is appended.
  Otherwise, if the @code{CLASSPATH} environment variable is specified,
  then its value is appended.
! Otherwise, the current directory (@file{.}) is appended.

  @item
  If @code{--bootclasspath} was specified, append its value.
Index: gcc/treelang/treelang.texi
===================================================================
RCS file: /e/cvs/gcc/gcc/treelang/treelang.texi,v
retrieving revision 1.2
diff -c -3 -F@node -r1.2 treelang.texi
*** gcc/treelang/treelang.texi	30 Oct 2004 20:58:35 -0000	1.2
--- gcc/treelang/treelang.texi	31 Oct 2004 17:07:04 -0000
*************** @node Getting Started
*** 304,311 ****
  interest in it.

  This manual assumes familiarity with GCC, which you can obtain by using
! it and by reading the manuals @samp{Using the GNU Compiler Collection (GCC)}
! and @samp{GNU Compiler Collection (GCC) Internals}.

  To install treelang, follow the GCC installation instructions,
  taking care to ensure you specify treelang in the configure step by adding
--- 304,311 ----
  interest in it.

  This manual assumes familiarity with GCC, which you can obtain by using
! it and by reading the manuals @cite{Using the GNU Compiler Collection (GCC)}
! and @cite{GNU Compiler Collection (GCC) Internals}.

  To install treelang, follow the GCC installation instructions,
  taking care to ensure you specify treelang in the configure step by adding
*************** @node Lexical Syntax, Parsing Syntax, Wh
*** 421,427 ****
  @item
  Keywords consist of any of the following reserved words or symbols:

! @itemize @bullet
  @item @{
  used to start the statements in a function
  @item @}
--- 421,427 ----
  @item
  Keywords consist of any of the following reserved words or symbols:

! @table @samp
  @item @{
  used to start the statements in a function
  @item @}
*************** @node Lexical Syntax, Parsing Syntax, Wh
*** 465,477 ****
  start function return statement
  @item void
  used as function type to indicate function returns nothing
! @end itemize


@item ! Names consist of any letter or "_" followed by any number of letters, ! numbers, or "_". "$" is not allowed in a name. All names must be globally ! unique, i.e. may not be used twice in any context, and must not be a keyword. Names and keywords are case sensitive. For example:

  @smallexample
--- 465,477 ----
  start function return statement
  @item void
  used as function type to indicate function returns nothing
! @end table


@item ! Names consist of any letter or @samp{_} followed by any number of letters, ! numbers, or @samp{_}. @samp{$} is not allowed in a name. All names must be ! globally unique, i.e. may not be used twice in any context, and must not be a keyword. Names and keywords are case sensitive. For example:

@smallexample


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]