[PATCH] Fix Texinfo usage in pexecute.txh

[PATCH] Fix Texinfo usage in pexecute.txh

[Eli Zaretskii]

I suggest the following patches to pexecute.txh:


2005-05-14  Eli Zaretskii  <eliz@gnu.org>

	* pexecute.txh: Enclose multi-word data types in @deftypefn in
	braces.  Minor wording fixes.  Use --- for em-dash.  Use
	@enumerate in enumerated lists.


Index: libiberty/pexecute.txh
===================================================================
RCS file: /cvs/src/src/libiberty/pexecute.txh,v
retrieving revision 1.2
diff -u -r1.2 pexecute.txh
--- libiberty/pexecute.txh	29 Mar 2005 02:15:22 -0000	1.2
+++ libiberty/pexecute.txh	14 May 2005 08:39:08 -0000
@@ -1,4 +1,4 @@
-@deftypefn Extension struct pex_obj *pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
+@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
 
 Prepare to execute one or more programs, with standard output of each
 program fed to standard input of the next.  This is a system
@@ -29,7 +29,7 @@
 
 @end deftypefn
 
-@deftypefn Extension const char *pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err})
+@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err})
 
 Execute one program in a pipeline.  On success this returns
 @code{NULL}.  On failure it returns an error message, a statically
@@ -46,8 +46,8 @@
 This must be set on the last program in the pipeline.  In particular,
 it should be set when executing a single program.  The standard output
 of the program will be sent to @var{outname}, or, if @var{outname} is
-@code{NULL}, to the standard output of the calling program.  This
-should not be set if you want to call @code{pex_read_output}
+@code{NULL}, to the standard output of the calling program.  Do @emph{not}
+set this bit if you want to call @code{pex_read_output}
 (described below).  After a call to @code{pex_run} with this bit set,
 @var{pex_run} may no longer be called with the same @var{obj}.
 
@@ -71,7 +71,7 @@
 The standard input (output) of the program should be read (written) in
 binary mode rather than text mode.  These flags are ignored on systems
 which do not distinguish binary mode and text mode, such as Unix.  For
-proper behavior these flags should match appropriately--a call to
+proper behavior these flags should match appropriately---a call to
 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
 call using @code{PEX_BINARY_INPUT}.
 @end table
@@ -81,11 +81,20 @@
 be a copy of @var{executable}.
 
 @var{outname} is used to set the name of the file to use for standard
-output.  There are two cases in which no output file will be used: 1)
+output.  There are two cases in which no output file will be used:
+
+@enumerate
+@item
 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
-was set in the call to @code{pex_init}, and the system supports pipes;
-2) if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
-@code{NULL}.  Otherwise the code will use a file to hold standard
+was set in the call to @code{pex_init}, and the system supports pipes
+
+@item
+if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
+@code{NULL}
+@end enumerate
+
+@noindent
+Otherwise the code will use a file to hold standard
 output.  If @code{PEX_LAST} is not set, this file is considered to be
 a temporary file, and it will be removed when no longer needed, unless
 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
@@ -93,22 +102,26 @@
 There are two cases to consider when setting the name of the file to
 hold standard output.
 
-First case: @code{PEX_SUFFIX} is set in @var{flags}.  In this case
+@enumerate
+@item
+@code{PEX_SUFFIX} is set in @var{flags}.  In this case
 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
 to @code{pex_init} was not @code{NULL}, then the output file name is
 the concatenation of @var{tempbase} and @var{outname}.  If
 @var{tempbase} was @code{NULL}, then the output file name is a random
 file name ending in @var{outname}.
 
-Second case: @code{PEX_SUFFIX} was not set in @var{flags}.  In this
+@item
+@code{PEX_SUFFIX} was not set in @var{flags}.  In this
 case, if @var{outname} is not @code{NULL}, it is used as the output
 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
 not NULL, the output file name is randomly chosen using
 @var{tempbase}.  Otherwise the output file name is chosen completely
 at random.
+@end enumerate
 
 @var{errname} is the file name to use for standard error output.  If
-it is @code{NULL}, standard error is the same as the caller.
+it is @code{NULL}, standard error is the same as the caller's.
 Otherwise, standard error is written to the named file.
 
 On an error return, the code sets @code{*@var{err}} to an @code{errno}
@@ -116,7 +129,7 @@
 
 @end deftypefn
 
-@deftypefn Extension FILE * pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
+@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
 
 Returns a @code{FILE} pointer which may be used to read the standard
 output of the last program in the pipeline.  When this is used,
@@ -145,7 +158,8 @@
 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
 success.
 
-@code{struct pex_time} has the following fields: @code{user_seconds},
+@code{struct pex_time} has the following fields of the type
+@code{unsigned long}: @code{user_seconds},
 @code{user_microseconds}, @code{system_seconds},
 @code{system_microseconds}.  On systems which do not support reporting
 process times, all the fields will be set to @code{0}.
@@ -158,14 +172,14 @@
 
 @end deftypefn
 
-@deftypefn Extension const char *pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err})
+@deftypefn Extension {const char *} pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err})
 
-An interface to @code{pex_init} to permit the easy execution of a
+An interface to permit the easy execution of a
 single program.  The return value and most of the parameters are as
 for a call to @code{pex_run}.  @var{flags} is restricted to a
 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
-@code{PEX_LAST} were set.  On a successful return, *@var{status} will
+@code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
 be set to the exit status of the program.
 
 @end deftypefn

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Andreas Jaeger]

[-- Attachment #1: Type: text/plain, Size: 668 bytes --]

"Eli Zaretskii" <eliz@gnu.org> writes:

> I suggest the following patches to pexecute.txh:
>
>
> 2005-05-14  Eli Zaretskii  <eliz@gnu.org>
>
> 	* pexecute.txh: Enclose multi-word data types in @deftypefn in
> 	braces.  Minor wording fixes.  Use --- for em-dash.  Use

em-dash?  I don't see any changes like this in your patch, seems that
the ChangeLog entry is not correct - or your patch misses a few bits.

> 	@enumerate in enumerated lists.

Andreas
-- 
 Andreas Jaeger, aj@suse.de, http://www.suse.de/~aj
  SUSE Linux Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

[-- Attachment #2: Type: application/pgp-signature, Size: 188 bytes --]

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Eli Zaretskii]

> From: Andreas Jaeger <aj@suse.de>
> Cc: gcc-patches@gcc.gnu.org, gdb-patches@sourceware.org
> Date: Sat, 14 May 2005 11:23:13 +0200
> 
> > 	* pexecute.txh: Enclose multi-word data types in @deftypefn in
> > 	braces.  Minor wording fixes.  Use --- for em-dash.  Use
> 
> em-dash?  I don't see any changes like this in your patch

It's in this hunk:

    @@ -71,7 +71,7 @@
     The standard input (output) of the program should be read (written) in
     binary mode rather than text mode.  These flags are ignored on systems
     which do not distinguish binary mode and text mode, such as Unix.  For
    -proper behavior these flags should match appropriately--a call to
    +proper behavior these flags should match appropriately---a call to
     @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
     call using @code{PEX_BINARY_INPUT}.
     @end table

See that "---"?  That's what produces em-dash in print.  The original
was using "--", which produces a single hyphen in print; that is not
what we want here.

Thanks for reviewing the patch.

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Andreas Jaeger]

[-- Attachment #1: Type: text/plain, Size: 1472 bytes --]

"Eli Zaretskii" <eliz@gnu.org> writes:

>> From: Andreas Jaeger <aj@suse.de>
>> Cc: gcc-patches@gcc.gnu.org, gdb-patches@sourceware.org
>> Date: Sat, 14 May 2005 11:23:13 +0200
>> 
>> > 	* pexecute.txh: Enclose multi-word data types in @deftypefn in
>> > 	braces.  Minor wording fixes.  Use --- for em-dash.  Use
>> 
>> em-dash?  I don't see any changes like this in your patch
>
> It's in this hunk:
>
>     @@ -71,7 +71,7 @@
>      The standard input (output) of the program should be read (written) in
>      binary mode rather than text mode.  These flags are ignored on systems
>      which do not distinguish binary mode and text mode, such as Unix.  For
>     -proper behavior these flags should match appropriately--a call to
>     +proper behavior these flags should match appropriately---a call to
>      @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
>      call using @code{PEX_BINARY_INPUT}.
>      @end table
>
> See that "---"?  That's what produces em-dash in print.  The original
> was using "--", which produces a single hyphen in print; that is not
> what we want here.

Argh, I looked for " --- " instead of "---".  This looks fine indeed.

Btw. shouldn't there be spaces around this one?

Andreas
-- 
 Andreas Jaeger, aj@suse.de, http://www.suse.de/~aj
  SUSE Linux Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

[-- Attachment #2: Type: application/pgp-signature, Size: 188 bytes --]

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Eli Zaretskii]

> From: Andreas Jaeger <aj@suse.de>
> Cc: gcc-patches@gcc.gnu.org, gdb-patches@sourceware.org
> Date: Sat, 14 May 2005 12:23:38 +0200
> 
> Argh, I looked for " --- " instead of "---".  This looks fine indeed.

Thanks.  I don't have write access to the repository, so someone else
will have to commit this.

> Btw. shouldn't there be spaces around this one?

I don't think so.  The Texinfo manual shows its usage without spaces.

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Andreas Jaeger]

[-- Attachment #1: Type: text/plain, Size: 932 bytes --]

"Eli Zaretskii" <eliz@gnu.org> writes:

>> From: Andreas Jaeger <aj@suse.de>
>> Cc: gcc-patches@gcc.gnu.org, gdb-patches@sourceware.org
>> Date: Sat, 14 May 2005 12:23:38 +0200
>> 
>> Argh, I looked for " --- " instead of "---".  This looks fine indeed.
>
> Thanks.  I don't have write access to the repository, so someone else
> will have to commit this.

Sorry, I don't have approval rights, I just commented on it.

Bug if somebody approves it, I can commit it to gcc - and then it will
find it's way automatically to gdb AFAIK.

>> Btw. shouldn't there be spaces around this one?
>
> I don't think so.  The Texinfo manual shows its usage without spaces.

I see - habit from my LaTeX experience...

Andreas
-- 
 Andreas Jaeger, aj@suse.de, http://www.suse.de/~aj
  SUSE Linux Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

[-- Attachment #2: Type: application/pgp-signature, Size: 188 bytes --]

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Ian Lance Taylor]

"Eli Zaretskii" <eliz@gnu.org> writes:

> I suggest the following patches to pexecute.txh:
> 
> 
> 2005-05-14  Eli Zaretskii  <eliz@gnu.org>
> 
> 	* pexecute.txh: Enclose multi-word data types in @deftypefn in
> 	braces.  Minor wording fixes.  Use --- for em-dash.  Use
> 	@enumerate in enumerated lists.

This is OK.  Thanks.

Ian

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Andreas Jaeger]

[-- Attachment #1: Type: text/plain, Size: 639 bytes --]

Ian Lance Taylor <ian@airs.com> writes:

> "Eli Zaretskii" <eliz@gnu.org> writes:
>
>> I suggest the following patches to pexecute.txh:
>> 
>> 
>> 2005-05-14  Eli Zaretskii  <eliz@gnu.org>
>> 
>> 	* pexecute.txh: Enclose multi-word data types in @deftypefn in
>> 	braces.  Minor wording fixes.  Use --- for em-dash.  Use
>> 	@enumerate in enumerated lists.
>
> This is OK.  Thanks.

I'll commit this for Eli now,

Andreas
-- 
 Andreas Jaeger, aj@suse.de, http://www.suse.de/~aj
  SUSE Linux Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

[-- Attachment #2: Type: application/pgp-signature, Size: 188 bytes --]

Re: [PATCH] Fix Texinfo usage in pexecute.txh

[Eli Zaretskii]

> From: Andreas Jaeger <aj@suse.de>
> Cc: Eli Zaretskii <eliz@gnu.org>, gcc-patches@gcc.gnu.org,
> 	gdb-patches@sourceware.org
> Date: Sun, 15 May 2005 18:34:29 +0200
> 
> >> 	* pexecute.txh: Enclose multi-word data types in @deftypefn in
> >> 	braces.  Minor wording fixes.  Use --- for em-dash.  Use
> >> 	@enumerate in enumerated lists.
> >
> > This is OK.  Thanks.
> 
> I'll commit this for Eli now,

Thanks.