"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/recode.texi" between
recode-3.7.11.tar.gz and recode-3.7.12.tar.gz

About: recode is a charset converter tool and library (fork of the original and now unmaintained GNU recode).

recode.texi  (recode-3.7.11):recode.texi  (recode-3.7.12)
skipping to change at line 653 skipping to change at line 653
@item @item
By default, without @samp{-f} nor @samp{-s}, Recode sets the exit By default, without @samp{-f} nor @samp{-s}, Recode sets the exit
status as above, and also in case of invalid or untranslatable input. status as above, and also in case of invalid or untranslatable input.
It also tries (but not always succeed) to detect if output is going to It also tries (but not always succeed) to detect if output is going to
be ambiguous at some later recode-back time. be ambiguous at some later recode-back time.
@item @item
The stricter setting is activated with @samp{-s}, Recode then sets the The stricter setting is activated with @samp{-s}, Recode then sets the
exit status as above, or if input is not canonically coded (and it also exit status as above, or if input is not canonically coded (and it also
prevents itself from *completing* recoding tables for making the prevents itself from @emph{completing} recoding tables for making the
recoding reversible). recoding reversible).
@end itemize @end itemize
@node Requests, Listings, Synopsis, Invoking recode @node Requests, Listings, Synopsis, Invoking recode
@section The @var{request} parameter @section The @var{request} parameter
In the case where the @var{request} is merely written as In the case where the @var{request} is merely written as
@var{before}..@var{after}, then @var{before} and @var{after} specify the @var{before}..@var{after}, then @var{before} and @var{after} specify the
start charset and the goal charset for the recoding. start charset and the goal charset for the recoding.
skipping to change at line 1800 skipping to change at line 1800
When this flag is set, the library later issues diagnostics itself, and When this flag is set, the library later issues diagnostics itself, and
aborts the calling program on errors. This is merely a convenience, aborts the calling program on errors. This is merely a convenience,
because if this flag was not given, the calling program should always because if this flag was not given, the calling program should always
take care of checking the return value of all other calls to the take care of checking the return value of all other calls to the
recoding library functions, and when any error is detected, issue a recoding library functions, and when any error is detected, issue a
diagnostic and abort processing itself. diagnostic and abort processing itself.
@item RECODE_NO_ICONV_FLAG @item RECODE_NO_ICONV_FLAG
When this flag is set, the library does not initialize nor use the When this flag is set, the library does not initialize or use the
external @code{iconv} library. This means that the charsets and aliases external @code{iconv} library. This means that the charsets and aliases
provided by the @code{iconv} external library and not by Recode provided by the @code{iconv} external library and not by Recode
itself are not available. itself are not available.
@item RECODE_STRICT_MAPPING_FLAG
When this flag is set (corresponding to the @samp{--strict} command-line
option), untranslatable characters are discarded, but an error is
returned on completion unless @samp{RECODE_FORCE_FLAG} is also set.
@item RECODE_FORCE_FLAG
When this flag is set (corresponding to the @samp{--force} command-line
option), errors caused by untranslatable characters are ignored.
@end table @end table
In previous incatations of the Recode library, @var{flags} In previous incarnations of the Recode library, @var{flags}
was a Boolean instead of a collection of flags, meant to set was a Boolean instead of a collection of flags, meant to set
@code{RECODE_AUTO_ABORT_FLAG}. This still works, but is deprecated. @code{RECODE_AUTO_ABORT_FLAG}. This still works, but is deprecated.
Regardless of the setting of @code{RECODE_AUTO_ABORT}, all recoding Regardless of the setting of @code{RECODE_AUTO_ABORT}, all recoding
library functions return a success status. Most functions are library functions return a success status. Most functions are
geared for returning @code{false} for an error, and @code{true} if geared for returning @code{false} for an error, and @code{true} if
everything went fine. Functions returning structures or strings return everything went fine. Functions returning structures or strings return
@code{NULL} instead of the result, when the result cannot be produced. @code{NULL} instead of the result, when the result cannot be produced.
If @var{RECODE_AUTO_ABORT} is selected, functions either return If @var{RECODE_AUTO_ABORT} is selected, functions either return
@code{true}, or do not return at all. @code{true}, or do not return at all.
skipping to change at line 1872 skipping to change at line 1883
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <recode.h> #include <recode.h>
const char *program_name; const char *program_name;
int int
main (int argc, char *const *argv) main (int argc, char *const *argv)
@{ @{
program_name = argv[0]; program_name = argv[0];
RECODE_OUTER outer = recode_new_outer (true); RECODE_OUTER outer = recode_new_outer (RECODE_AUTO_ABORT_FLAG);
RECODE_REQUEST request = recode_new_request (outer); RECODE_REQUEST request = recode_new_request (outer);
bool success; bool success;
recode_scan_request (request, "ibmpc..latin1"); recode_scan_request (request, "ibmpc..latin1");
success = recode_file_to_file (request, stdin, stdout); success = recode_file_to_file (request, stdin, stdout);
recode_delete_request (request); recode_delete_request (request);
recode_delete_outer (outer); recode_delete_outer (outer);
skipping to change at line 2147 skipping to change at line 2158
#include <stdbool.h> #include <stdbool.h>
#include <stdlib.h> #include <stdlib.h>
#include <recodext.h> #include <recodext.h>
const char *program_name; const char *program_name;
int int
main (int argc, char *const *argv) main (int argc, char *const *argv)
@{ @{
program_name = argv[0]; program_name = argv[0];
RECODE_OUTER outer = recode_new_outer (false); RECODE_OUTER outer = recode_new_outer (0);
RECODE_REQUEST request = recode_new_request (outer); RECODE_REQUEST request = recode_new_request (outer);
RECODE_TASK task; RECODE_TASK task;
bool success; bool success;
recode_scan_request (request, "ibmpc..latin1"); recode_scan_request (request, "ibmpc..latin1");
task = recode_new_task (request); task = recode_new_task (request);
task->input.name = ""; task->input.name = "";
task->output.name = ""; task->output.name = "";
success = recode_perform_task (task); success = recode_perform_task (task);
skipping to change at line 2947 skipping to change at line 2958
@cindex interface, with @code{iconv} library @cindex interface, with @code{iconv} library
@cindex Haible, Bruno @cindex Haible, Bruno
The Recode library is able to use the capabilities of an The Recode library is able to use the capabilities of an
external, pre-installed @code{iconv} library, usually as provided by GNU external, pre-installed @code{iconv} library, usually as provided by GNU
@code{libc} or the portable @code{libiconv} written by Bruno Haible. In @code{libc} or the portable @code{libiconv} written by Bruno Haible. In
fact, many capabilities of the Recode library are duplicated in fact, many capabilities of the Recode library are duplicated in
an external @code{iconv} library, as they likely share many charsets. an external @code{iconv} library, as they likely share many charsets.
We discuss, here, the issues related to this duplication, and other We discuss, here, the issues related to this duplication, and other
peculiarities specific to the @code{iconv} library. peculiarities specific to the @code{iconv} library.
The @code{iconv} library provides transliteration between character The @code{RECODE_STRICT_MAPPING_FLAG} option, corresponding to the
sets, using encodings with the suffix @code{-translit}. This @samp{--strict} flag, is implemented by adding @code{iconv} option
corresponds to the @code{iconv} option @code{//TRANSLIT}. @code{//IGNORE} to the @samp{after} encoding. This has the side effect
that untranslatable input is only signalled at the end of the
Similarly, the suffix @code{-ignore} tells @code{iconv} to ignore conversion, whereas with Recode's built-in conversion routines the error
invalid character sequences. This corresponds to the @code{iconv} will be signalled immediately.
option @code{//IGNORE}.
If the string @code{-translit} is appended to the @var{after} encoding,
The two suffixes can be combined using the suffix characters being converted are transliterated when needed and possible.
@code{-translit-ignore}; for example, @code{iso-8859-1-translit-ignore}. This means that when a character cannot be represented in the target
character set, it can be approximated through one or several similar
looking characters. Characters that are outside of the target character
set and cannot be transliterated are replaced with a question mark (?)
in the output. This corresponds to the @code{iconv} option
@code{//TRANSLIT}.
To check whether @code{iconv} is used for a particular conversion, To check whether @code{iconv} is used for a particular conversion,
just use the @samp{-v} or @samp{--verbose} option, @pxref{Recoding}, and just use the @samp{-v} or @samp{--verbose} option, @pxref{Recoding}, and
check whether @samp{:iconv:} appears as an intermediate charset. check whether @samp{:iconv:} appears as an intermediate charset.
@tindex iconv @tindex iconv
@anchor{prefer-iconv} @anchor{prefer-iconv}
The @code{:iconv:} charset represents a conceptual pivot charset within The @code{:iconv:} charset represents a conceptual pivot charset within
the external @code{iconv} library (in fact, this pivot exists, but is the external @code{iconv} library (in fact, this pivot exists, but is
skipping to change at line 4703 skipping to change at line 4719
also provide. also provide.
The first such function has the purpose of allocating structures, The first such function has the purpose of allocating structures,
pre-conditioning conversion tables, etc. It is also the way of further pre-conditioning conversion tables, etc. It is also the way of further
modifying the @code{STEP} structure. This function is executed if and modifying the @code{STEP} structure. This function is executed if and
only if the single step is retained in an actual recoding sequence. only if the single step is retained in an actual recoding sequence.
If you do not need such delayed initialisation, merely use @code{NULL} If you do not need such delayed initialisation, merely use @code{NULL}
for the function argument. for the function argument.
The second function executes the elementary recoding on a whole file. The second function executes the elementary recoding on a whole file.
There are a few cases when you can spare writing this function:
@c FIXME: functions file_one_to_one and file_one_to_many don't exist!
@itemize @bullet
@item
@findex file_one_to_one
Some single steps do nothing else than a pure copy of the input onto the
output, in this case, you can use the predefined function
@code{file_one_to_one}, while having a delayed initialisation for
presetting the @code{STEP} field @code{one_to_one} to the predefined
value @code{one_to_same}.
@item
Some single steps are driven by a table which recodes one character into
another; if the recoding does nothing else, you can use the predefined
function @code{file_one_to_one}, while having a delayed initialisation
for presetting the @code{STEP} field @code{one_to_one} with your table.
@item
@findex file_one_to_many
Some single steps are driven by a table which recodes one character into
a string; if the recoding does nothing else, you can use the predefined
function @code{file_one_to_many}, while having a delayed initialisation
for presetting the @code{STEP} field @code{one_to_many} with your table.
@end itemize
If you have a recoding table handy in a suitable format but do not use If you have a recoding table handy in a suitable format but do not use
one of the predefined recoding functions, it is still a good idea to use one of the predefined recoding functions, it is still a good idea to use
a delayed initialisation to save it anyway, because @code{recode} option a delayed initialisation to save it anyway, because @code{recode} option
@samp{-h} will take advantage of this information when available. @samp{-h} will take advantage of this information when available.
Finally, edit @file{Makefile.am} to add the source file name of your routines Finally, edit @file{Makefile.am} to add the source file name of your routines
to the @code{C_STEPS} or @code{L_STEPS} macro definition, depending on to the @code{C_STEPS} or @code{L_STEPS} macro definition, depending on
the fact your routines is written in C or in Flex. whether your routines are written in C or Flex.
@node New surfaces, Design, New charsets, Internals @node New surfaces, Design, New charsets, Internals
@section Adding new surfaces @section Adding new surfaces
@cindex adding new surfaces @cindex adding new surfaces
@cindex new surfaces, how to add @cindex new surfaces, how to add
Adding a new surface is technically quite similar to adding a new charset. Adding a new surface is technically quite similar to adding a new charset.
@xref{New charsets}. A surface is provided as a set of two transformations: @xref{New charsets}. A surface is provided as a set of two transformations:
one from the predefined special charset @code{data} to the one from the predefined special charset @code{data} to the
new surface, meant to apply the surface, the other from the new surface new surface, meant to apply the surface, the other from the new surface
 End of changes. 9 change blocks. 
41 lines changed or deleted 32 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)