• R/O
  • HTTP
  • SSH
  • HTTPS

Commit

Tags
Keine Tags

Frequently used words (click to add to your profile)

javac++androidlinuxc#objective-cqt誰得windowscocoapythonphprubygameguibathyscaphec翻訳omegat計画中(planning stage)frameworktwittertestdomvb.netdirectxbtronarduinopreviewerゲームエンジン

POSIX.1 National Language Support API for MinGW


Commit MetaInfo

Revision05d9c2386afc8f9d424966c6f6b3d48b6248f5f1 (tree)
Zeit2007-07-17 07:16:52
AutorKeith Marshall <keithmarshall@user...>
CommiterKeith Marshall

Log Message

Add manpage sources.

Ändern Zusammenfassung

Diff

--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,30 @@
11 2007-07-16 Keith Marshall <keithmarshall@users.sourceforge.net>
22
3+ Add manpage sources.
4+
5+ * man: New directory, containing...
6+ * man/catopen.man, man/catgets.man, man/catclose.man: New files.
7+ * man/gencat.man: New file.
8+
9+ * Makefile.in (VPATH): Add `man' source directory.
10+ (MANPAGE_SOURCES): Define; it includes all new `*.man' files, as
11+ itemised above, for this update.
12+ (MANSECTS, MAN1EXT, MAN2EXT, MAN3EXT): Define.
13+ (mansect_lookup, mansect_transform, mansect, manpage): New macros;
14+ use them to define a generic rule for generating installable manpages,
15+ from raw manpage source, used by...
16+ (all-man): this new documentation target.
17+ (all-info, all-html-doc, all-pdf, all-ps): New documentation targets;
18+ none invoke any action, at present.
19+ (all-doc): New collective documentation target; it invokes `all-man',
20+ `all-info', `all-htmldoc', `all-pdf' and `all-ps'.
21+ (all): Add `all-doc' as new prerequisite.
22+ (install-man): Add prerequisites and commands for `MANPAGE_SOURCES'.
23+ (DISTDIRS): Add `man'.
24+ (clean): Add `*.n', `*.a' and `*.dll' as generic prototypes for `rm'.
25+
26+2007-07-16 Keith Marshall <keithmarshall@users.sourceforge.net>
27+
328 * catclose.c (mc_close): Error out, if descriptor for message
429 catalogue to be closed lies outside the valid range.
530
--- /dev/null
+++ b/man/catclose.man
@@ -0,0 +1,89 @@
1+'\"
2+.TH catclose @MAN3EXT@ 21-Jun-2007 MinGW "MinGW Programming Reference
3+.
4+.SH NAME
5+.B catclose
6+\- close a national language message catalogue.
7+.
8+.\" Copyright (C) 2007, Keith Marshall.
9+.
10+.\" Permission is granted to copy, distribute and/or modify this manpage
11+.\" under the terms of the GNU Free Documentation License, Version 1.2
12+.\" or any later version published by the Free Software Foundation, with
13+.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
14+.\" A copy of the license is included in the accompanying file, `FDL'.
15+.
16+.SH SYNOPSIS
17+.BR #include
18+.RB < nl_types.h >
19+.LP
20+.BR "int catclose" ( nl_catd\c
21+.IR catd )
22+.
23+.SH AVAILABILITY
24+Requires linking with the
25+.B \-lcatgets
26+library option.
27+.
28+.SH DESCRIPTION
29+The
30+.BR catclose ()
31+function closes the national language message catlogue,
32+associated with the descriptor
33+.I catd
34+by a preceding call to
35+.BR catopen (@MAN3EXT@),
36+and frees all resources allocated to it.
37+.
38+.SH RETURN VALUE
39+On successfully closing
40+.IR catd ,
41+.BR catclose ()
42+returns zero;
43+on failure it returns
44+.BR -1 ,
45+and
46+.I errno
47+is set to
48+.BR EBADF .
49+.
50+.SH CONFORMING TO
51+POSIX 1003.1-2001.
52+.
53+.SH CAVEATS AND BUGS
54+POSIX specifies a further possible error return case,
55+with
56+.I errno
57+set to
58+.BR EINTR ;
59+this case should not occur on MS\(hyWindows\*(Tm hosts.
60+.
61+.SH SEE ALSO
62+.BR catopen (@MAN3EXT@).
63+.
64+.SH AUTHOR
65+Copyright \(co 2007, Keith Marshall
66+.
67+.LP
68+This man page was written by Keith Marshall
69+<keithmarshall@users.sourceforge.net>
70+for the MinGW project.
71+It relates to the MinGW specific implementation of
72+.BR catgets (@MAN3EXT@).
73+.
74+.LP
75+Permission is granted to copy and redistribute this man page,
76+either
77+.IR "as is" ,
78+or in modified form,
79+under the terms of the
80+.IR "GNU Free Documentation License" ,
81+Version 1.2,
82+or any later version published by the
83+.IR "Free Software Foundation, Inc." ,
84+with no front cover texts,
85+no back cover texts,
86+and no invariant sections.
87+Please refer to
88+.I http://www.gnu.org/licenses/licenses.html#FDL
89+for further information.
--- /dev/null
+++ b/man/catgets.man
@@ -0,0 +1,127 @@
1+'\"
2+.TH catgets @MAN3EXT@ 19-Jun-2007 MinGW "MinGW Programming Reference
3+.
4+.SH NAME
5+.B catgets
6+\- retrieve message text from a national language catalogue
7+.
8+.\" Copyright (C) 2007, Keith Marshall.
9+.
10+.\" Permission is granted to copy, distribute and/or modify this manpage
11+.\" under the terms of the GNU Free Documentation License, Version 1.2
12+.\" or any later version published by the Free Software Foundation, with
13+.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
14+.\" A copy of the license is included in the accompanying file, `FDL'.
15+.
16+.SH SYNOPSIS
17+.BR #include
18+.RB < nl_types.h >
19+.LP
20+.BR "char *catgets" ( nl_catd
21+.IR catd ,
22+.BR int
23+.IR setnum ,
24+.BR int
25+.IR msgnum ,
26+.BI "const char *" \c
27+.IR msg )
28+.
29+.SH AVAILABILITY
30+Requires linking with the
31+.B \-lcatgets
32+library option.
33+.
34+.SH DESCRIPTION
35+The
36+.BR catgets ()
37+function searches in the national language message catalogue
38+specified by
39+.IR catd ,
40+which must have been opened by a preceding call to
41+.BR catopen (@MAN3EXT@),
42+for a message in set number
43+.IR setnum ,
44+which is identified by the message number
45+.IR msgnum .
46+If found,
47+.BR catgets ()
48+returns the text of this message;
49+the
50+.I msg
51+argument specifies a default message,
52+which is returned if the specified message cannot be found
53+in the catalogue.
54+.
55+.SH RETURN VALUE
56+If the specified message entry is successfully located in
57+the catalogue,
58+.BR catgets ()
59+returns a pointer to the null\-terminated string
60+defining the text of the message;
61+if the look\-up is unsuccessful,
62+.BR catgets ()
63+returns
64+.IR msg .
65+.
66+.SH ERROR RETURNS
67+None.
68+.
69+.SH CONFORMING TO
70+POSIX 1003.1-2001.
71+.
72+.SH CAVEATS AND BUGS
73+Text retrieved from a message catalogue is located within
74+an internal buffer allocated by
75+.BR catopen (@MAN3EXT@);
76+it must not be modified by the calling procedure.
77+.
78+.LP
79+The encoding format for message text is defined at the time
80+the catalogue is compiled by
81+.BR gencat (@MAN1EXT@).
82+Nominally,
83+it may be expected to conform to the
84+.B LC_MESSAGES
85+encoding for the active locale,
86+as established by
87+.BR setlocale (@MAN3EXT@);
88+however,
89+this cannot be easily confirmed by the function calling
90+.BR catgets ().
91+Therefore,
92+the calling procedure should assume that
93+the returned text matches the locale encoding;
94+if the message catalogue is known to employ Unicode encoding,
95+then the calling procedure should process the returned message
96+as a Unicode string.
97+.
98+.SH SEE ALSO
99+.BR catopen (@MAN3EXT@),
100+.BR gencat (@MAN1EXT@).
101+.
102+.SH AUTHOR
103+Copyright \(co 2007, Keith Marshall
104+.
105+.LP
106+This man page was written by Keith Marshall
107+<keithmarshall@users.sourceforge.net>
108+for the MinGW project.
109+It relates to the MinGW specific implementation of
110+.BR catgets ().
111+.
112+.LP
113+Permission is granted to copy and redistribute this man page,
114+either
115+.IR "as is" ,
116+or in modified form,
117+under the terms of the
118+.IR "GNU Free Documentation License" ,
119+Version 1.2,
120+or any later version published by the
121+.IR "Free Software Foundation, Inc." ,
122+with no front cover texts,
123+no back cover texts,
124+and no invariant sections.
125+Please refer to
126+.I http://www.gnu.org/licenses/licenses.html#FDL
127+for further information.
--- /dev/null
+++ b/man/catopen.man
@@ -0,0 +1,322 @@
1+'\"
2+.TH catopen @MAN3EXT@ 21-Jun-2007 MinGW "MinGW Programming Reference
3+.
4+.SH NAME
5+.B catopen
6+\- open a national language message catalogue.
7+.
8+.\" Copyright (C) 2007, Keith Marshall.
9+.
10+.\" Permission is granted to copy, distribute and/or modify this manpage
11+.\" under the terms of the GNU Free Documentation License, Version 1.2
12+.\" or any later version published by the Free Software Foundation, with
13+.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
14+.\" A copy of the license is included in the accompanying file, `FDL'.
15+.
16+.SH SYNOPSIS
17+.BR #include
18+.RB < nl_types.h >
19+.LP
20+.BR "nl_catd catopen" ( "const char *" \c
21+.IR name ,
22+.BR int
23+.IR flag )
24+.
25+.SH AVAILABILITY
26+Requires linking with the
27+.B \-lcatgets
28+library option.
29+.
30+.SH DESCRIPTION
31+The
32+.BR catopen ()
33+function opens a national language message catalogue,
34+and returns a catalogue descriptor.
35+Once a message catalogue has been successfully opened,
36+its descriptor remains valid until explicitly closed by calling
37+.BR catclose (@MAN3EXT@),
38+or until the process image is replaced by calling
39+.BR exec ();
40+it is
41+.I never
42+inherited by any child process invoked by
43+.BR spawn ()
44+or by
45+.BR CreateProcess ().
46+.
47+.LP
48+The
49+.I name
50+argument specifies the name of the facility
51+to which the message catalogue relates.
52+If it includes a disk drive designator,
53+any
54+.BR / " or any " \e
55+directory/file name separator characters,
56+then it is assumed to represent an actual path name
57+for the message catalogue;
58+otherwise the message catalogue is located by searching
59+the paths specified by the
60+.B NLSPATH
61+environment variable,
62+substituting
63+.I name
64+for the
65+.B %N
66+translation specifier.
67+If no
68+.B NLSPATH
69+variable exists in the environment,
70+or if no message catalogue matching
71+.I name
72+is found in any path specified by it,
73+an internally defined default
74+.B NLSPATH
75+is searched.
76+.
77+.LP
78+The
79+.I flag
80+argument specifies how
81+.B NLSPATH
82+should be interpreted,
83+when searching for the named message catalogue;
84+it may be specified as the manifest constant
85+.BR NL_CAT_LOCALE ,
86+defined in
87+.BR nl_types.h ,
88+or it should be zero.
89+.
90+.LP
91+When searching
92+.BR NLSPATH ,
93+either as specified in the environment,
94+or using the internal default,
95+the selection of a message catalogue may depend on the
96+specification for the current locale,
97+as defined in the environment;
98+such selection is derived from the definition of
99+.BR LC_MESSAGES ,
100+if the
101+.I flag
102+argument is given as
103+.BR NL_CAT_LOCALE ,
104+or from
105+.B LANG
106+otherwise,
107+and is determined by substitution of the appropriate
108+components of the respective definition for each of the following
109+.B NLSPATH
110+translation specifiers:\(en
111+.ll -\n(INu
112+.
113+.RS
114+.TP
115+.B %l
116+The language specification component
117+of the locale identification string.
118+.
119+.TP
120+.B %t
121+The country/territory component
122+of the locale identification string.
123+.
124+.TP
125+.B %c
126+The codeset specification component
127+of the locale identification string.
128+.
129+.TP
130+.B %L
131+The entire locale identification;
132+nominally equivalent to
133+.BR %l_%t.%c .
134+.RE
135+.
136+.ll +\n(INu
137+.SH RETURN VALUE
138+If the requested message catalogue is successfully opened,
139+.BR catopen ()
140+returns a unique descriptor,
141+which remains associated with the catalogue for as long
142+as it remains open.
143+.
144+.SH ERROR RETURNS
145+If the requested catalogue cannot be successfully opened,
146+.BR catopen ()
147+returns
148+.RB ( nl_catd )( -1 ),
149+(which is
150+.I never
151+returned as a valid descriptor),
152+and
153+.I errno
154+is set to one of the following values:\(en
155+.ll -\n(INu
156+.
157+.RS
158+.TP
159+.B EACCESS
160+The user is not permitted to read the message catalogue
161+associated with the facility specified by
162+.IR name .
163+.
164+.TP
165+.B EMFILE
166+The calling process has too many open files.
167+.
168+.TP
169+.B ENOENT
170+No message catalogue,
171+associated with the facility specified by
172+.IR name ,
173+could be found.
174+.
175+.TP
176+.B ENOMEM
177+There is insufficient free memory available.
178+.ll +\n(INu
179+.RE
180+.
181+.SH ENVIRONMENT
182+.TP
183+.B NLSPATH
184+Specifies a list of semicolon separated path names,
185+by which a message catalogue may be identified.
186+It may include any,
187+or all of the following translation specifiers,
188+in any combination:\(en
189+.ll -\n(INu
190+.
191+.RS
192+.TP
193+.B %N
194+The message catalogue facility name.
195+.
196+.TP
197+.B %l
198+The language component of the locale specification string.
199+.
200+.TP
201+.B %t
202+The territory,
203+or region,
204+component of the locale specification string.
205+.
206+.TP
207+.B %c
208+The codeset component of the locale specification string.
209+.
210+.TP
211+.B %L
212+The fully qualified locale specification string.
213+.ll +\n(INu
214+.RE
215+.
216+.TP
217+.B LC_MESSAGES
218+The locale specification string,
219+used to establish the
220+.B NLSPATH
221+translations for
222+.BR %l ,
223+.BR %t ,
224+.B %c
225+and
226+.BR %L ,
227+when the
228+.I flag
229+argument to
230+.BR catopen ()
231+is specified as
232+.BR NL_CAT_LOCALE .
233+.
234+.TP
235+.B LANG
236+The locale specification string,
237+used to establish the
238+.B NLSPATH
239+translations for
240+.BR %l ,
241+.BR %t ,
242+.B %c
243+and
244+.BR %L ,
245+when the
246+.I flag
247+argument to
248+.BR catopen ()
249+is specified as zero.
250+.
251+.SH CONFORMING TO
252+POSIX 1003.1-2001,
253+but omitting the reporting of error conditions
254+which are unsupported by MS\(hyWindows\*(Tm.
255+.
256+.SH CAVEATS AND BUGS
257+When performing an
258+.B NLSPATH
259+search,
260+the strings substituted for the
261+.BR %l ,
262+.BR %t ,
263+.B %c
264+and
265+.B %L
266+translation specifiers are copied literally from the
267+.B LC_MESSAGES
268+or
269+.B LANG
270+environment variables,
271+as appropriate.
272+If the requisite environment variable is not defined,
273+then the substitution will be performed on the basis of the
274+locale identification string for the system
275+.B LC_CTYPE
276+category,
277+(since MS\(hyWindows\*(Tm does not provide native support for the
278+.B LC_MESSAGES
279+category),
280+as returned by
281+.BR setlocale (@MAN3EXT@);
282+this will be the long form locale identification string,
283+which is standard for MS\(hyWindows\*(Tm systems.
284+If your system uses POSIX conventions for storing message catalogues,
285+with national language directory names specified as ISO\(hy639 language
286+or ISO\(hy3166 territory codes,
287+be sure to set the requisite
288+.B LC_MESSAGES
289+or
290+.B LANG
291+environment variable accordingly.
292+.
293+.SH SEE ALSO
294+.BR catgets (@MAN3EXT@),
295+.BR catclose (@MAN3EXT@).
296+.
297+.SH AUTHOR
298+Copyright \(co 2007, Keith Marshall
299+.
300+.LP
301+This man page was written by Keith Marshall
302+<keithmarshall@users.sourceforge.net>
303+for the MinGW project.
304+It relates to the MinGW specific implementation of
305+.BR catgets (@MAN3EXT@).
306+.
307+.LP
308+Permission is granted to copy and redistribute this man page,
309+either
310+.IR "as is" ,
311+or in modified form,
312+under the terms of the
313+.IR "GNU Free Documentation License" ,
314+Version 1.2,
315+or any later version published by the
316+.IR "Free Software Foundation, Inc." ,
317+with no front cover texts,
318+no back cover texts,
319+and no invariant sections.
320+Please refer to
321+.I http://www.gnu.org/licenses/licenses.html#FDL
322+for further information.
--- /dev/null
+++ b/man/gencat.man
@@ -0,0 +1,628 @@
1+'\"
2+.TH gencat @MAN3EXT@ 16-Jul-2007 MinGW "MinGW User Commands
3+.
4+.SH NAME
5+.B gencat
6+\- compile a national language message catalogue for use with
7+.BR catgets (@MAN3EXT@).
8+.
9+.\" Copyright (C) 2007, Keith Marshall.
10+.
11+.\" Permission is granted to copy, distribute and/or modify this manpage
12+.\" under the terms of the GNU Free Documentation License, Version 1.2
13+.\" or any later version published by the Free Software Foundation, with
14+.\" no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
15+.\" A copy of the license is included in the accompanying file, `FDL'.
16+.
17+.SH SYNOPSIS
18+.B gencat
19+.I catfile
20+.I msgfile
21+\&...
22+.
23+.SH DESCRIPTION
24+.B gencat
25+merges the messages defined in the input file,
26+or files,
27+specified by the
28+.I msgfile
29+argument list into the binary format national language message catalogue
30+specified by
31+.IR catfile .
32+.
33+.LP
34+If
35+.I catfile
36+does not exist,
37+it is created;
38+if it is specified as
39+.BR \- ,
40+or as the special device name
41+.BR /dev/stdout ,
42+then the message catalogue is treated as non\(hyexistent,
43+and it is created by writing the compiled message data to
44+standard output.
45+.
46+.LP
47+Input files in the
48+.I msgfile
49+list are processed in left to right order,
50+as specified.
51+If any file name in this
52+list is specified as
53+.BR \- ,
54+or as the special device name
55+.BR /dev/stdin ,
56+then standard input is read as the corresponding
57+.IR msgfile ;
58+at most one
59+.I msgfile
60+should be specified using either of these special
61+input file names,
62+in any single invocation of
63+.BR gencat .
64+.
65+.SS Message Catalogue Organisation
66+Typically,
67+a collection of message catalogues,
68+comprising one catalogue for each national language,
69+will be provided for a single
70+.IR facility ,
71+(where a
72+.I facility
73+may represent a single application,
74+or a single logical group of applications).
75+.
76+.LP
77+Within each individual catalogue,
78+messages are individually numbered,
79+and organised into numbered
80+.IR sets ,
81+such that each message is uniquely identified by
82+the combination of its set and message numbers;
83+these are indexed,
84+to facilitate retrieval of any specific message by the
85+.BR catgets (@MAN3EXT@)
86+function.
87+Within each multilingual collection of message catalogues,
88+relating to a common
89+.IR facility ,
90+each specific combination of set and message numbers refers to
91+the various national language translations for the same message.
92+.
93+.LP
94+Message text is incorporated into the message catalogues
95+in the form of NUL terminated strings;
96+these may be defined using any codeset which may be
97+appropriate for the respective national language of
98+each individual message catalogue.
99+.
100+.SS Input File Syntax
101+.B gencat
102+input files define both the organisation and content
103+of a message catalogue.
104+They are
105+.I text
106+files,
107+with individual lines delimited by either
108+.B LF
109+or
110+.B CRLF
111+line terminators;
112+every line of input
113+.I must
114+be properly terminated,
115+by either of these line terminators.
116+.
117+.LP
118+Each line of input must represent one of the input record types:\(en
119+.ll -4n
120+.
121+.RS 4n
122+.TP 4n
123+.IR "\fB$\fP comment" " ..."
124+Lines having
125+.B $
126+as their first character,
127+followed by one or more white space characters,
128+and then any additional characters up to and
129+including the line terminator,
130+are considered as comments.
131+They are parsed in the POSIX locale,
132+(with conversion of the input encoding from
133+UTF\(hy16 or UTF\(hy32 if required).
134+With the execption of the special case of a
135+.I codeset
136+declaration,
137+such comment lines are simply ignored.
138+.
139+.TP
140+.BR "$ codeset" = \fIencoding
141+This special use of a
142+.B comment
143+line is an extension to the POSIX standard.
144+It functions as a pseudo\(hydirective,
145+which provides a mechanism for specifying the codeset in which
146+messages are to be defined,
147+when this differs from the prevailing codeset
148+of the language specified for the
149+.B LC_CTYPE
150+category of the locale established in the process environment.
151+This feature is not supported
152+when the input encoding is implicitly identified as
153+UTF\(hy16 or UTF\(hy32.
154+.
155+.TP
156+.IR \fB$ < \fBdirective "> " argument " [" comment " ...]"
157+Lines having
158+.B $
159+as their first character,
160+followed immediately by a directive keyword,
161+with no intervening white space,
162+are interpreted as
163+.B gencat
164+directives.
165+The valid directives are:\(en
166+.ll -4n
167+.
168+.RS 4n
169+.TP 4n
170+.IR \fB$quote " [<" char ">]"
171+Identifies a single character,
172+which is to be interpreted as an optional quoting character,
173+while parsing subsequent message definitions.
174+.
175+.IP
176+The optional
177+.RI < char >
178+argument must represent a single character;
179+it is interpreted,
180+possibly as a multi\(hybyte character,
181+in the input encoding,
182+which may be implicitly identified as
183+UTF\(hy16 or UTF\(hy32,
184+explicitly specified by a
185+.I codeset
186+pseudo\(hydirective,
187+or,
188+failing either of these,
189+in the encoding for the
190+.B LC_CTYPE
191+category of the locale defined in the
192+.B gencat
193+process environment.
194+This character may be used,
195+in strict matching pairs,
196+to surround sections of text within message definitions,
197+so improving the visibility of trailing white space,
198+or of empty message definitions,
199+within the source file;
200+such pairs of the quote character are
201+.I not
202+copied to the message definition in the message catalogue.
203+.
204+.IP
205+If a
206+.B $quote
207+directive is issued,
208+from which the
209+.RI < char >
210+argument is omitted,
211+or if no
212+.B $quote
213+directive is specified,
214+then no quoting character is available
215+for use in subsequent message definitions.
216+.
217+.TP
218+.IR \fB$set " <" setnum "> [" comment ]
219+Identifies the set number,
220+.IR setnum ,
221+to which subsequently defined messages are to be added,
222+until the next
223+.B $set
224+directive,
225+or until the end of the source file.
226+The
227+.I setnum
228+argument must represent a decimal integer number in the range from
229+.B 1
230+to the value of the manifest constant
231+.BR NL_SETMAX ,
232+which is defined in
233+.IR nl_types.h .
234+.
235+.IP
236+Within any single source file,
237+set numbers defined by
238+.B $set
239+directives must be presented in strictly ascending order,
240+but they need not be contiguously numbered.
241+.
242+.IP
243+If any source file presents message definitions
244+before the first of any
245+.B $set
246+directives,
247+or if no
248+.B $set
249+directive is present,
250+then those messages are added to
251+the set identified by the manifest constant
252+.BR NL_SETD ,
253+which is defined in
254+.IR nl_types.h .
255+.
256+.TP
257+.IR \fB$delset " <" setnum "> [" comment ]
258+Instructs
259+.B gencat
260+to remove all messages,
261+belonging to the set identified by
262+.IR setnum ,
263+from an existing message catalogue.
264+.RE
265+.
266+.TP
267+.RI < \fBmsgnum "> " "message text" " ... [" \fB\e ]
268+Lines commencing with a numeric
269+.B msgnum
270+tag introduce a new message definition.
271+The
272+.B msgnum
273+tag must be composed of decimal digits from the POSIX portable character set,
274+converted from UTF\(hy16 or UTF\(hy32 encoding as necessary,
275+when either of these is used for input,
276+and must represent a decimal integer number in the range from
277+.B 1
278+to the value of the manifest constant
279+.BR NL_MSGMAX ,
280+which is defined in
281+.IR nl_types.h .
282+It must be separated from the following
283+.I message text
284+by exactly one space character;
285+any additional spaces,
286+where present,
287+are significant and are considered to be part of the defined
288+.IR "message text" .
289+.
290+.IP
291+Within any single message set,
292+as presented within any single source file,
293+.B msgnum
294+records
295+.I must
296+be presented in strictly ascending numerical order of
297+.BR msgnum ;
298+however,
299+the message numbers need not be contiguous.
300+.
301+.IP
302+The
303+.I message text
304+is interpreted using the encoding of the input stream,
305+which may be implicitly identified as
306+UTF\(hy16 or UTF\(hy32,
307+explicitly specified by a
308+.I codeset
309+pseudo\(hydirective,
310+or,
311+where neither of these is applicable,
312+using the encoding for the
313+.B LC_CTYPE
314+category of the locale defined in the
315+.B gencat
316+process environment.
317+.
318+.IP
319+Within
320+.IR "message text" ,
321+the following escape sequences are recognised,
322+and interpreted in place,
323+before copying to the message catalogue:\(en
324+.ll -4n
325+.
326+.RS 8n
327+.TP 9n
328+.B \eb
329+backspace.
330+.
331+.TP
332+.B \ef
333+form feed.
334+.
335+.TP
336+.B \en
337+newline.
338+.
339+.TP
340+.B \er
341+carriage return.
342+.
343+.TP
344+.B \et
345+horizontal tab.
346+.
347+.TP
348+.B \ev
349+vertical tab.
350+.
351+.TP
352+.B \e\e
353+a single literal
354+.B \e
355+character.
356+.
357+.TP
358+.BR \e < ddd >
359+octal digit sequence;
360+the arbitrary length sequence of octal digit characters,
361+.BR ddd ,
362+is parsed,
363+interpreted as the numeric value represented,
364+and replaced by the single character associated with the corresponding
365+position in the collating sequence of the input codeset.
366+.ll +4n
367+.RE
368+.
369+.IP
370+In addition to the above escape sequences,
371+if the
372+.I last
373+character of
374+.IR "message text" ,
375+immediately preceding the
376+.B LF
377+or
378+.B CRLF
379+line terminator,
380+is an unescaped
381+.B \e
382+character,
383+or if
384+.I message text
385+includes an unpaired instance of the quoting character,
386+as defined by the
387+.B $quote
388+directive,
389+then the following line is interpreted as a continuation of
390+.IR "message text" .
391+.
392+.IP
393+When followed by any character,
394+other than those specified for the above escape sequences,
395+or the line terminator,
396+any
397+.B \e
398+character appearing in
399+.I message text
400+is ignored;
401+it is not included in the collected
402+.I message text
403+which is to be copied to the message catalogue.
404+.
405+.IP
406+If
407+.B msgnum
408+is followed by
409+.I exactly
410+one white space character,
411+and immediately thereafter by a
412+.B LF
413+or a
414+.B CRLF
415+line terminator,
416+then a zero length message will be entered into the message catalogue.
417+.
418+.IP
419+If
420+.B msgnum
421+is immediately followed by a
422+.B LF
423+or
424+.B CRLF
425+line terminator,
426+without intervening white space,
427+then any message in the current message set,
428+and with the specified message number,
429+which already exists in the message catalogue,
430+will be deleted.
431+.
432+.TP
433+.IR "continuation message text" " ... [" \fB\e ]
434+Any line,
435+immediately following a message definition record which ends with a
436+.B \e
437+escaped
438+.B LF
439+or
440+.B CRLF
441+terminator,
442+or which includes an unpaired quoting character,
443+is parsed as a logical continuation of the message definition;
444+such continuation may be extended over as many lines as required,
445+by similarly escaping the line terminator
446+on each continuation line but the last,
447+or by deferring the matching of an unpaired quoting character
448+until the last continuation line.
449+.
450+.IP
451+When a message definition is extended over one or more continuation lines,
452+the intervening line terminators are not included in the collected
453+.IR "message text" .
454+Thus,
455+each of the following two examples:\(en
456+.
457+.nf
458+.RS
459+.IP
460+$quote "
461+1 Message defined \e
462+with continuation line.\en
463+.
464+.IP
465+$quote "
466+1 "Message defined
467+\ with continuation line.\en"
468+.RE
469+.IP
470+is equivalent to:\(en
471+.RS
472+.IP
473+$quote "
474+1 Message defined with continuation line.\en
475+.RE
476+.fi
477+.RE
478+.ll +8n
479+.
480+.LP
481+All
482+.IR "message text" ,
483+from each
484+.B msgnum
485+definition line and its following continuation lines,
486+if any,
487+is interpreted and collected into a single logical message definition.
488+Each such definition is indexed by
489+.B setnum
490+and
491+.B msgnum
492+for subsequent retrieval by any application
493+accessing the message catalogue by calling
494+.BR catopen (@MAN3EXT@)
495+and
496+.BR catgets (@MAN3EXT@),
497+and is stored in the message catalogue as a NUL terminated string.
498+.
499+.SH ENVIRONMENT
500+The following environment variables may be set,
501+to control the operation of
502+.BR gencat :\(en
503+.ll -4n
504+.
505+.TP 4n
506+.B LC_ALL
507+If set
508+.B LC_ALL
509+defines the language,
510+territory and encoding attributes to be associated with the
511+.B LC_CTYPE
512+and
513+.B LC_MESSAGE
514+locale categories.
515+.
516+.TP
517+.B LC_CTYPE
518+If
519+.B LC_ALL
520+is not defined,
521+the encoding attribute from the locale category defined by
522+.B LC_CTYPE
523+is used to establish the default codeset for the message catalogue,
524+when the input encoding cannot be identified as either UTF\(hy16 or UTF\(hy32,
525+and there is no
526+.B codeset
527+pseudo\(hydirective specified in the input stream.
528+.
529+.TP
530+.B LC_MESSAGES
531+If
532+.B LC_ALL
533+is not defined,
534+.B LC_MESSAGES
535+defines the language,
536+territory and encoding attributes identifying a message catalogue,
537+in which
538+.BR gencat \(aqs
539+own diagnostic messages are defined.
540+.
541+.TP
542+.B NLSPATH
543+Defines the search path used to locate message catalogues,
544+in which
545+.BR gencat \(aqs
546+own diagnostic messages are defined.
547+.B NLSPATH
548+should be a semicolon separated list of directory paths,
549+in the format required by
550+.BR catopen (@MAN3EXT@).
551+.
552+.SH CONFORMING TO
553+POSIX 1003.1-2001.
554+.
555+.SH CAVEATS AND BUGS
556+Neither the automatic detection of UTF\(hy16 or UTF\(hy32
557+input encoding formats,
558+nor the use of the
559+.B codeset
560+pseudo\(hydirective to specify message catalogue encoding,
561+is mandated by POSIX.
562+While some other
563+.B gencat
564+implementations are known to support the
565+.B codeset
566+pseudo\(hydirective,
567+neither of these features is guaranteed to be portable.
568+.
569+.LP
570+Similarly,
571+the use of unpaired quoting characters to extend message definitions,
572+over one or more continuation lines,
573+is an extension to POSIX requirements,
574+and may not be portable to other
575+.B gencat
576+implementations.
577+.
578+.LP
579+POSIX requires that no individual message shall be greater in length
580+than the value of the manifest constant
581+.BR NL_TEXTMAX ,
582+which is defined in
583+.IR nl_types.h ;
584+this implementation does not enforce this limitation.
585+.
586+.LP
587+POSIX stipulates that the manifest constants
588+.BR NL_SETMAX ,
589+.B NL_MSGMAX
590+and
591+.BR NL_TEXTMAX ,
592+should be defined in
593+.IR limits.h ;
594+this implementation defines them in
595+.I nl_types.h
596+instead.
597+.
598+.SH SEE ALSO
599+.BR catopen (@MAN3EXT@),
600+.BR catgets (@MAN3EXT@),
601+.BR catclose (@MAN3EXT@).
602+.
603+.SH AUTHOR
604+Copyright \(co 2007, Keith Marshall
605+.
606+.LP
607+This man page was written by Keith Marshall
608+<keithmarshall@users.sourceforge.net>
609+for the MinGW project.
610+It relates to the MinGW specific implementation of
611+.BR catgets (@MAN3EXT@).
612+.
613+.LP
614+Permission is granted to copy and redistribute this man page,
615+either
616+.IR "as is" ,
617+or in modified form,
618+under the terms of the
619+.IR "GNU Free Documentation License" ,
620+Version 1.2,
621+or any later version published by the
622+.IR "Free Software Foundation, Inc." ,
623+with no front cover texts,
624+no back cover texts,
625+and no invariant sections.
626+Please refer to
627+.I http://www.gnu.org/licenses/licenses.html#FDL
628+for further information.