texinfo/doc/draft_api.texi

@node texi2any Output Customization
@chapter @command{texi2any} Output Customization

@cartouche
@quotation Warning
The information displayed here is likely to change in the future.
In particular, the functions and their behavior may change in any
Texinfo release. 
@end quotation
@end cartouche

This chapter describes how to customize aspects of the
@command{texi2any} HTML output.  Although some of the features here
can technically be used with other output formats, it's not especially
useful to do so, so we'll write the documentation as if HTML were the
target format.  Most of the customizations are only available for
HTML.

This part of the manual and the corresponding interfaces are being
stabilized, and the only parts described are those that should not
change in the future.  Many other aspects of the formatted HTML may
already be customized, but the interfaces will change and will be
documented as soon as they are stable.

The HTML converter takes a Texinfo Perl tree as input and transforms
it to HTML@.  The Texinfo Perl tree describes a Texinfo document in a
structured way which makes it easy to go through the tree and format
@@-commands and other containers.  The code that is used to go through
the tree cannot be customized, but the conversion of tree elements can
be fully customized.  The tree structure and the customization of
Texinfo Perl tree elements will be described in future versions of the
manual.

@menu
* Loading Init Files::               Finding and writing initialization files.
* Init File Basics::                 What init files can contain and do.
@end menu


@node Loading Init Files
@section Loading Initialization Files and Search Paths

@cindex Loading init files
@cindex Initialization files, loading
@cindex Search paths, for initialization files

@pindex Config @r{init files loaded}

You can write so-called @dfn{initialization files}, or @dfn{init
files} for short, to modify almost every aspect of output formatting.
The program loads init files named @file{Config} each time it is run.
Those files are looked for in the following directories:

@table @file
@item @var{datadir}/texi2any/
(where @var{datadir} is the system data directory specified at
compile-time, e.g., @file{/usr/local/share})

@item @var{sysconfdir}/texi2any/
(likewise specified at compile time, e.g., @file{/usr/local/etc})

@item ~/.texi2any/
(where @code{~} is the current user's home directory)

@item ./.texi2any/
(under the current directory)

@item ./
(the current directory)
@end table

All @file{Config} files found are loaded, in the above order.  Thus,
@file{./Config} can override entries in, say,
@file{/usr/local/share/makeinfo/Config}.

@opindex --init-file
However, the most common way to load an initialization file is with
the @option{--init-file} option, explicitly specifying the file to be
loaded.  By default the following directories are searched, in the
following order.
@c  where @var{prog} is the name of the program invoked
@c on the command line (@command{makeinfo}, @command{texi2any}, etc.).
Only the first file found is used:

@enumerate
@item The current directory @file{./};

@item @file{./.texi2any/} under the current directory;

@item @file{~/.texi2any/}
where @code{~} is the current user's home directory;

@item @file{@var{sysconfdir}/texi2any/}
where @var{sysconfdir} is the system configuration directory
specified at compile-time, e.g., @file{/usr/local/etc};

@item @file{@var{datadir}/texi2any/}
Where @var{datadir} is the system data directory likewise specified at
compile time, e.g., @file{/usr/local/share};

@item @file{./.texinfo/init/} under the current directory;

@item @file{~/.texinfo/init/} under the current home directory;

@item @file{@var{sysconfdir}/texinfo/init/} with @var{sysconfdir} as above;

@item @file{@var{datadir}/texinfo/init/} with @var{datadir} as above.
@end enumerate

Additional directories may be prepended to the list with the
@option{--conf-dir} option (@pxref{Invoking texi2any}).


@node Init File Basics
@section Init File Basics

@cindex Init file basics
@cindex Perl, language for init files

Init files are written in Perl, and by convention have extension
@file{.init} or @file{.pm}.  
@c Several init files are included in the Texinfo
@c distribution (some are crucial components of the program), and can
@c serve as a good model for writing your own. 
@c  Smaller examples include @file{utf8.pm},
@c @file{html32.pm}, and plenty more.

@menu
* Init File Namespaces:: @code{Texinfo::Config}.
* Setting and Getting Customization Variables::
* Internationalization of Strings::
@end menu
@c * Init File Expansion Contexts::     Normal, preformatted, string, math.


@node Init File Namespaces
@subsection Init File Namespaces

@cindex Init file namespaces
@cindex Namespaces, for init files
@cindex Perl namespaces, for init files

@c when colons are supported ... vindex Texinfo::Config @r{namespace}
Initialization file are loaded from the main program via an
@code{require} call in the @code{Texinfo::Config} namespace.  This
means that the namespace of the main program and the namespace of
initialization files are distinct, which minimizes the chance of a
name clash.  

@node Setting and Getting Customization Variables
@subsection Setting and Getting Customization Variables

@cindex Customization variables, setting and getting

The basic operations on customization variables are to set and
retrieve their values.

To set the value of a customization variable from an initialization
file, you should use @code{set_from_init_file}:

@defun set_from_init_file ($variable_name, $variable_value)
@var{$variable_name} is a string containing the name of the variable
you want to set, and @var{$variable_value} is the value to which you
want to set it.  @var{$variable_value} may be @samp{undef}.
@end defun

For example,

@example
set_from_init_file('documentlanguage', 'fr');
@end example

@noindent overrides the @code{@@documentlanguage} from the
document.  It would be overridden by @option{--document-language} on
the command line.

Another example:

@example
set_from_init_file('SPLIT', 'chapter');
@end example

@noindent overrides the default splitting of the document.  It would be
overridden by @option{--split} on the command line.

A final example:

@example
set_from_init_file('NO_CSS', 1);
@end example

@noindent overrides the default value for @code{NO_CSS}.  It would be
overridden by @code{--set-customization-variable NO_CSS=1} on the command line.

To get the value of a variable, the function is @code{get_conf}:

@defun get_conf ($variable_name)
@var{$variable_name} is the name of the variable; its value (possibly
@code{undef}) is returned.
@end defun

For example:

@example
if (get_conf('footnotestyle') eq 'separate') @{ ... @}
@end example

For the customization variables associated with @@-commands, see
@ref{Customization Variables for @@-Commands}.  For the customization
variables associated with command line options, see @ref{Customization
Variables and Options}.


 @ignore
@c The following is still true, but right now nothing uses these contexts
@c in init files.
@c 
@c @node Init File Expansion Contexts
@c @subsection Init File Expansion Contexts: Normal, Preformatted, String, Math
@c 
@c @cindex Init file expansion contexts
@c @cindex Expansion contexts, for init files
@c @cindex Contexts for expansion in init files
@c 
@c There are four expansion contexts of interest:
@c 
@c @table @emph 
@c @item normal context
@c @cindex Normal expansion context
@c Paragraphs, index entries, tables, @enddots{}
@c 
@c @item preformatted context
@c @cindex Preformatted expansion context
@c When spaces between words are kept.  For example, within the
@c @code{@@display} (@pxref{display,, @code{@@display}}) and
@c @code{@@example} environments (@pxref{example,, @code{@@example}}), and
@c in menu comments.  The preformatted regions
@c are usually rendered using @code{<pre>} elements in HTML.
@c 
@c @c oldapi (@pxref{Menu formatting})
@c 
@c @item string context
@c @cindex String expansion context
@c When rendering strings without formatting elements, for example in
@c comments (@pxref{Comments}) and titles.  In the string context, there
@c is limited formatting, typically without any element when producing HTML,
@c so the value can be used in an attribute.
@c 
@c @item math context
@c @cindex Math expansion context
@c Math (@pxref{math,, @code{@@math}}).
@c 
@c @end table
@end ignore


@node Internationalization of Strings Function
@subsection Internationalization of Strings in the Output Document Function

@vindex texinfo_document @r{Gettext domain}
The subroutine @code{gdt} is used for translated strings:

@defun gdt (\%converter, $string, \%variables_hash)
@var{$string} is the string to be translated, @var{\%variables_hash}
is a hash reference holding the variable parts of the translated
string, and @var{\%converter} is an object which holds the informations
about the context.  The result returned is a perl Texinfo tree.
@end defun

When the string is expanded as Texinfo, and converted to a
Texinfo tree in perl, the arguments are substituted; for 
example, @samp{@{arg_name@}} is replaced by the corresponding 
actual argument, which should be Texinfo perl trees or Texinfo 
perl tree contents arrays.

In the following example, @samp{@{date@}}, @samp{@{program_homepage@}}
and @samp{@{program@}} are the arguments of the string.  Since they
are used in @code{@@uref}, their order is not predictable.
@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are 
substituted after the expansion, which means that they should already be
Texinfo perl trees or Texinfo perl tree contents:

@example
gdt('Generated on @@emph@{@{date@}@} using
     @@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.',
    @{
     'date' => expand_today(\%converter),
     'program_homepage' 
         => @{'text' => $Texi2HTML::THISDOC@{'program_homepage'@}@},
     'program' 
         => @{'text' => $Texi2HTML::THISDOC@{'program_and_version'@}@} @},
   );
@end example