[patch] use @command in makefile.texi

Wed Apr 2 04:20:00 GMT 2003

On Tue, Apr 01, 2003 at 12:29:23PM +0200, Gerald Pfeifer wrote:
> I therefore believe that the change to @command{configure} is fine, while
> the occurrences of @code{make something} perhaps should be changed to
> @samp{make something}, and such a patch is pre-approved for mainline
> and the 3.3 branch.

If Joseph doesn't object, are similar changes to install.texi and
sourcebuild.texi also OK?

* doc/install.texi: Use @command and @samp for single- and
  multi-word commands respectively.
* doc/makefile.texi: Likewise.
* doc/sourcebuild.texi: Likewise.

Index: gcc/doc/install.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/install.texi,v
retrieving revision 1.177
diff -c -3 -p -r1.177 install.texi
*** gcc/doc/install.texi	25 Mar 2003 22:31:25 -0000	1.177
--- gcc/doc/install.texi	2 Apr 2003 04:16:58 -0000
*************** file system, the shell's built-in @comma
*** 281,287 ****
  temporary pathnames.  Using these can lead to various sorts of build
  problems.  To avoid this issue, set the @env{PWDCMD} environment
  variable to an automounter-aware @command{pwd} command, e.g.,
! @command{pawd} or @command{amq -w}, during the configuration and build
  phases.

  First, we @strong{highly} recommend that GCC be built into a
--- 281,287 ----
  temporary pathnames.  Using these can lead to various sorts of build
  problems.  To avoid this issue, set the @env{PWDCMD} environment
  variable to an automounter-aware @command{pwd} command, e.g.,
! @command{pawd} or @samp{amq -w}, during the configuration and build
  phases.

  First, we @strong{highly} recommend that GCC be built into a
*************** implies that the host defaults to @var{t
*** 346,352 ****
  @heading Options specification

  Use @var{options} to override several configure time options for
! GCC@.  A list of supported @var{options} follows; @command{configure
  --help} may list other options, but those not listed below may not
  work and should not normally be used.

--- 346,352 ----
  @heading Options specification

  Use @var{options} to override several configure time options for
! GCC@.  A list of supported @var{options} follows; @samp{configure
  --help} may list other options, but those not listed below may not
  work and should not normally be used.

*************** Other broken versions may recompile part
*** 976,982 ****
  installing the compiler.)

  Some commands executed when making the compiler may fail (return a
! nonzero status) and be ignored by @code{make}.  These failures, which
  are often due to files that were not found, are expected, and can safely
  be ignored.

--- 976,982 ----
  installing the compiler.)

  Some commands executed when making the compiler may fail (return a
! nonzero status) and be ignored by @command{make}.  These failures, which
  are often due to files that were not found, are expected, and can safely
  be ignored.

*************** target in an integral value on the host 
*** 1839,1845 ****
  cross-compilers on the Alpha for 32-bit machines has only been tested in
  a few cases and may not work properly.

! @code{make compare} may fail on old versions of DEC Unix unless you add
  @option{-save-temps} to @code{CFLAGS}.  On these systems, the name of the
  assembler input file is stored in the object file, and that makes
  comparison fail if it differs between the @code{stage1} and
--- 1839,1845 ----
  cross-compilers on the Alpha for 32-bit machines has only been tested in
  a few cases and may not work properly.

! @samp{make compare} may fail on old versions of DEC Unix unless you add
  @option{-save-temps} to @code{CFLAGS}.  On these systems, the name of the
  assembler input file is stored in the object file, and that makes
  comparison fail if it differs between the @code{stage1} and
*************** bootstrap.  Binaries are available from 
*** 2630,2636 ****
  @heading @anchor{m68k-crds-unos}m68k-crds-unos
  Use @samp{configure unos} for building on Unos.

! The Unos assembler is named @code{casm} instead of @code{as}.  For some
  strange reason linking @file{/bin/as} to @file{/bin/casm} changes the
  behavior, and does not work.  So, when installing GCC, you should
  install the following script as @file{as} in the subdirectory where
--- 2630,2636 ----
  @heading @anchor{m68k-crds-unos}m68k-crds-unos
  Use @samp{configure unos} for building on Unos.

! The Unos assembler is named @command{casm} instead of @command{as}.  For some
  strange reason linking @file{/bin/as} to @file{/bin/casm} changes the
  behavior, and does not work.  So, when installing GCC, you should
  install the following script as @file{as} in the subdirectory where
*************** kept up to date.  gdb does not understan
*** 2704,2712 ****
  you must use gas if you wish to use gdb.

  On HP-UX version 8.05, but not on 8.07 or more recent versions, the
! @code{fixproto} shell script triggers a bug in the system shell.  If you
  encounter this problem, upgrade your operating system or use BASH (the
! GNU shell) to run @code{fixproto}.  This bug will cause the fixproto
  program to report an error of the form:

  @example
--- 2704,2712 ----
  you must use gas if you wish to use gdb.

  On HP-UX version 8.05, but not on 8.07 or more recent versions, the
! @command{fixproto} shell script triggers a bug in the system shell.  If you
  encounter this problem, upgrade your operating system or use BASH (the
! GNU shell) to run @command{fixproto}.  This bug will cause the fixproto
  program to report an error of the form:

  @example
*************** subsystem must be installed from the IDO
*** 2776,2782 ****
  Graphics.  It is also available for download from
  @uref{http://www.sgi.com/developers/devtools/apis/ido.html,,http://www.sgi.com/developers/devtools/apis/ido.html}.

! @code{make compare} may fail on version 5 of IRIX unless you add
  @option{-save-temps} to @code{CFLAGS}.  On these systems, the name of the
  assembler input file is stored in the object file, and that makes
  comparison fail if it differs between the @code{stage1} and
--- 2776,2782 ----
  Graphics.  It is also available for download from
  @uref{http://www.sgi.com/developers/devtools/apis/ido.html,,http://www.sgi.com/developers/devtools/apis/ido.html}.

! @samp{make compare} may fail on version 5 of IRIX unless you add
  @option{-save-temps} to @code{CFLAGS}.  On these systems, the name of the
  assembler input file is stored in the object file, and that makes
  comparison fail if it differs between the @code{stage1} and
*************** On System V, if you get an error like th
*** 3251,3264 ****
  that too indicates a problem with disk space, ulimit, or @code{MAXUMEM}.

  On a System V release 4 system, make sure @file{/usr/bin} precedes
! @file{/usr/ucb} in @code{PATH}.  The @code{cc} command in
  @file{/usr/ucb} uses libraries which have bugs.

  @html
  <hr />
  @end html
  @heading @anchor{vax-dec-ultrix}vax-dec-ultrix
! Don't try compiling with VAX C (@code{vcc}).  It produces incorrect code
  in some cases (for example, when @code{alloca} is used).

  @html
--- 3251,3264 ----
  that too indicates a problem with disk space, ulimit, or @code{MAXUMEM}.

  On a System V release 4 system, make sure @file{/usr/bin} precedes
! @file{/usr/ucb} in @code{PATH}.  The @command{cc} command in
  @file{/usr/ucb} uses libraries which have bugs.

  @html
  <hr />
  @end html
  @heading @anchor{vax-dec-ultrix}vax-dec-ultrix
! Don't try compiling with VAX C (@command{vcc}).  It produces incorrect code
  in some cases (for example, when @code{alloca} is used).

  @html
Index: gcc/doc/makefile.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/makefile.texi,v
retrieving revision 1.3
diff -c -3 -p -r1.3 makefile.texi
*** gcc/doc/makefile.texi	4 Sep 2002 17:35:59 -0000	1.3
--- gcc/doc/makefile.texi	2 Apr 2003 04:16:58 -0000
*************** This is the default target.  Depending o
*** 13,30 ****
  configuration is, it coordinates all the things that need to be built.

  @item doc
! Produce info-formatted documentation.  Also, @code{make dvi} is
! available for DVI-formatted documentation, and @code{make
  generated-manpages} to generate man pages.

  @item mostlyclean
  Delete the files made while building the compiler.

  @item clean
! That, and all the other files built by @code{make all}.

  @item distclean
! That, and all the files created by @code{configure}.

  @item extraclean
  That, and any temporary or intermediate files, like emacs backup files.
--- 13,30 ----
  configuration is, it coordinates all the things that need to be built.

  @item doc
! Produce info-formatted documentation.  Also, @samp{make dvi} is
! available for DVI-formatted documentation, and @samp{make
  generated-manpages} to generate man pages.

  @item mostlyclean
  Delete the files made while building the compiler.

  @item clean
! That, and all the other files built by @samp{make all}.

  @item distclean
! That, and all the files created by @command{configure}.

  @item extraclean
  That, and any temporary or intermediate files, like emacs backup files.
*************** Deletes installed files.
*** 43,49 ****
  @item check
  Run the testsuite.  This creates a @file{testsuite} subdirectory that
  has various @file{.sum} and @file{.log} files containing the results of
! the testing.  You can run subsets with, for example, @code{make check-gcc}.
  You can specify specific tests by setting RUNTESTFLAGS to be the name
  of the @file{.exp} file, optionally followed by (for some tests) an equals
  and a file wildcard, like:
--- 43,49 ----
  @item check
  Run the testsuite.  This creates a @file{testsuite} subdirectory that
  has various @file{.sum} and @file{.log} files containing the results of
! the testing.  You can run subsets with, for example, @samp{make check-gcc}.
  You can specify specific tests by setting RUNTESTFLAGS to be the name
  of the @file{.exp} file, optionally followed by (for some tests) an equals
  and a file wildcard, like:
*************** installed, such as TCL or dejagnu.
*** 59,65 ****
  Builds gcc three times---once with the native compiler, once with the
  native-built compiler it just built, and once with the compiler it built
  the second time.  In theory, the last two should produce the same
! results, which @code{make compare} can check.  Each step of this process
  is called a ``stage'', and the results of each stage @var{N}
  (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.

--- 59,65 ----
  Builds gcc three times---once with the native compiler, once with the
  native-built compiler it just built, and once with the compiler it built
  the second time.  In theory, the last two should produce the same
! results, which @samp{make compare} can check.  Each step of this process
  is called a ``stage'', and the results of each stage @var{N}
  (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.

*************** special invocation, using this target me
*** 81,87 ****
  of which stage you're on or what invocation that stage needs.

  @item cleanstrap
! Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).

  @item stage@var{N} (@var{N} = 1@dots{}4)
  For each stage, moves the appropriate files to the @file{stage@var{N}}
--- 81,87 ----
  of which stage you're on or what invocation that stage needs.

  @item cleanstrap
! Removed everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).

  @item stage@var{N} (@var{N} = 1@dots{}4)
  For each stage, moves the appropriate files to the @file{stage@var{N}}
Index: gcc/doc/sourcebuild.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/sourcebuild.texi,v
retrieving revision 1.14
diff -c -3 -p -r1.14 sourcebuild.texi
*** gcc/doc/sourcebuild.texi	4 Mar 2003 21:48:52 -0000	1.14
--- gcc/doc/sourcebuild.texi	2 Apr 2003 04:17:03 -0000
*************** various languages, @file{@var{language}.
*** 155,161 ****
  contains @file{gcc.pot}, the template for these message catalogues,
  @file{exgettext}, a wrapper around @command{gettext} to extract the
  messages from the GCC sources and create @file{gcc.pot}, which is run
! by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from
  which messages should not be extracted.

  @item testsuite
--- 155,161 ----
  contains @file{gcc.pot}, the template for these message catalogues,
  @file{exgettext}, a wrapper around @command{gettext} to extract the
  messages from the GCC sources and create @file{gcc.pot}, which is run
! by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
  which messages should not be extracted.

  @item testsuite
*************** needs fixing, @file{syslimits.h} is the 
*** 278,284 ****

  The main GCC documentation is in the form of manuals in Texinfo
  format.  These are installed in Info format, and DVI versions may be
! generated by @command{make dvi}.  In addition, some man pages are
  generated from the Texinfo manuals, there are some other text files
  with miscellaneous documentation, and runtime libraries have their own
  documentation outside the @file{gcc} directory.  FIXME: document the
--- 278,284 ----

  The main GCC documentation is in the form of manuals in Texinfo
  format.  These are installed in Info format, and DVI versions may be
! generated by @samp{make dvi}.  In addition, some man pages are
  generated from the Texinfo manuals, there are some other text files
  with miscellaneous documentation, and runtime libraries have their own
  documentation outside the @file{gcc} directory.  FIXME: document the
*************** The GNU General Public License.
*** 312,320 ****
  A copy of @file{texinfo.tex} known to work with the GCC manuals.
  @end table

! DVI formatted manuals are generated by @command{make dvi}, which uses
  @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  Info
! manuals are generated by @command{make info} (which is run as part of
  a bootstrap); this generates the manuals in the source directory,
  using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
  and they are included in release distributions.
--- 312,320 ----
  A copy of @file{texinfo.tex} known to work with the GCC manuals.
  @end table

! DVI formatted manuals are generated by @samp{make dvi}, which uses
  @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  Info
! manuals are generated by @samp{make info} (which is run as part of
  a bootstrap); this generates the manuals in the source directory,
  using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
  and they are included in release distributions.
*************** not themselves the root files of manuals
*** 330,336 ****
  more than once in the source tree.)  The manual file
  @file{@var{name}.texi} should only include other files in its own
  directory or in @file{doc/include}.  HTML manuals will be generated by
! @command{makeinfo --html} and PostScript manuals by @command{texi2dvi}
  and @command{dvips}.  All Texinfo files that are parts of manuals must
  be checked into CVS, even if they are generated files, for the
  generation of online manuals to work.
--- 330,336 ----
  more than once in the source tree.)  The manual file
  @file{@var{name}.texi} should only include other files in its own
  directory or in @file{doc/include}.  HTML manuals will be generated by
! @samp{makeinfo --html} and PostScript manuals by @command{texi2dvi}
  and @command{dvips}.  All Texinfo files that are parts of manuals must
  be checked into CVS, even if they are generated files, for the
  generation of online manuals to work.
*************** Build an @command{etags} @file{TAGS} fil
*** 544,550 ****
  in the source tree.
  @item info
  Build info documentation for the front end, in the source directory.
! This target is only called by @command{make bootstrap} if a suitable
  version of @command{makeinfo} is available, so does not need to check
  for this, and should fail if an error occurs.
  @item dvi
--- 544,550 ----
  in the source tree.
  @item info
  Build info documentation for the front end, in the source directory.
! This target is only called by @samp{make bootstrap} if a suitable
  version of @command{makeinfo} is available, so does not need to check
  for this, and should fail if an error occurs.
  @item dvi

Matt
-- 
It's most certainly GNU/Linux, not Linux.  Read more at
http://www.gnu.org/gnu/why-gnu-linux.html.