[v3,BZ,#17787] Fix exponents in manual.
Commit Message
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
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.
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.
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.
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}").
@@ -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.
@@ -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}.
@@ -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}