diff mbox

[v3,BZ,#17787] Fix exponents in manual.

Message ID 20150618142917.GA16523@domone
State New
Headers show

Commit Message

Ondřej Bílka June 18, 2015, 2:29 p.m. UTC 
On Tue, Jun 16, 2015 at 04:24:52PM -0400, Carlos O'Donell wrote:
> On 06/16/2015 04:07 PM, Joseph Myers wrote:
> > On Tue, 16 Jun 2015, Ondřej Bílka wrote:
> > 
> >> Ping, if you have better idea I would like it.
> > 
> > I've looked back at the previous discussion.  It seems clear enough that:
> > 
> > * It's a bad idea to duplicate parts of sentences that don't need 
> > duplicating.  Conditionals in the main manual should be around lines with 
> > nothing more than the single word using @math.
> 
> It's bad, but it's not terrible. I would rather see the manual get updated
> than nit pick over the exact ways that this can get fixed.
> 
> > * It should be possible to use a Texinfo macro for this and so avoid any 
> > conditionals at all in the main manual.  Something like (untested)
> > 
> > @iftex
> > @macro twoexp{exp}
> > 2^{\exp\}
> > @end macro
> > @end iftex
> > @ifnottex
> > @macro twoexp{exp}
> > 2^{exp}
> > @end macro
> > @end itnottex
> > 
> > (and then use @twoexp{63} etc.).
> 
> That's a good suggestion.
> 
> Cheers,
> Carlos.

Thanks that works after fixing two typos. Here I use twoexp.

        * manual/filesys.texi: Fix exponents.
        * manual/llio.texi: Likewise.
        * manual/stdio.texi: Likewise.

Comments

Joseph Myers June 18, 2015, 2:34 p.m. UTC | #1 
On Thu, 18 Jun 2015, Ondřej Bílka wrote:

> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index 0f2e3dc..181de76 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -2,6 +2,18 @@
>  @c %MENU% Functions for manipulating files
>  @chapter File System Interface
>  
> +@iftex
> +@macro twoexp{exp}
> +@math{2^{{\exp\}}}
> +@end macro
> +@end iftex
> +@ifnottex
> +@macro twoexp{exp}
> +2^\exp\
> +@end macro
> +@end ifnottex

The macro definitions should go in macros.texi, rather than being 
duplicated in each file using it.
Carlos O'Donell June 18, 2015, 3:26 p.m. UTC | #2 
On 06/18/2015 10:29 AM, Ondřej Bílka wrote:
> On Tue, Jun 16, 2015 at 04:24:52PM -0400, Carlos O'Donell wrote:
>> On 06/16/2015 04:07 PM, Joseph Myers wrote:
>>> On Tue, 16 Jun 2015, Ondřej Bílka wrote:
>>>
>>>> Ping, if you have better idea I would like it.
>>>
>>> I've looked back at the previous discussion.  It seems clear enough that:
>>>
>>> * It's a bad idea to duplicate parts of sentences that don't need 
>>> duplicating.  Conditionals in the main manual should be around lines with 
>>> nothing more than the single word using @math.
>>
>> It's bad, but it's not terrible. I would rather see the manual get updated
>> than nit pick over the exact ways that this can get fixed.
>>
>>> * It should be possible to use a Texinfo macro for this and so avoid any 
>>> conditionals at all in the main manual.  Something like (untested)
>>>
>>> @iftex
>>> @macro twoexp{exp}
>>> 2^{\exp\}
>>> @end macro
>>> @end iftex
>>> @ifnottex
>>> @macro twoexp{exp}
>>> 2^{exp}
>>> @end macro
>>> @end itnottex
>>>
>>> (and then use @twoexp{63} etc.).
>>
>> That's a good suggestion.
>>
>> Cheers,
>> Carlos.
> 
> Thanks that works after fixing two typos. Here I use twoexp.
> 
>         * manual/filesys.texi: Fix exponents.
>         * manual/llio.texi: Likewise.
>         * manual/stdio.texi: Likewise.

Looks good to me.

Cheers,
Carlos.
Carlos O'Donell June 18, 2015, 3:54 p.m. UTC | #3 
On 06/18/2015 10:34 AM, Joseph Myers wrote:
> On Thu, 18 Jun 2015, Ondřej Bílka wrote:
> 
>> diff --git a/manual/filesys.texi b/manual/filesys.texi
>> index 0f2e3dc..181de76 100644
>> --- a/manual/filesys.texi
>> +++ b/manual/filesys.texi
>> @@ -2,6 +2,18 @@
>>  @c %MENU% Functions for manipulating files
>>  @chapter File System Interface
>>  
>> +@iftex
>> +@macro twoexp{exp}
>> +@math{2^{{\exp\}}}
>> +@end macro
>> +@end iftex
>> +@ifnottex
>> +@macro twoexp{exp}
>> +2^\exp\
>> +@end macro
>> +@end ifnottex
> 
> The macro definitions should go in macros.texi, rather than being 
> duplicated in each file using it.

It would also seem sensible to keep such macros near their uses,
and move them to macros.texi only if globally useful or repeated
more than some nominal number of times.

What if the macro was only used in one place? Would we still put
it into macros.texi?

Cheers,
Carlos.
Joseph Myers June 18, 2015, 4:01 p.m. UTC | #4 
On Thu, 18 Jun 2015, Carlos O'Donell wrote:

> > The macro definitions should go in macros.texi, rather than being 
> > duplicated in each file using it.
> 
> It would also seem sensible to keep such macros near their uses,
> and move them to macros.texi only if globally useful or repeated
> more than some nominal number of times.
> 
> What if the macro was only used in one place? Would we still put
> it into macros.texi?

If it were only used in one source file, it might be reasonable to define 
it there, but this macro is used in three source files.

Another issue with this patch: where it has "-@twoexp{63}" replacing 
"@math{-2^63}", the minus sign being outside @math will make it a hyphen 
rather than a minus sign (use @minus{} instead).  And one typo, 
"-2@twoexp{63}" has a stray "2" in there (should be 
"@minus{}@twoexp{63}").
diff mbox

Patch

diff --git a/manual/filesys.texi b/manual/filesys.texi
index 0f2e3dc..181de76 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -2,6 +2,18 @@ 
 @c %MENU% Functions for manipulating files
 @chapter File System Interface
 
+@iftex
+@macro twoexp{exp}
+@math{2^{{\exp\}}}
+@end macro
+@end iftex
+@ifnottex
+@macro twoexp{exp}
+2^\exp\
+@end macro
+@end ifnottex
+
+
 This chapter describes @theglibc{}'s functions for manipulating
 files.  Unlike the input and output functions (@pxref{I/O on Streams};
 @pxref{Low-Level I/O}), these functions are concerned with operating
@@ -1834,7 +1846,7 @@  writing the file.  (This is unrelated to @code{st_blocks}.)
 @end deftp
 
 The extensions for the Large File Support (LFS) require, even on 32-bit
-machines, types which can handle file sizes up to @math{2^63}.
+machines, types which can handle file sizes up to @twoexp{63}.
 Therefore a new definition of @code{struct stat} is necessary.
 
 @comment sys/stat.h
@@ -2024,7 +2036,7 @@  replaces the normal implementation.
 @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 This function is similar to @code{stat} but it is also able to work on
-files larger than @math{2^31} bytes on 32-bit systems.  To be able to do
+files larger than @twoexp{31} bytes on 32-bit systems.  To be able to do
 this the result is stored in a variable of type @code{struct stat64} to
 which @var{buf} must point.
 
@@ -2097,7 +2109,7 @@  replaces the normal implementation.
 @c Direct system call through lxstat64, sometimes with an xstat conv
 @c call afterwards.
 This function is similar to @code{lstat} but it is also able to work on
-files larger than @math{2^31} bytes on 32-bit systems.  To be able to do
+files larger than @twoexp{31} bytes on 32-bit systems.  To be able to do
 this the result is stored in a variable of type @code{struct stat64} to
 which @var{buf} must point.
 
@@ -3073,7 +3085,7 @@  systems do not support this feature and will leave the file unchanged.
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
 @code{truncate} function is in fact @code{truncate64} and the type
 @code{off_t} has 64 bits which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
 
 The return value is @math{0} for success, or @math{-1} for an error.  In
 addition to the usual file name errors, the following errors may occur:
@@ -3110,7 +3122,7 @@  The operation was interrupted by a signal.
 This function is similar to the @code{truncate} function.  The
 difference is that the @var{length} argument is 64 bits wide even on 32
 bits machines, which allows the handling of files with sizes up to
-@math{2^63} bytes.
+@twoexp{63} bytes.
 
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
 32 bits machine this function is actually available under the name
@@ -3144,7 +3156,7 @@  The example below shows how this works.
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
 @code{ftruncate} function is in fact @code{ftruncate64} and the type
 @code{off_t} has 64 bits which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
 
 The return value is @math{0} for success, or @math{-1} for an error.  The
 following errors may occur:
@@ -3190,7 +3202,7 @@  The operation was interrupted by a signal.
 This function is similar to the @code{ftruncate} function.  The
 difference is that the @var{length} argument is 64 bits wide even on 32
 bits machines which allows the handling of files with sizes up to
-@math{2^63} bytes.
+@twoexp{63} bytes.
 
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
 32 bits machine this function is actually available under the name
@@ -3430,7 +3442,7 @@  interface transparently replaces the old interface.
 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
 This function is similar to @code{tmpfile}, but the stream it returns a
 pointer to was opened using @code{tmpfile64}.  Therefore this stream can
-be used for files larger than @math{2^31} bytes on 32-bit machines.
+be used for files larger than @twoexp{31} bytes on 32-bit machines.
 
 Please note that the return type is still @code{FILE *}.  There is no
 special @code{FILE} type for the LFS interface.
diff --git a/manual/llio.texi b/manual/llio.texi
index 4f3fada..6e36f97 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -2,6 +2,18 @@ 
 @c %MENU% Low-level, less portable I/O
 @chapter Low-Level Input/Output
 
+@iftex
+@macro twoexp{exp}
+@math{2^{{\exp\}}}
+@end macro
+@end iftex
+@ifnottex
+@macro twoexp{exp}
+2^\exp\
+@end macro
+@end ifnottex
+
+
 This chapter describes functions for performing low-level input/output
 operations on file descriptors.  These functions include the primitives
 for the higher-level I/O functions described in @ref{I/O on Streams}, as
@@ -150,8 +162,8 @@  or @code{O_CREAT} is set and the file does not already exist.
 If on a 32 bit machine the sources are translated with
 @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
 descriptor opened in the large file mode which enables the file handling
-functions to use files up to @math{2^63} bytes in size and offset from
-@math{-2^63} to @math{2^63}.  This happens transparently for the user
+functions to use files up to @twoexp{63} bytes in size and offset from
+-@twoexp{63} to @twoexp{63}.  This happens transparently for the user
 since all of the lowlevel file handling functions are equally replaced.
 
 This function is a cancellation point in multi-threaded programs.  This
@@ -201,8 +213,8 @@  open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
 If on a 32 bit machine the sources are translated with
 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
 descriptor opened in the large file mode which enables the file handling
-functions to use files up to @math{2^63} in size and offset from
-@math{-2^63} to @math{2^63}.  This happens transparently for the user
+functions to use files up to @twoexp{63} in size and offset from
+-2@twoexp{63} to @twoexp{63}.  This happens transparently for the user
 since all of the lowlevel file handling functions are equally replaced.
 @end deftypefn
 
@@ -422,7 +434,7 @@  not affected by the operation.  The value is the same as before the call.
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
 @code{pread} function is in fact @code{pread64} and the type
 @code{off_t} has 64 bits, which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
 
 The return value of @code{pread} describes the number of bytes read.
 In the error case it returns @math{-1} like @code{read} does and the
@@ -451,7 +463,7 @@  version 2.
 This function is similar to the @code{pread} function.  The difference
 is that the @var{offset} parameter is of type @code{off64_t} instead of
 @code{off_t} which makes it possible on 32 bit machines to address
-files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
 file descriptor @code{filedes} must be opened using @code{open64} since
 otherwise the large offsets possible with @code{off64_t} will lead to
 errors with a descriptor in small file mode.
@@ -623,7 +635,7 @@  not affected by the operation.  The value is the same as before the call.
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
 @code{pwrite} function is in fact @code{pwrite64} and the type
 @code{off_t} has 64 bits, which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
 
 The return value of @code{pwrite} describes the number of written bytes.
 In the error case it returns @math{-1} like @code{write} does and the
@@ -652,7 +664,7 @@  version 2.
 This function is similar to the @code{pwrite} function.  The difference
 is that the @var{offset} parameter is of type @code{off64_t} instead of
 @code{off_t} which makes it possible on 32 bit machines to address
-files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
 file descriptor @code{filedes} must be opened using @code{open64} since
 otherwise the large offsets possible with @code{off64_t} will lead to
 errors with a descriptor in small file mode.
@@ -752,7 +764,7 @@  only for pipes and FIFOs, but on @gnusystems{}, you always get
 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
 @code{lseek} function is in fact @code{lseek64} and the type
 @code{off_t} has 64 bits which makes it possible to handle files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
 
 This function is a cancellation point in multi-threaded programs.  This
 is a problem if the thread allocates some resources (like memory, file
@@ -775,7 +787,7 @@  descriptors.
 This function is similar to the @code{lseek} function.  The difference
 is that the @var{offset} parameter is of type @code{off64_t} instead of
 @code{off_t} which makes it possible on 32 bit machines to address
-files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
 file descriptor @code{filedes} must be opened using @code{open64} since
 otherwise the large offsets possible with @code{off64_t} will lead to
 errors with a descriptor in small file mode.
@@ -848,7 +860,7 @@  is transparently replaced by @code{off64_t}.
 This type is used similar to @code{off_t}.  The difference is that even
 on 32 bit machines, where the @code{off_t} type would have 32 bits,
 @code{off64_t} has 64 bits and so is able to address files up to
-@math{2^63} bytes in length.
+@twoexp{63} bytes in length.
 
 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
 available under the name @code{off_t}.
diff --git a/manual/stdio.texi b/manual/stdio.texi
index e407170..7d62829 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -6,6 +6,18 @@ 
 \hyphenation{which-ever}
 @end tex
 
+@iftex
+@macro twoexp{exp}
+@math{2^{{\exp\}}}
+@end macro
+@end iftex
+@ifnottex
+@macro twoexp{exp}
+2^\exp\
+@end macro
+@end ifnottex
+
+
 This chapter describes the functions for creating streams and performing
 input and output operations on them.  As discussed in @ref{I/O
 Overview}, a stream is a fairly abstract, high-level concept
@@ -270,7 +282,7 @@  Locks}.
 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
 This function is similar to @code{fopen} but the stream it returns a
 pointer for is opened using @code{open64}.  Therefore this stream can be
-used even on files larger than @math{2^31} bytes on 32 bit machines.
+used even on files larger than @twoexp{31} bytes on 32 bit machines.
 
 Please note that the return type is still @code{FILE *}.  There is no
 special @code{FILE} type for the LFS interface.
@@ -336,7 +348,7 @@  interface replaces transparently the old interface.
 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
 This function is similar to @code{freopen}.  The only difference is that
 on 32 bit machine the stream returned is able to read beyond the
-@math{2^31} bytes limits imposed by the normal interface.  It should be
+@twoexp{31} bytes limits imposed by the normal interface.  It should be
 noted that the stream pointed to by @var{stream} need not be opened
 using @code{fopen64} or @code{freopen64} since its mode is not important
 for this function.
@@ -4412,7 +4424,7 @@  This function is similar to @code{ftello} with the only difference that
 the return value is of type @code{off64_t}.  This also requires that the
 stream @var{stream} was opened using either @code{fopen64},
 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
-file operations to position the file pointer beyond the @math{2^31}
+file operations to position the file pointer beyond the @twoexp{31}
 bytes limit might fail.
 
 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
@@ -4473,7 +4485,7 @@  the @var{offset} parameter is of type @code{off64_t}.  This also
 requires that the stream @var{stream} was opened using either
 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
 the underlying file operations to position the file pointer beyond the
-@math{2^31} bytes limit might fail.
+@twoexp{31} bytes limit might fail.
 
 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
 bits machine this function is available under the name @code{fseeko}