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 <stdbool.h>
#include <recode.h>
+ 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 <stdlib.h>
+ #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 <stdbool.h>
+ #else
+ typedef enum {false = 0, true = 1} bool;
+ #endif
+
+ #include <recode.h>
+
+ 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:
an example of a program which does not really make anything useful.
#include <stdbool.h>
+ #include <stdlib.h>
#include <recode.h>
const char *program_name;
RECODE_OUTER outer = recode_new_outer (RECODE_AUTO_ABORT_FLAG);
recode_delete_outer (outer);
- exit (0);
+ exit (EXIT_SUCCESS);
}
- The header file `<recode.h>' 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
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 `<recode.h>' header file uses the Boolean type setup by the
-system header file `<stdbool.h>'. 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 `<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.in' for being able to write something more general,
-like:
-
- #if STDC_HEADERS
- # include <stdlib.h>
- #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 <stdbool.h>
- #else
- typedef enum {false = 0, true = 1} bool;
- #endif
-
- #include <recode.h>
-
- 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);
of a program which sole job is to filter `ibmpc' code on its standard
input into `latin1' code on its standard output.
- #include <stdio.h>
#include <stdbool.h>
+ #include <stdio.h>
+ #include <stdlib.h>
#include <recode.h>
const char *program_name;
recode_delete_request (request);
recode_delete_outer (outer);
- exit (success ? 0 : 1);
+ exit (success ? EXIT_SUCCESS : EXIT_FAILURE);
}
- The header file `<recode.h>' 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.
the same goal as the one from the previous section, but does its things
a bit differently.
- #include <stdio.h>
#include <stdbool.h>
+ #include <stdlib.h>
#include <recodext.h>
const char *program_name;
recode_delete_request (request);
recode_delete_outer (outer);
- exit (success ? 0 : 1);
+ exit (success ? EXIT_SUCCESS : EXIT_FAILURE);
}
- 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.
+ 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
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 `<recodext.h>'. Other possible values are:
+ the header file `recodext.h'. Other possible values are:
`RECODE_SEQUENCE_IN_MEMORY'
Keep intermediate recodings in memory.
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
\0\b[index\0\b]
* 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)
* 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)
\1f
File: recode.info, Node: Charset and Surface Index, Prev: Library Index, Up: Top
Node: Emacs\7f58694
Node: Debugging\7f59728
Node: Library\7f63998
-Node: Outer level\7f65352
-Node: Request level\7f72226
-Node: Task level\7f83173
-Node: Charset level\7f93595
-Node: Errors\7f94437
-Ref: Errors-Footnote-1\7f99283
-Ref: Errors-Footnote-2\7f99397
-Node: Universal\7f99758
-Ref: Universal-Footnote-1\7f102870
-Ref: Universal-Footnote-2\7f102936
-Node: UCS-2\7f103149
-Node: UCS-4\7f105675
-Node: UTF-7\7f106215
-Node: UTF-8\7f106810
-Node: UTF-16\7f111115
-Node: count-characters\7f112263
-Node: dump-with-names\7f112934
-Node: iconv\7f115483
-Node: Tabular\7f118914
-Node: ASCII misc\7f141127
-Node: ASCII\7f141493
-Node: ISO 8859\7f142309
-Node: ASCII-BS\7f144603
-Node: flat\7f146440
-Node: IBM and MS\7f147111
-Node: EBCDIC\7f147655
-Node: IBM-PC\7f149751
-Ref: IBM-PC-Footnote-1\7f151865
-Node: Icon-QNX\7f152024
-Node: CDC\7f152449
-Node: Display Code\7f154130
-Ref: Display Code-Footnote-1\7f156411
-Node: CDC-NOS\7f156616
-Node: Bang-Bang\7f158578
-Node: Micros\7f160507
-Node: Apple-Mac\7f160890
-Node: AtariST\7f162924
-Node: Miscellaneous\7f163910
-Node: HTML\7f164829
-Node: LaTeX\7f170818
-Node: Texinfo\7f171592
-Node: Vietnamese\7f172364
-Node: African\7f173340
-Node: Others\7f174690
-Node: Java\7f176143
-Node: Texte\7f176810
-Ref: Texte-Footnote-1\7f181358
-Ref: Texte-Footnote-2\7f181438
-Ref: Texte-Footnote-3\7f181913
-Node: Mule\7f182010
-Ref: Mule-Footnote-1\7f183791
-Node: Surfaces\7f184310
-Ref: Surfaces-Footnote-1\7f187729
-Node: Permutations\7f187833
-Node: End lines\7f188674
-Node: MIME\7f190875
-Node: Dump\7f192062
-Node: Test\7f196232
-Node: Internals\7f198710
-Node: Main flow\7f199938
-Node: New charsets\7f203041
-Node: New surfaces\7f207579
-Node: Design\7f208305
-Ref: Design-Footnote-1\7f217471
-Node: Concept Index\7f217575
-Node: Option Index\7f232610
-Node: Library Index\7f235463
-Node: Charset and Surface Index\7f240038
+Node: Outer level\7f66958
+Node: Request level\7f72307
+Node: Task level\7f83299
+Node: Charset level\7f93929
+Node: Errors\7f94771
+Ref: Errors-Footnote-1\7f99617
+Ref: Errors-Footnote-2\7f99731
+Node: Universal\7f100092
+Ref: Universal-Footnote-1\7f103204
+Ref: Universal-Footnote-2\7f103270
+Node: UCS-2\7f103483
+Node: UCS-4\7f106009
+Node: UTF-7\7f106549
+Node: UTF-8\7f107144
+Node: UTF-16\7f111449
+Node: count-characters\7f112597
+Node: dump-with-names\7f113268
+Node: iconv\7f115817
+Node: Tabular\7f119248
+Node: ASCII misc\7f141461
+Node: ASCII\7f141827
+Node: ISO 8859\7f142643
+Node: ASCII-BS\7f144937
+Node: flat\7f146774
+Node: IBM and MS\7f147445
+Node: EBCDIC\7f147989
+Node: IBM-PC\7f150085
+Ref: IBM-PC-Footnote-1\7f152199
+Node: Icon-QNX\7f152358
+Node: CDC\7f152783
+Node: Display Code\7f154464
+Ref: Display Code-Footnote-1\7f156745
+Node: CDC-NOS\7f156950
+Node: Bang-Bang\7f158912
+Node: Micros\7f160841
+Node: Apple-Mac\7f161224
+Node: AtariST\7f163258
+Node: Miscellaneous\7f164244
+Node: HTML\7f165163
+Node: LaTeX\7f171152
+Node: Texinfo\7f171926
+Node: Vietnamese\7f172698
+Node: African\7f173674
+Node: Others\7f175024
+Node: Java\7f176477
+Node: Texte\7f177144
+Ref: Texte-Footnote-1\7f181692
+Ref: Texte-Footnote-2\7f181772
+Ref: Texte-Footnote-3\7f182247
+Node: Mule\7f182344
+Ref: Mule-Footnote-1\7f184125
+Node: Surfaces\7f184644
+Ref: Surfaces-Footnote-1\7f188063
+Node: Permutations\7f188167
+Node: End lines\7f189008
+Node: MIME\7f191209
+Node: Dump\7f192396
+Node: Test\7f196566
+Node: Internals\7f199044
+Node: Main flow\7f200272
+Node: New charsets\7f203375
+Node: New surfaces\7f207913
+Node: Design\7f208639
+Ref: Design-Footnote-1\7f217805
+Node: Concept Index\7f217909
+Node: Option Index\7f233382
+Node: Library Index\7f236235
+Node: Charset and Surface Index\7f240810
\1f
End Tag Table
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 <stdbool.h>
#include <recode.h>
+
+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 <stdlib.h>
+#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 <stdbool.h>
+#else
+typedef enum @{false = 0, true = 1@} bool;
+#endif
+
+#include <recode.h>
+
+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
@example
@group
#include <stdbool.h>
+#include <stdlib.h>
#include <recode.h>
const char *program_name;
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{<recode.h>} 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
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{<recode.h>} header file uses the Boolean type setup by the
-system header file @code{<stdbool.h>}. 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{<recode.h>} 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 <stdlib.h>
-#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 <stdbool.h>
-#else
-typedef enum @{false = 0, true = 1@} bool;
-#endif
-
-#include <recode.h>
-
-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
@example
@group
-#include <stdio.h>
#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
#include <recode.h>
const char *program_name;
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{<recode.h>} 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.
@example
@group
-#include <stdio.h>
#include <stdbool.h>
+#include <stdlib.h>
#include <recodext.h>
const char *program_name;
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{<recode.h>} 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
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{<recodext.h>}. Other possible values are:
+the header file @file{recodext.h}. Other possible values are:
@table @code
@item RECODE_SEQUENCE_IN_MEMORY
projects / recode / commitdiff