| texinfo/tp/README |
| |
| Copyright 2011-2024 Free Software Foundation, Inc. |
| |
| Copying and distribution of this file, with or without modification, |
| are permitted in any medium without royalty provided the copyright |
| notice and this notice are preserved. |
| |
| texi2any is a Perl program for converting Texinfo input to to divers |
| output formats. Texinfo::Parser (hence the directory name tp) is a Perl |
| module for parsing Texinfo code into a tree representing the Texinfo |
| code structure. |
| |
| These other modules and libraries are required (all have been standard |
| parts of Perl for years, at least since 5.7.3): |
| Carp, Config, Data::Dumper, Encode, File::Basename, File::Spec |
| Getopt::Long, Unicode::Normalize, Storable |
| |
| Unicode::Collate (also a standard module since 5.7.3) is required for |
| correct index sorting. |
| |
| texi2any also uses the less widely-available modules: |
| Locale::Messages, Unicode::EastAsianWidth, Text::Unidecode |
| For these, internal versions are included, and are installed and used as |
| part of Texinfo (not disturbing the Perl installation at all) (although |
| see the output of 'configure --help' for how to use externally installed |
| modules). |
| |
| |
| Archive::Zip is needed for the EPUB output format final file creation. |
| It is not included in Texinfo; it is detected at runtime and an error is |
| issued if it cannot be loaded. |
| |
| |
| To run the tests you also need: |
| Test::More, Data::Compare, Test::Deep |
| On Debian-based distros, Test::More is part of perl-modules and thus |
| installed with perl, the packages corresponding to the other modules |
| are named: |
| libdata-compare-perl libtest-deep-perl |
| |
| The tests are in the subdirectories t/ and test/. The tests in t/ test |
| the Perl modules used by the makeinfo command, and the tests in test/ |
| test the command itself. |
| |
| |
| If you want to delve into making a new backend, the documentation in |
| tp/Texinfo/Convert/Converter.pm is a good starting point, as it |
| describes the existing backends and other places to look. To do a good |
| job, expect to spend a lot of time making it do the right thing with the |
| existing tests. |
| |
| The Texinfo parser builds a complicated parse tree. It can output a lot of |
| debug information about the tree, and what it's doing generally. For example, |
| these commands output the tree (in different forms): |
| makeinfo -c DUMP_TREE=1 -c TEXINFO_OUTPUT_FORMAT=parse document.texi |
| makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi |
| In addition (or instead) setting the DEBUG configuration variable will |
| dump more information about what it's doing. |
| |
| |
| Sometime the messages on syntax errors can be incomplete because of the |
| system used to set the paths. It is possible in that case to use something |
| along the following line to test the validity of one source file: |
| |
| perl -c -I '.' -I './maintain/lib/libintl-perl/lib/' -I './maintain/lib/Unicode-EastAsianWidth/lib/' -I './maintain/lib/Text-Unidecode/lib' Texinfo/Convert/HTML.pm |