7.1 Customizing Output File Names ¶

It is possible to specify the output file names with more control than merely the command line option --output (see Invoking texi2any in Texinfo). The PREFIX customization variable overrides the base name of the file given by @setfilename or the file name and should not contain any directory components. To alter intermediate directories, use the SUBDIR customization variable. Finally, the extension may also be overriden by the customization variable EXTENSION. This variable should be undef if no extension is to be added.

Furthermore, the customization variables TOP_FILE override the output file name for the top element.

Two function references registered with texinfo_register_file_id_setting_function enable further customization. The first, node_file_name is used to customize the nodes files names.

Function Reference: $node_file node_file_name ($converter, \%node_element, $file_name) ¶

$converter is a converter object. \%node_element is the Texinfo tree element corresponding to the @node. $file_name is the node file name that has been already set. The function should return the node file name ($node_file).

The other function reference, tree_unit_file_name, is used to customize the file names associated with each normal element unit (see Output Element Units).

Function Reference: ($file, $path) tree_unit_file_name ($converter, \%unit_element, $file_name, $file_path) ¶

$converter is a converter object. \%unit_element is the Texinfo element corresponding to the unit element. $file_name is the file name that has been already set. $file_path is the file path that has been already set. $file_path is ‘undef’ if the file is relative to the output directory, which is the case if the output is split. The function should return the file name for the unit element, $file, and the file path for the unit element, $path, which should be ‘undef’ if the file path is to be constructed by putting $file in the destination directory.

In the user defined functions, the information that a unit element is associated with @top or @node Top or more generally considered to be the Top element may be determined with

$converter->element_is_tree_unit_top(\%unit_element);

The information on tree elements may be interesting for those functions (see Texinfo Tree Elements in User Defined Functions). The extra key associated_section of a node element and associated_node of a sectioning command element may also be useful.

The file name associated to a sectioning command is set together with the target, and is described in the next section.