7.3.1 Encoding File Path Strings ¶

In general, the strings in the customization functions are character strings. For most purposes, this is right, and the encoding in output files is taken care of by the converter. Operations on directories and file names, however, such as the creation of a directory or the opening of a file require binary strings.

To encode file names consistently with file name encoding used in the conversion to HTML, there is a function encoded_output_file_name:

Function: ($encoded_name, $encoding) = $converter->encoded_output_file_name ($character_string_name) ¶

Encode $character_string_name in the same way as other file name are encoded in the converter. Use OUTPUT_FILE_NAME_ENCODING value for the file name encoding if set. Otherwise, if DOC_ENCODING_FOR_OUTPUT_FILE_NAME is set the input Texinfo document encoding is used, if unset, the default, files names are encoded using the current locale (see Global Customization Variables in Texinfo). Return the encoded name and the encoding used to encode the name.

There is also a similar function for the input file names encoding, encoded_input_file_name, which uses INPUT_FILE_NAME_ENCODING and DOC_ENCODING_FOR_INPUT_FILE_NAME and is less likely to be useful.

When calling external commands, the command line arguments should also be encoded. To do similarly with other codes, the customization variable MESSAGE_ENCODING should be used. Already encoded file names may be used. For example

use Encode qw(encode);

....

my ($encoded_file_path, $encoding)
  = $converter->encoded_output_file_name($file_name);

my $fh = open($encoded_file_path);

.....

my $call_start = "command --set '$action' ";
my $encoding = $converter->get_conf('MESSAGE_ENCODING');
if (defined($encoding)) {
  $encoded_call_start = encode($encoding, $call_start);
} else {
  $encoded_call_start = $call_start;
}
my $encoded_call = $encoded_call_start . $encoded_file_path;
my $call = $call_start . $file_name;
if (system($encoded_call)) {
 $converter->document_error($converter,
     sprintf(__("command did not succeed: %s"),
            $call));
}