B. Incompatibilities with previous versions

texi2html has accumulated a lot of incompatibilities with previous versions. They are documented in the ‘NEWS’ file, we discuss them here nevertheless. Most of the incompatibilities were introduced in version 1.68. API changed also a lot between 1.78 and 1.80.

• API changes between 1.78 and 1.80:
  • what was done in the beginning of the $print_section function reference is now done in $print_element_header.
  • there is a new argument for $normal_text.
  • there is a new argument for $menu_link and $simple_menu_link, and the name argument is always set, even if there is no explicit name. The new argument is true if there really was an explicit name.
  • $internal_ref and $external_ref don’t change inforef to xref anymore.
  • in $table_item the text is not formatted with the format command, the text_formatted argument is.
  • definition index entries are now formatted with $definition_index_entry, not with $definition_category anymore.
  • $printindex is called if an index appears, even if the index is not defined or there are no index entries.
  • new argument (@-command name) for $quotation and $quotation_prepend_text.
  • change in the heading API. THIS_HEADER is not used anymore. New function reference, element_heading to format a node or a section heading, including navigation and label. Accordingly, print_Top and one_section don’t print the element header anymore. Also it is reported if the element is a new element, is the main element and more arguments, and top element heading is always done in heading.
  • print_element_header and print_navigation now return their result.
  • the copying key of %Texi2HTML::THISDOC is now called copying_comment.
  • TOC_LIST_ATTRIBUTE is now called NO_BULLET_LIST_ATTRIBUTE.
  • TOC_LIST_STYLE is now called NO_BULLET_LIST_STYLE.
  • the $unknown function reference has a new argument, the pass number.
  • ‘--sec-nav’ is replaced by ‘--headers’.
  • ‘--Verbose’ is replaced by ‘--verbose’.
  • ‘--lang’ is replaced by ‘--document-language’.
  • ‘--separated-footnotes’ is replaced by ‘--footnote-style’.
  • ‘--lang’ is replaced by ‘--document-language’.
  • &$menu_comment is removed, menu_comment is now handled like an @-command.
  • @detailmenu is now formatted more like @menu, and the &$menu function reference is replaced by &$menu_command. &$menu is kept for backward compatibility. If &$menu is defined, @detailmenu is ignored.
  • the API for the formatting of menus completly changed. $simple_menu_link is removed, everything should be done in $menu_link.
  • image API changed, and is unstable, so not documented.
  • image file paths are not completed anymore in the default case. The previous behaviour can be restored with $COMPLETE_IMAGE_PATHS set to true.
  • in %misc_command ‘texi’ is not used anymore. The value and macros are expanded as they should be unconditionnally.
  • there is a new ’style’ key in $complex_format_map, to be able to differentiate complex formats inheriting fonts and code_style (like @format, @display).
  • $EXTENSION should be undef if one doesn’t want an extension to be added.
  • THISDOC{’title’} and similar are now for @title since only one @title should appear in the document. @settitle is tried first to set fulltitle.
  • Configuration variables are modified anymore, instead the variable value is put in $Texi2HTML::THISDOC{’VAR’}. This is the case for DO_CONTENTS, DO_SCONTENTS, CSS_LINES, BODYTEXT, DOCUMENT_DESCRIPTION, DOCUMENT_ENCODING, IN_ENCODING, ENCODING_NAME, OUT_ENCODING.

    For example, if $CSS_LINES is defined, the value is put in $Texi2HTML::THISDOC{’CSS_LINES’} which is used for formatting, and if $CSS_LINES is not defined, $Texi2HTML::THISDOC{’CSS_LINES’} is autodetected.

  • When there is no section and $USE_NODES is not set don’t split by node. This behaviour and the previous aren’t documented, so it could change in the future.
• API changes between 1.76 and 1.78:
  • paragraph has new arguments with indentation information, added as the third argument, and other context information. The formatting linked with commands opened before the paragraph and closed after the paragraph are done in the formatting function. Similar things are done for preformatted.
  • normal_text changed completely. There are much more arguments to give informations about the context, and normal_text now does more text manipulation.
  • New arguments for image the alt text, the height and width, the path to working dir and the path to image file relative to working dir. More image formatting is done in the formatting function.
  • New argument for empty_line.
  • End of line removal is done in formatting function of definition line formatting.
  • node_file_name now should only returns the node file, since the redirection file isn’t used anymore. element_file_name only is used for file names, whatever NODES_FILES is.
• changes between 1.66 and 1.68:
  • When the manual is split the default is to put resulting files in a directory with name the manual file basename (previously they were left in the current directory). To avoid that, call texi2html with ‘-output .’. This has been changed to be compatible with makeinfo and also because it fits better with the cross manuals reference scheme.
  • The option ‘--output’ signification changed. It now has the same meaning than for makeinfo. It seems that in 1.66 it was the same than ‘-out-file’. ‘--output’ new meaning allows to replace ‘-out-file’ and ‘-subdir’ with a unique option.

    More precisely ‘-out-file’ forces the output to be unsplit while ‘--output’ behaves differently when split (it specifies the directory where the manual files should be outputted) and unsplit (it specifies the output file). ‘-subdir’ is retained for backward compatibility.

    If you want a backward compatibility you can use ‘-subdir’ for the output directory if the document is split, and ‘-out-file’ if the document isn’t split. This hasn’t been tested extensively though.

  • Many options has been obsoleted but they are retained for backward compatibility.
  • The init files are searched in new directories, however they are still searched for in the old directories for backward compatibility.
  • the option ‘--glossary’ doesn’t do anything. Likely nothing specific is done regarding bibliographies. This has been decided because this added some semantics to the texinfo formatting language that weren’t part of texinfo.

    It should be possible to do something similar with macros. See for example ‘glossary.texi’ for glossary and ‘my-bib-macros.texi’ for bibliography in the directory ‘examples’. In the web2c package there is an example of use of BibTeX, see http://tug.org/texlive/devsrc/Build/source/TeX/texk/web2c/doc/ (the examples for bibliography are taken from the texinfo home page http://www.gnu.org/software/texinfo/texinfo.html).

  • don’t use T2H_CENTER_IMAGE. @center should be used insead, it will give the right output for all the formats.
  • If a directory creation fails the program aborts. This is much safer.
  • The interface for internationalisation changed, although the previous wasn’t documented a lot.
  • the API described in this manual changed a lot. A important change was to use the Texi2HTML::Config names space instead of variables prefixed with ‘T2H_’ or ‘t2h_’. To cope with the change the prefix should be removed from variables in init files. Some variables are now in %Texi2HTML::THISDOC.
  • @ifinfo regions are not expanded by default. This may lead to warnings or errors especially if the Top node is enclosed in @ifinfo, as some node won’t appear in menus. The quick fix is to call texi2html with the option ‘--ifinfo’ and the right way should be to make more use of @ifnottex.
  • The code appearing before the first node is now outputted, it was ignored before. ‘--ignore-preamble-text’ revert to the previous behaviour. Enclosing in @ifnothtml would be much cleaner.

This document was generated by Derek Price on January 5, 2009 using texi2html 1.82.