From 88bb7e9bee473d6b4a6fb4b0cfa193eaed806abc Mon Sep 17 00:00:00 2001 From: =?utf8?q?Fran=C3=A7ois=20Pinard?= Date: Thu, 13 Mar 2008 18:01:17 -0400 Subject: [PATCH] Manual: header usage --- THANKS | 1 + doc/ChangeLog | 5 + doc/recode.info | 390 ++++++++++++++++++++++++------------------------ doc/recode.texi | 163 ++++++++++---------- 4 files changed, 289 insertions(+), 270 deletions(-) diff --git a/THANKS b/THANKS index 6f06d78..86b5a67 100644 --- a/THANKS +++ b/THANKS @@ -259,4 +259,5 @@ Wilhelm Zadrapa wfz@aon.at William Bader wbader@scarecrow.csee.lehigh.edu Wolfgang Boerner Wolfgang.Boerner@rz.uni-regensburg.de Wolfgang Wander wwc@hermes.desy.de +Xabier Rodriguez Calvar xrcalvar@igalia.com Yves Arrouye diff --git a/doc/ChangeLog b/doc/ChangeLog index b84a56b..cac0c65 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2008-03-13 François Pinard + + * recode.texi: Clarify include files and configuration matters. + Reported by Xabier Rodriguez Calvar. + 2008-03-10 François Pinard * recode.texi (Task level): Use name, not file, in example. diff --git a/doc/recode.info b/doc/recode.info index 66fc0af..473c587 100644 --- a/doc/recode.info +++ b/doc/recode.info @@ -1432,22 +1432,69 @@ programs. A good way to acquire some familiarity with the recoding library is to get acquainted with the `recode' program itself. To use the recoding library once it is installed, a C program needs -to have a line: +to have the following lines: + #include #include + const char *program_name; + near its beginning, and the user should have `-lrecode' on the linking call, so modules from the recoding library are found. + The `recode.h' header file uses the Boolean type setup by the system +header file `stdbool.h'. This header file, which is now part of C +standards, does not likely exist everywhere. If you system does not +offer this system header file yet, the proper compilation of the +`recode.h' file could be guaranteed through the replacement of the +inclusion line by: + + typedef enum {false = 0, true = 1} bool; + + People wanting wider portability, or Autoconf lovers, might arrange +their `configure.ac' for being able to write something more general. +In such contexts, a typical beginning of a program using the Recode +library might look something like: + + #if STDC_HEADERS + # include + #endif + + /* Some systems do not define EXIT_*, even with STDC_HEADERS. */ + #ifndef EXIT_SUCCESS + # define EXIT_SUCCESS 0 + #endif + #ifndef EXIT_FAILURE + # define EXIT_FAILURE 1 + #endif + /* The following test is to work around the gross typo in systems like Sony + NEWS-OS Release 4.0C, whereby EXIT_FAILURE is defined to 0, not 1. */ + #if !EXIT_FAILURE + # undef EXIT_FAILURE + # define EXIT_FAILURE 1 + #endif + + #if HAVE_STDBOOL_H + # include + #else + typedef enum {false = 0, true = 1} bool; + #endif + + #include + + const char *program_name; + + Yet, for the remainder of the discussion below, we will ignore all +these configuration matters, and merely presume that both `stdlib.h' +and `stdbool.h' system header files are available. + The library is still under development. As it stands, it contains four identifiable sets of routines: the outer level functions, the request level functions, the task level functions and the charset level -functions. There are discussed in separate sections. - - For effectively using the recoding library in most applications, it -should be rarely needed to study anything beyond the main -initialisation function at outer level, and then, various functions at -request level. +functions. There are discussed in separate sections. For effectively +using the recoding library in most applications, it should be rarely +needed to study anything beyond the main initialisation function at +outer level, and then, various functions at request level. * Menu: @@ -1468,6 +1515,7 @@ use, or do actions which are unrelated to specific recodings. Here is an example of a program which does not really make anything useful. #include + #include #include const char *program_name; @@ -1479,10 +1527,10 @@ an example of a program which does not really make anything useful. RECODE_OUTER outer = recode_new_outer (RECODE_AUTO_ABORT_FLAG); recode_delete_outer (outer); - exit (0); + exit (EXIT_SUCCESS); } - The header file `' declares an opaque `RECODE_OUTER' + The header file `recode.h' declares an opaque `RECODE_OUTER' structure, which the programmer should use for allocating a variable in his program (let's assume the programmer is a male, here, no prejudice intended). This `outer' variable is given as a first argument to all @@ -1501,59 +1549,6 @@ not so much attention has been paid to avoid memory leaks at this level within Recode. This is hardly a reason for not plugging such leaks at any level: in the long run, they should all be chased and repaired. - The `' header file uses the Boolean type setup by the -system header file `'. But this header file is still fairly -new in C standards, and likely does not exist everywhere. If you -system does not offer this system header file yet, the proper -compilation of the `' file could be guaranteed through the -replacement of the inclusion line by: - - typedef enum {false = 0, true = 1} bool; - - People wanting wider portability, or Autoconf lovers, might arrange -their `configure.in' for being able to write something more general, -like: - - #if STDC_HEADERS - # include - #endif - - /* Some systems do not define EXIT_*, even with STDC_HEADERS. */ - #ifndef EXIT_SUCCESS - # define EXIT_SUCCESS 0 - #endif - #ifndef EXIT_FAILURE - # define EXIT_FAILURE 1 - #endif - /* The following test is to work around the gross typo in systems like Sony - NEWS-OS Release 4.0C, whereby EXIT_FAILURE is defined to 0, not 1. */ - #if !EXIT_FAILURE - # undef EXIT_FAILURE - # define EXIT_FAILURE 1 - #endif - - #if HAVE_STDBOOL_H - # include - #else - typedef enum {false = 0, true = 1} bool; - #endif - - #include - - const char *program_name; - - int - main (int argc, char *const *argv) - { - program_name = argv[0]; - RECODE_OUTER outer = recode_new_outer (RECODE_AUTO_ABORT_FLAG); - - recode_term_outer (outer); - exit (EXIT_SUCCESS); - } - -but we will not insist on such details in the examples to come. - * Initialisation functions RECODE_OUTER recode_new_outer (FLAGS); @@ -1638,8 +1633,9 @@ Their API is almost stable by now. of a program which sole job is to filter `ibmpc' code on its standard input into `latin1' code on its standard output. - #include #include + #include + #include #include const char *program_name; @@ -1659,10 +1655,10 @@ input into `latin1' code on its standard output. recode_delete_request (request); recode_delete_outer (outer); - exit (success ? 0 : 1); + exit (success ? EXIT_SUCCESS : EXIT_FAILURE); } - The header file `' declares a `RECODE_REQUEST' structure, + The header file `recode.h' declares a `RECODE_REQUEST' structure, which the programmer should use for allocating a variable in his program. This REQUEST variable is given as a first argument to all request level functions, and in most cases, may be considered as opaque. @@ -1883,8 +1879,8 @@ into `latin1' code on its standard output. That is, this program has the same goal as the one from the previous section, but does its things a bit differently. - #include #include + #include #include const char *program_name; @@ -1909,14 +1905,18 @@ a bit differently. recode_delete_request (request); recode_delete_outer (outer); - exit (success ? 0 : 1); + exit (success ? EXIT_SUCCESS : EXIT_FAILURE); } - The header file `' declares a `RECODE_TASK' structure, -which the programmer should use for allocating a variable in his -program. This `task' variable is given as a first argument to all task -level functions. The programmer ought to change and possibly consult a -few fields in this structure, using special functions. + Note that in the example above, `recodext.h' header is used instead +of `recode.h'. By doing so, the various structures are not opaque +anymore, and their fields may be accessed by name. + + The header file `recode.h' declares a `RECODE_TASK' structure, which +the programmer should use for allocating a variable in his program. +This `task' variable is given as a first argument to all task level +functions. The programmer ought to change and possibly consult a few +fields in this structure, using special functions. * Initialisation functions @@ -2032,7 +2032,7 @@ few fields in this structure, using special functions. tells how various recoding steps (passes) will be interconnected. Its initial value is `RECODE_STRATEGY_UNDECIDED', which is a constant defined in - the header file `'. Other possible values are: + the header file `recodext.h'. Other possible values are: `RECODE_SEQUENCE_IN_MEMORY' Keep intermediate recodings in memory. @@ -5043,8 +5043,9 @@ Concept Index * alternate names for charsets and surfaces: Requests. (line 80) * ambiguous output, error message: Errors. (line 31) * ASCII table, recreating with Recode: ASCII. (line 12) +* Autoconf: Library. (line 31) * average number of recoding steps: Main flow. (line 40) -* bool data type: Outer level. (line 44) +* bool data type: Library. (line 22) * box-drawing characters: Recoding. (line 16) * bug reports, where to send: Contributing. (line 37) * byte order mark: UCS-2. (line 12) @@ -5071,6 +5072,7 @@ Concept Index * codepages: IBM and MS. (line 6) * combining characters: UCS-2. (line 34) * commutativity of surfaces: Requests. (line 57) +* configure.ac: Library. (line 31) * contributing charsets: Contributing. (line 6) * conversions, unavailable: Charset overview. (line 33) * convert a subset of characters: Mixed. (line 20) @@ -5123,9 +5125,9 @@ Concept Index * implied surfaces: Requests. (line 69) * impossible conversions: Charset overview. (line 33) * information about charsets: Listings. (line 153) -* initialisation functions, outer: Outer level. (line 97) -* initialisation functions, request: Request level. (line 51) -* initialisation functions, task: Task level. (line 52) +* initialisation functions, outer: Outer level. (line 45) +* initialisation functions, request: Request level. (line 52) +* initialisation functions, task: Task level. (line 56) * interface, with iconv library: iconv. (line 6) * intermediate charsets: Requests. (line 23) * internal functions: Charset level. (line 6) @@ -5139,7 +5141,7 @@ Concept Index * LaTeX files: LaTeX. (line 6) * Latin charsets: ISO 8859. (line 6) * Latin-1 table, recreating with Recode: ISO 8859. (line 45) -* leaks, memory: Outer level. (line 39) +* leaks, memory: Outer level. (line 40) * letter case, in charset and surface names: Requests. (line 93) * libiconv: iconv. (line 6) * library, iconv: iconv. (line 6) @@ -5148,7 +5150,7 @@ Concept Index * map filling: Reversibility. (line 98) * map filling, disable: Reversibility. (line 48) * markup language: HTML. (line 6) -* memory leaks: Outer level. (line 39) +* memory leaks: Outer level. (line 40) * memory sequencing: Sequencing. (line 23) * MIME encodings: MIME. (line 6) * misuse of recoding library, error message: Errors. (line 76) @@ -5167,7 +5169,9 @@ Concept Index * partial conversion: Mixed. (line 20) * permutations of groups of bytes: Permutations. (line 6) * pipe sequencing: Sequencing. (line 40) -* program_name variable: Outer level. (line 150) +* portability: Library. (line 31) +* program_name variable <1>: Outer level. (line 98) +* program_name variable: Library. (line 11) * programming language support: Listings. (line 26) * pseudo-charsets: Charset overview. (line 33) * pure charset: Surface overview. (line 17) @@ -5181,6 +5185,8 @@ Concept Index * Recode, main flow of operation: Main flow. (line 6) * recode, operation as filter: Synopsis. (line 27) * recode, synopsis of invocation: Synopsis. (line 6) +* recode.h header: Library. (line 11) +* recodext.h header: Task level. (line 46) * recoding details: Recoding. (line 35) * recoding library: Library. (line 6) * recoding path, rejection: Recoding. (line 60) @@ -5198,9 +5204,9 @@ Concept Index * silent operation: Reversibility. (line 36) * single step: Main flow. (line 17) * source file generation: Listings. (line 26) -* speed considerations <1>: Request level. (line 43) -* speed considerations: Outer level. (line 31) -* stdbool.h header: Outer level. (line 44) +* speed considerations <1>: Request level. (line 44) +* speed considerations: Outer level. (line 32) +* stdbool.h header: Library. (line 22) * strict operation: Reversibility. (line 48) * string and comments conversion: Mixed. (line 39) * structural surfaces: Surfaces. (line 44) @@ -5219,7 +5225,7 @@ Concept Index * surfaces, syntax: Requests. (line 52) * surfaces, trees: Surfaces. (line 44) * system detected problem, error message: Errors. (line 71) -* task execution: Task level. (line 215) +* task execution: Task level. (line 219) * task level functions: Task level. (line 6) * TeX files: LaTeX. (line 6) * Texinfo files: Texinfo. (line 6) @@ -5301,15 +5307,15 @@ and variables in the Recode library. [index] * Menu: -* abort_level: Task level. (line 198) -* ascii_graphics: Request level. (line 110) -* byte_order_mark: Task level. (line 182) +* abort_level: Task level. (line 202) +* ascii_graphics: Request level. (line 111) +* byte_order_mark: Task level. (line 186) * declare_step: New surfaces. (line 13) * DEFAULT_CHARSET: Requests. (line 104) -* diacritics_only: Request level. (line 101) -* diaeresis_char: Request level. (line 85) -* error_so_far: Task level. (line 210) -* fail_level: Task level. (line 188) +* diacritics_only: Request level. (line 102) +* diaeresis_char: Request level. (line 86) +* error_so_far: Task level. (line 214) +* fail_level: Task level. (line 192) * file_one_to_many: New charsets. (line 70) * file_one_to_one: New charsets. (line 58) * find_charset: Charset level. (line 15) @@ -5318,48 +5324,48 @@ and variables in the Recode library. * list_all_charsets: Charset level. (line 15) * list_concise_charset: Charset level. (line 15) * list_full_charset: Charset level. (line 15) -* make_header_flag: Request level. (line 92) +* make_header_flag: Request level. (line 93) * RECODE_AMBIGUOUS_OUTPUT: Errors. (line 31) -* recode_buffer_to_buffer: Request level. (line 156) -* recode_buffer_to_file: Request level. (line 156) -* recode_delete_outer: Outer level. (line 102) -* recode_delete_request: Request level. (line 56) -* recode_delete_task: Task level. (line 54) -* recode_file_to_buffer: Request level. (line 156) -* recode_file_to_file: Request level. (line 156) -* recode_filter_close: Task level. (line 217) -* recode_filter_close, not available: Request level. (line 221) -* recode_filter_open: Task level. (line 217) -* recode_filter_open, not available: Request level. (line 221) -* recode_format_table: Request level. (line 236) +* recode_buffer_to_buffer: Request level. (line 157) +* recode_buffer_to_file: Request level. (line 157) +* recode_delete_outer: Outer level. (line 50) +* recode_delete_request: Request level. (line 57) +* recode_delete_task: Task level. (line 58) +* recode_file_to_buffer: Request level. (line 157) +* recode_file_to_file: Request level. (line 157) +* recode_filter_close: Task level. (line 221) +* recode_filter_close, not available: Request level. (line 222) +* recode_filter_open: Task level. (line 221) +* recode_filter_open, not available: Request level. (line 222) +* recode_format_table: Request level. (line 237) * RECODE_INTERNAL_ERROR: Errors. (line 81) * RECODE_INVALID_INPUT: Errors. (line 61) * RECODE_MAXIMUM_ERROR <1>: Errors. (line 88) -* RECODE_MAXIMUM_ERROR: Task level. (line 198) -* recode_new_outer: Outer level. (line 102) -* recode_new_request: Request level. (line 56) -* recode_new_task: Task level. (line 54) +* RECODE_MAXIMUM_ERROR: Task level. (line 202) +* recode_new_outer: Outer level. (line 50) +* recode_new_request: Request level. (line 57) +* recode_new_task: Task level. (line 58) * RECODE_NO_ERROR: Errors. (line 16) * RECODE_NOT_CANONICAL: Errors. (line 19) -* RECODE_OUTER structure: Outer level. (line 25) -* recode_perform_task: Task level. (line 217) -* recode_request structure: Request level. (line 68) -* RECODE_REQUEST structure: Request level. (line 38) -* recode_scan_request: Request level. (line 120) -* RECODE_SEQUENCE_IN_MEMORY: Task level. (line 169) -* RECODE_SEQUENCE_WITH_FILES: Task level. (line 172) -* RECODE_SEQUENCE_WITH_PIPE: Task level. (line 175) -* RECODE_STRATEGY_UNDECIDED: Task level. (line 162) -* recode_string: Request level. (line 149) -* recode_string_to_buffer: Request level. (line 156) -* recode_string_to_file: Request level. (line 156) +* RECODE_OUTER structure: Outer level. (line 26) +* recode_perform_task: Task level. (line 221) +* recode_request structure: Request level. (line 69) +* RECODE_REQUEST structure: Request level. (line 39) +* recode_scan_request: Request level. (line 121) +* RECODE_SEQUENCE_IN_MEMORY: Task level. (line 173) +* RECODE_SEQUENCE_WITH_FILES: Task level. (line 176) +* RECODE_SEQUENCE_WITH_PIPE: Task level. (line 179) +* RECODE_STRATEGY_UNDECIDED: Task level. (line 166) +* recode_string: Request level. (line 150) +* recode_string_to_buffer: Request level. (line 157) +* recode_string_to_file: Request level. (line 157) * RECODE_SYSTEM_ERROR: Errors. (line 71) -* RECODE_TASK structure: Task level. (line 46) +* RECODE_TASK structure: Task level. (line 50) * RECODE_UNTRANSLATABLE: Errors. (line 50) * RECODE_USER_ERROR: Errors. (line 76) -* strategy: Task level. (line 162) -* task_request structure: Task level. (line 81) -* verbose_flag: Request level. (line 80) +* strategy: Task level. (line 166) +* task_request structure: Task level. (line 85) +* verbose_flag: Request level. (line 81)  File: recode.info, Node: Charset and Surface Index, Prev: Library Index, Up: Top @@ -6128,73 +6134,73 @@ Node: Mixed55326 Node: Emacs58694 Node: Debugging59728 Node: Library63998 -Node: Outer level65352 -Node: Request level72226 -Node: Task level83173 -Node: Charset level93595 -Node: Errors94437 -Ref: Errors-Footnote-199283 -Ref: Errors-Footnote-299397 -Node: Universal99758 -Ref: Universal-Footnote-1102870 -Ref: Universal-Footnote-2102936 -Node: UCS-2103149 -Node: UCS-4105675 -Node: UTF-7106215 -Node: UTF-8106810 -Node: UTF-16111115 -Node: count-characters112263 -Node: dump-with-names112934 -Node: iconv115483 -Node: Tabular118914 -Node: ASCII misc141127 -Node: ASCII141493 -Node: ISO 8859142309 -Node: ASCII-BS144603 -Node: flat146440 -Node: IBM and MS147111 -Node: EBCDIC147655 -Node: IBM-PC149751 -Ref: IBM-PC-Footnote-1151865 -Node: Icon-QNX152024 -Node: CDC152449 -Node: Display Code154130 -Ref: Display Code-Footnote-1156411 -Node: CDC-NOS156616 -Node: Bang-Bang158578 -Node: Micros160507 -Node: Apple-Mac160890 -Node: AtariST162924 -Node: Miscellaneous163910 -Node: HTML164829 -Node: LaTeX170818 -Node: Texinfo171592 -Node: Vietnamese172364 -Node: African173340 -Node: Others174690 -Node: Java176143 -Node: Texte176810 -Ref: Texte-Footnote-1181358 -Ref: Texte-Footnote-2181438 -Ref: Texte-Footnote-3181913 -Node: Mule182010 -Ref: Mule-Footnote-1183791 -Node: Surfaces184310 -Ref: Surfaces-Footnote-1187729 -Node: Permutations187833 -Node: End lines188674 -Node: MIME190875 -Node: Dump192062 -Node: Test196232 -Node: Internals198710 -Node: Main flow199938 -Node: New charsets203041 -Node: New surfaces207579 -Node: Design208305 -Ref: Design-Footnote-1217471 -Node: Concept Index217575 -Node: Option Index232610 -Node: Library Index235463 -Node: Charset and Surface Index240038 +Node: Outer level66958 +Node: Request level72307 +Node: Task level83299 +Node: Charset level93929 +Node: Errors94771 +Ref: Errors-Footnote-199617 +Ref: Errors-Footnote-299731 +Node: Universal100092 +Ref: Universal-Footnote-1103204 +Ref: Universal-Footnote-2103270 +Node: UCS-2103483 +Node: UCS-4106009 +Node: UTF-7106549 +Node: UTF-8107144 +Node: UTF-16111449 +Node: count-characters112597 +Node: dump-with-names113268 +Node: iconv115817 +Node: Tabular119248 +Node: ASCII misc141461 +Node: ASCII141827 +Node: ISO 8859142643 +Node: ASCII-BS144937 +Node: flat146774 +Node: IBM and MS147445 +Node: EBCDIC147989 +Node: IBM-PC150085 +Ref: IBM-PC-Footnote-1152199 +Node: Icon-QNX152358 +Node: CDC152783 +Node: Display Code154464 +Ref: Display Code-Footnote-1156745 +Node: CDC-NOS156950 +Node: Bang-Bang158912 +Node: Micros160841 +Node: Apple-Mac161224 +Node: AtariST163258 +Node: Miscellaneous164244 +Node: HTML165163 +Node: LaTeX171152 +Node: Texinfo171926 +Node: Vietnamese172698 +Node: African173674 +Node: Others175024 +Node: Java176477 +Node: Texte177144 +Ref: Texte-Footnote-1181692 +Ref: Texte-Footnote-2181772 +Ref: Texte-Footnote-3182247 +Node: Mule182344 +Ref: Mule-Footnote-1184125 +Node: Surfaces184644 +Ref: Surfaces-Footnote-1188063 +Node: Permutations188167 +Node: End lines189008 +Node: MIME191209 +Node: Dump192396 +Node: Test196566 +Node: Internals199044 +Node: Main flow200272 +Node: New charsets203375 +Node: New surfaces207913 +Node: Design208639 +Ref: Design-Footnote-1217805 +Node: Concept Index217909 +Node: Option Index233382 +Node: Library Index236235 +Node: Charset and Surface Index240810  End Tag Table diff --git a/doc/recode.texi b/doc/recode.texi index 6c1f49a..be77407 100644 --- a/doc/recode.texi +++ b/doc/recode.texi @@ -1694,25 +1694,86 @@ library. The recoding library is available separately for other C programs. A good way to acquire some familiarity with the recoding library is to get acquainted with the @code{recode} program itself. +@cindex @code{recode.h} header +@cindex @code{program_name} variable To use the recoding library once it is installed, a C program needs to -have a line: +have the following lines: @example +#include #include + +const char *program_name; @end example @noindent near its beginning, and the user should have @samp{-lrecode} on the linking call, so modules from the recoding library are found. -The library is still under development. As it stands, it contains four -identifiable sets of routines: the outer level functions, the request -level functions, the task level functions and the charset level functions. -There are discussed in separate sections. +@cindex @code{stdbool.h} header +@cindex @code{bool} data type +The @code{recode.h} header file uses the Boolean type setup by the +system header file @code{stdbool.h}. This header file, which is now +part of C standards, does not likely exist everywhere. If you system +does not offer this system header file yet, the proper compilation of +the @code{recode.h} file could be guaranteed through the replacement +of the inclusion line by: -For effectively using the recoding library in most applications, it should -be rarely needed to study anything beyond the main initialisation function -at outer level, and then, various functions at request level. +@example +typedef enum @{false = 0, true = 1@} bool; +@end example + +@cindex Autoconf +@cindex portability +@cindex @file{configure.ac} +People wanting wider portability, or Autoconf lovers, might arrange +their @file{configure.ac} for being able to write something more +general. In such contexts, a typical beginning of a program using the +Recode library might look something like: + +@example +@group +#if STDC_HEADERS +# include +#endif + +/* Some systems do not define EXIT_*, even with STDC_HEADERS. */ +#ifndef EXIT_SUCCESS +# define EXIT_SUCCESS 0 +#endif +#ifndef EXIT_FAILURE +# define EXIT_FAILURE 1 +#endif +/* The following test is to work around the gross typo in systems like Sony + NEWS-OS Release 4.0C, whereby EXIT_FAILURE is defined to 0, not 1. */ +#if !EXIT_FAILURE +# undef EXIT_FAILURE +# define EXIT_FAILURE 1 +#endif + +#if HAVE_STDBOOL_H +# include +#else +typedef enum @{false = 0, true = 1@} bool; +#endif + +#include + +const char *program_name; +@end group +@end example + +Yet, for the remainder of the discussion below, we will ignore all these +configuration matters, and merely presume that both @code{stdlib.h} +and @code{stdbool.h} system header files are available. + +The library is still under development. As it stands, it contains +four identifiable sets of routines: the outer level functions, the +request level functions, the task level functions and the charset level +functions. There are discussed in separate sections. For effectively +using the recoding library in most applications, it should be rarely +needed to study anything beyond the main initialisation function at +outer level, and then, various functions at request level. @menu * Outer level:: Outer level functions @@ -1734,6 +1795,7 @@ an example of a program which does not really make anything useful. @example @group #include +#include #include const char *program_name; @@ -1745,13 +1807,13 @@ main (int argc, char *const *argv) RECODE_OUTER outer = recode_new_outer (RECODE_AUTO_ABORT_FLAG); recode_delete_outer (outer); - exit (0); + exit (EXIT_SUCCESS); @} @end group @end example @vindex RECODE_OUTER structure -The header file @code{} declares an opaque @code{RECODE_OUTER} +The header file @code{recode.h} declares an opaque @code{RECODE_OUTER} structure, which the programmer should use for allocating a variable in his program (let's assume the programmer is a male, here, no prejudice intended). This @samp{outer} variable is given as a first argument to @@ -1773,67 +1835,6 @@ much attention has been paid to avoid memory leaks at this level within Recode. This is hardly a reason for not plugging such leaks at any level: in the long run, they should all be chased and repaired. -@cindex @code{stdbool.h} header -@cindex @code{bool} data type -The @code{} header file uses the Boolean type setup by the -system header file @code{}. But this header file is still -fairly new in C standards, and likely does not exist everywhere. If you -system does not offer this system header file yet, the proper compilation -of the @code{} file could be guaranteed through the replacement -of the inclusion line by: - -@example -typedef enum @{false = 0, true = 1@} bool; -@end example - -People wanting wider portability, or Autoconf lovers, might arrange their -@file{configure.in} for being able to write something more general, like: - -@example -@group -#if STDC_HEADERS -# include -#endif - -/* Some systems do not define EXIT_*, even with STDC_HEADERS. */ -#ifndef EXIT_SUCCESS -# define EXIT_SUCCESS 0 -#endif -#ifndef EXIT_FAILURE -# define EXIT_FAILURE 1 -#endif -/* The following test is to work around the gross typo in systems like Sony - NEWS-OS Release 4.0C, whereby EXIT_FAILURE is defined to 0, not 1. */ -#if !EXIT_FAILURE -# undef EXIT_FAILURE -# define EXIT_FAILURE 1 -#endif - -#if HAVE_STDBOOL_H -# include -#else -typedef enum @{false = 0, true = 1@} bool; -#endif - -#include - -const char *program_name; - -int -main (int argc, char *const *argv) -@{ - program_name = argv[0]; - RECODE_OUTER outer = recode_new_outer (RECODE_AUTO_ABORT_FLAG); - - recode_term_outer (outer); - exit (EXIT_SUCCESS); -@} -@end group -@end example - -@noindent -but we will not insist on such details in the examples to come. - @itemize @bullet @item Initialisation functions @cindex initialisation functions, outer @@ -1925,8 +1926,9 @@ input into @code{latin1} code on its standard output. @example @group -#include #include +#include +#include #include const char *program_name; @@ -1946,13 +1948,13 @@ main (int argc, char *const *argv) recode_delete_request (request); recode_delete_outer (outer); - exit (success ? 0 : 1); + exit (success ? EXIT_SUCCESS : EXIT_FAILURE); @} @end group @end example @vindex RECODE_REQUEST structure -The header file @code{} declares a @code{RECODE_REQUEST} structure, +The header file @code{recode.h} declares a @code{RECODE_REQUEST} structure, which the programmer should use for allocating a variable in his program. This @var{request} variable is given as a first argument to all request level functions, and in most cases, may be considered as opaque. @@ -2200,8 +2202,8 @@ a bit differently. @example @group -#include #include +#include #include const char *program_name; @@ -2226,13 +2228,18 @@ main (int argc, char *const *argv) recode_delete_request (request); recode_delete_outer (outer); - exit (success ? 0 : 1); + exit (success ? EXIT_SUCCESS : EXIT_FAILURE); @} @end group @end example +@cindex @code{recodext.h} header +Note that in the example above, @code{recodext.h} header is used instead +of @code{recode.h}. By doing so, the various structures are not opaque +anymore, and their fields may be accessed by name. + @vindex RECODE_TASK structure -The header file @code{} declares a @code{RECODE_TASK} +The header file @code{recode.h} declares a @code{RECODE_TASK} structure, which the programmer should use for allocating a variable in his program. This @code{task} variable is given as a first argument to all task level functions. The programmer ought to change and possibly @@ -2357,7 +2364,7 @@ situation immediately after a call to @code{recode_new_task}. This field, which is of type @code{enum recode_sequence_strategy}, tells how various recoding steps (passes) will be interconnected. Its initial value is @code{RECODE_STRATEGY_UNDECIDED}, which is a constant defined in -the header file @file{}. Other possible values are: +the header file @file{recodext.h}. Other possible values are: @table @code @item RECODE_SEQUENCE_IN_MEMORY -- 2.50.1