提交: 45437ae46ecd1f4f82758b394771420ddca71062 - mingw-org-wsl (git)

The MinGW.org Windows System Libraries

Commit MetaInfo

• 修訂: 45437ae46ecd1f4f82758b394771420ddca71062 (tree)
• 時間: 2020-04-12 04:58:43
• 作者: Keith Marshall <keith@user...>
• Commiter: Keith Marshall

Log Message

Manpage stylistic consistency updates.

Change Summary

• modified: mingwrt/ChangeLog
• modified: mingwrt/man/dirname.3.man
• modified: mingwrt/man/getline.3.man

差異

--- a/mingwrt/ChangeLog
+++ b/mingwrt/ChangeLog
@@ -1,3 +1,10 @@
[phone]  Keith Marshall  <[e-mail]>
+
+	Manpage stylistic consistency updates.
+
+	* man/dirname.3.man man/getline.3.man: Miscellaneous stylistic
+	formatting changes.
+
 2020-04-08  Keith Marshall  <[e-mail]>
 
 	Ensure PDF manpages are generated from local sources.

--- a/mingwrt/man/dirname.3.man
+++ b/mingwrt/man/dirname.3.man
@@ -1,6 +1,6 @@
 '\" t
 .\" vim: ft=nroff
-.TH %PAGEREF% MinGW "Programmer's Reference Manual"
+.TH %PAGEREF% MinGW "MinGW Programmer's Reference Manual"
 .
 .SH NAME
 .
@@ -48,16 +48,16 @@ Additionally,
 if the
 .I second
 character of
-.I path
+.I \%path
 is a colon
 .RB (\(dq : \(dq),
 the first two characters of
-.I path
+.I \%path
 are interpreted as an MS\-Windows drive designator,
 which will be included in the
 .B directory name
 component of
-.IR path ,
+.IR \%path ,
 but is never considered to form part of the
 .B file name
 component.
@@ -66,13 +66,13 @@ component.
 In normal usage,
 .BR \%dirname ()
 returns a pointer to a string representing the path name component of
-.IR path ,
+.IR \%path ,
 up to but not including the rightmost directory separator,
 while
 .BR \%basename ()
 returns a pointer to the component following this separator.
 Any trailing directory separators present in
-.I path
+.I \%path
 are disregarded,
 when determining the rightmost separator,
 and, in the case of the return value from
@@ -82,7 +82,7 @@ are each reduced to a single such character.
 .
 .PP
 If
-.I path
+.I \%path
 contains no MS\-Windows drive designator,
 and no directory separator character,
 then
@@ -92,9 +92,9 @@ returns the string
 and
 .BR \%basename ()
 returns a copy of
-.IR path.
+.IR \%path.
 If
-.I path
+.I \%path
 does commence with an MS\-Windows drive designator,
 but contains no directory separators,
 then
@@ -107,14 +107,14 @@ represents the drive designator,
 while
 .BR \%basename ()
 returns a copy of
-.IR path ,
+.IR \%path ,
 with its initial two characters,
 (i.e.\ the drive designator),
 deleted.
 .
 .PP
 If
-.I path
+.I \%path
 is a NULL pointer,
 or is a pointer to an empty string,
 then both
@@ -126,7 +126,7 @@ return the string
 .
 .PP
 If
-.I path
+.I \%path
 is the string
 .RB \(dq / \(dq,
 or the string
@@ -143,7 +143,7 @@ respectively.
 .
 .PP
 If
-.I path
+.I \%path
 commences with
 .I exactly
 two directory separator characters,
@@ -156,13 +156,13 @@ This construct does not affect the string returned by
 neither is this behaviour replicated by
 .BR \%dirname (),
 if
-.I path
+.I \%path
 includes an MS\-Windows drive designator.
 .
 .PP
 In the special case,
 where
-.I path
+.I \%path
 is specified as
 .I exactly
 two identical directory separator characters,
@@ -170,7 +170,7 @@ with no MS\-Windows drive designator,
 and no following path name,
 .BR \%dirname ()
 returns
-.I path
+.I \%path
 unchanged;
 .BR \%basename ()
 normalises the return string to only a single character,
@@ -179,7 +179,7 @@ either
 or
 .RB \(dq \e \(dq,
 matching the characters used to specify
-.IR path .
+.IR \%path .
 .
 .PP
 Concatenating the string returned by
@@ -222,7 +222,7 @@ the test program defines the following function:\(em
 .
 .PP
 .RS
-.nf
+.EX
 #include <stdio.h>
 #include <string.h>
 #include <libgen.h>
@@ -238,7 +238,7 @@ void result( char *path )
   free( dir );
   free( file );
 }
-.fi
+.EE
 .RE
 .PP
 This illustrates the correct use of the
@@ -247,14 +247,14 @@ and the
 .BR \%basename ()
 functions,
 with copies of the original
-.I path
+.I \%path
 string being passed in the function calls.
 Note that the return values from each function are used immediately,
 in the
-.BR printf ()
+.BR \%printf ()
 call,
 and the temporary copies of
-.I path
+.I \%path
 are discarded,
 and the associated memory is freed,
 before these go out of scope.
@@ -373,7 +373,7 @@ The
 .BR \%dirname ()
 function returns a pointer to a null terminated string,
 which represents the directory path component of the passed
-.I path
+.I \%path
 string,
 without any trailing directory separator character,
 and with all internal sequences of directory separator characters
@@ -385,13 +385,13 @@ The
 function
 returns a pointer to a null terminated string,
 which represents the rightmost element of the passed
-.I path
+.I \%path
 string,
 with all trailing directory separator characters removed.
 .
 .PP
 If any MS\-Windows drive designator is specified in the input
-.I path
+.I \%path
 string,
 it is included in the return value of the
 .BR \%dirname ()
@@ -413,10 +413,10 @@ The
 and
 .BR \%basename ()
 functions may modify the
-.I path
+.I \%path
 string passed to them.
 Therefore, it is an error to pass a character constant as the
-.I path
+.I \%path
 parameter;
 to do so may result in memory violation errors,
 (segmentation faults),
@@ -424,14 +424,14 @@ and consequent abnormal program termination.
 .PP
 Also note that,
 since the
-.I path
+.I \%path
 argument may be modified by the
 .BR \%dirname ()
 or the
 .BR \%basename ()
 function call,
 if you wish to preserve the original content of
-.IR path ,
+.IR \%path ,
 you should pass a copy to the function.
 Furthermore,
 either function may return its result in a statically allocated buffer,
@@ -443,13 +443,13 @@ and
 .BR \%basename ()
 functions parse path name strings,
 they are basically just
-.I string
+.I \%string
 functions.
 The presence of an MS\-Windows drive designator is determined
 by the appearance of a colon
 .RB (\(dq : \(dq)
 as the second character of the
-.I path
+.I \%path
 string,
 but neither function performs any check
 to ensure that the first character represents a valid file system device;
@@ -461,7 +461,8 @@ represents a valid path name.
 .SH AUTHOR
 .
 This manpage was written by \%Keith\ Marshall,
-\%<[e-mail]>, to document the
+\%<[e-mail]>,
+to document the
 .BR \%basename ()
 and
 .BR \%dirname ()
@@ -469,7 +470,7 @@ functions as they have been implemented for the MinGW.org Project.
 It may be copied, modified and redistributed,
 without restriction of copyright,
 provided this acknowledgement of contribution by
-the original author remains unchanged.
+the original author remains in place.
 .
 .
 .\" EOF

--- a/mingwrt/man/getline.3.man
+++ b/mingwrt/man/getline.3.man
@@ -1,5 +1,5 @@
 .\" vim: ft=nroff
-.TH %PAGEREF% MinGW "Programmer's Reference Manual"
+.TH %PAGEREF% MinGW "MinGW Programmer's Reference Manual"
 .
 .SH NAME
 .BR getline ,\0 getdelim
@@ -28,8 +28,7 @@
 .BI * stream
 .B  );
 .
-.PP
-.in -4n
+.IP \& -4n
 Feature Test Macro Requirements for libmingwex:
 .TP 4
 .BR getdelim (),\~ getline ():
@@ -41,52 +40,52 @@ Available since libmingwex version 3.22:
 .
 .SH DESCRIPTION
 The
-.BR getdelim ()
+.BR \%getdelim ()
 function reads data from
-.IR stream ,
+.IR \%stream ,
 until either a character entity matching
-.IR delim ,
+.IR \%delim ,
 or
 .I EOF
 is encountered;
 the data so read,
 including the
-.I delim
+.I \%delim
 character if present,
 is stored into the buffer referenced by the pointer at
 .B *\c
-.IR linebuf ,
+.IR \%linebuf ,
 and is
 .I NUL
 terminated.
 .PP
 The
-.BR getline ()
+.BR \%getline ()
 function is a special case of
-.BR getdelim (),
+.BR \%getdelim (),
 with the
-.I delim
+.I \%delim
 argument implicitly specified as the POSIX newline character,
 .IR '\en' .
 .
 .PP
 The
-.I linebuf
+.I \%linebuf
 argument must be a reference to a pointer which is safe to pass to
-.BR free ();
+.BR \%free ();
 either a
-.I NULL
+.I \%NULL
 pointer,
 or a pointer to a buffer of size as indicated by
 .B *\c
 .IR n ,
 allocated by
-.BR malloc ().
+.BR \%malloc ().
 Passing a value of
-.I NULL
+.I \%NULL
 in
 .B *\c
-.IR linebuf ,
+.IR \%linebuf ,
 with a value of zero in
 .B *\c
 .IR n ,
@@ -96,7 +95,7 @@ of a default buffer.
 .
 .PP
 The
-.I delim
+.I \%delim
 argument is specified as an
 .BR int ;
 it must be passed a value which is representable as an
@@ -108,21 +107,21 @@ otherwise the behaviour is undefined.
 If
 .BI * linebuf
 is initially passed as a
-.I NULL
+.I \%NULL
 pointer,
 then
-.BR getdelim ()
+.BR \%getdelim ()
 or
-.BR getline ()
+.BR \%getline ()
 will call
-.BR malloc (),
+.BR \%malloc (),
 in an attempt to allocate
 .BI * n
 bytes,
 or an arbitrarily sized smaller default buffer,
 if such an allocation is not achievable.
 In either case,
-.BI * linebuf
+.BI \%* linebuf
 and
 .BI * n
 will be updated to reflect the allocated buffer location,
@@ -132,11 +131,11 @@ and the actual size allocated.
 If,
 at any time during collection of the input record,
 the buffer referenced by
-.BI * linebuf
+.BI \%* linebuf
 becomes too small to store the record,
 it will be expanded as necessary,
 and both
-.BI * linebuf
+.BI \%* linebuf
 and
 .BI * n
 will be adjusted to reflect the change in allocation.
@@ -145,14 +144,14 @@ will be adjusted to reflect the change in allocation.
 .SH RETURN VALUE
 .
 On successful completion,
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim ()
+.BR \%getdelim ()
 return the number of characters stored into the buffer at
 .B *\c
-.IR linebuf ,
+.IR \%linebuf ,
 including the
-.I delim
+.I \%delim
 character if this was encountered before
 .IR EOF ,
 but excluding the terminating
@@ -162,22 +161,22 @@ character.
 .PP
 If no characters were read,
 and
-.I stream
+.I \%stream
 is at end-of-file,
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim ()
+.BR \%getdelim ()
 return \(mi1,
 and the end-of-file indicator is set for
-.IR stream .
+.IR \%stream .
 .
 .PP
 If an error occurs,
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim ()
+.BR \%getdelim ()
 set
-.IR errno ,
+.IR \%errno ,
 as indicated under the heading
 .B ERROR CONDITIONS
 below,
@@ -186,95 +185,100 @@ and return \(mi1.
 .
 .SH ERROR CONDITIONS
 .
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim
+.BR \%getdelim
 may fail for any of the reasons described as failure conditions for
-.BR fgetc ();
+.BR \%fgetc ();
 when any such error occurs,
-.I errno
+.I \%errno
 is left as set by
-.BR fgetc (),
+.BR \%fgetc (),
 and
-.BR getline ()
+.BR \%getline ()
 or
-.BR getdelim ()
+.BR \%getdelim ()
 returns \(mi1.
 .
 .PP
 In addition to
-.BR fgetc ()
+.BR \%fgetc ()
 failure conditions,
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim ()
+.BR \%getdelim ()
 may fail,
 returning \(mi1 after setting
-.I errno
+.I \%errno
 to indicate occurrence of any of the following errors:
 .
 .RS 4
 .TP 10
-.B EINVAL
-.I linebuf
+.B \%EINVAL
+.I \%linebuf
 or
 .I n
 is
-.IR NULL .
+.IR \%NULL .
 .
 .TP 10
 .B EBADF
-.I stream
+.I \%stream
 is a
-.I NULL
+.I \%NULL
 pointer,
 or otherwise is not a valid stream opened for reading,
 as determined by
-.BR fgetc ().
+.BR \%fgetc ().
 .
 .TP 10
 .B ENOMEM
 An attempt to allocate a buffer,
 or to expand the buffer referenced by
 .B *
-.IR linebuf ,
+.IR \%linebuf ,
 was unsuccessful.
 .
 .TP 10
 .B ERANGE
 More than
-.B SSIZE_MAX
+.B \%SSIZE_MAX
 characters were read,
 without finding
-.IR delim .
-(Note that POSIX specifies that
+.IR \%delim .
+(Note that
+.B \%POSIX.1
+specifies that
 .I errno
 should be set to
-.B EOVERFLOW
+.B \%EOVERFLOW
 for this error condition;
 see heading
 .B CAVEATS AND BUGS
 below,
 for the rationale for the use of
-.B ERANGE
+.B \%ERANGE
 in this implementation).
 .RE
 .
 .
-.SH CONFORMING TO
+.SH STANDARDS CONFORMANCE
 .
 Originally implemented as GNU extension functions,
 both
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim ()
-were adopted into POSIX.1-2008;
-implementations conforming to this POSIX standard have been
-integrated into libmingwex from version 3.22 onwards.
+.BR \%getdelim ()
+were adopted into
+.BR \%POSIX.1\(hy2008 ;
+implementations conforming to this
+.B \%POSIX.1
+standard have been integrated into libmingwex
+from version 3.22 onwards.
 .
 .
 .SH EXAMPLE
-.nf
+.EX
 #include <stdio.h>
 #include <stdlib.h>
 
@@ -297,62 +301,63 @@ int main ()
   fclose (fp);
   return 0;
 }
-.fi
+.EE
 .
 .
 .SH CAVEATS AND BUGS
 .
 A return value of \(mi1 may indicate that
-.I stream
+.I \%stream
 is already at end-of-file when
-.BR getline ()
+.BR \%getline ()
 or
-.BR getdelim ()
+.BR \%getdelim ()
 is called,
 or it may indicate an error condition;
 use
-.BR ferror ()
+.BR \%ferror ()
 or
-.BR feof ()
+.BR \%feof ()
 to distinguish error and end-of-file conditions.
 .
 .PP
 The return type of
-.I ssize_t
+.I \%ssize_t
 can accommodate a maximum character count of
-.BR SSIZE_MAX ,
+.BR \%SSIZE_MAX ,
 and thus,
 the return value will overflow if
-.BR getline ()
+.BR \%getline ()
 or
-.BR getdelim ()
+.BR \%getdelim ()
 reads
-.B SSIZE_MAX
+.B \%SSIZE_MAX
 characters without encountering a line delimiter;
 for this overflow condition,
-POSIX.1-2008 stipulates an
+.B \%POSIX.1\(hy2008
+stipulates an
 .I errno
 condition code of
-.B EOVERFLOW .
+.B \%EOVERFLOW .
 However,
 MSVCRT.DLL provides no significant interpretation for
 an arbitrarily assigned
-.B EOVERFLOW
-.I errno
+.B \%EOVERFLOW
+.I \%errno
 code.
 Thus,
 this implementation of
-.BR getline ()
+.BR \%getline ()
 and
-.BR getdelim ()
+.BR \%getdelim ()
 substitutes the semantically similar,
 (but not semantically identical),
-.B ERANGE
-.I errno
+.B \%ERANGE
+.I \%errno
 code for
-.BR EOVERFLOW ,
+.BR \%EOVERFLOW ,
 to ensure that MSVCRT.DLL's
-.BR strerror ()
+.BR \%strerror ()
 can return an acceptable description for this error condition.
 .
 .
@@ -361,20 +366,21 @@ can return an acceptable description for this error condition.
 Please refer to Microsoft's documentation,
 on MSDN,
 for standard I/O streams,
-.BR fgetc (),
-.BR ferror (),
-.BR feof (),
-.BR malloc (),
-.BR free (),
-.BR strerror (),
+.BR \%fgetc (),
+.BR \%ferror (),
+.BR \%feof (),
+.BR \%malloc (),
+.BR \%free (),
+.BR \%strerror (),
 and
-.BR errno .
+.BR \%errno .
 .
 .
 .SH AUTHOR
 .
 This manpage was written by \%Keith\ Marshall,
-\%<[e-mail]>, to document the
+\%<[e-mail]>,
+to document the
 .BR \%getline ()
 and
 .BR \%getdelim ()
@@ -382,6 +388,6 @@ functions as they have been implemented for the MinGW.org Project.
 It may be copied, modified and redistributed,
 without restriction of copyright,
 provided this acknowledgement of contribution by
-the original author remains unchanged.
+the original author remains in place.
 .
 .\" EOF