This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc 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 v3][BZ #17787] Fix exponents in manual.


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.

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}


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