branch master updated: Remove doc/draft_api.texi merged in doc/customization_api.texi

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new c91ec2fe5e Remove doc/draft_api.texi merged in 
doc/customization_api.texi
c91ec2fe5e is described below

commit c91ec2fe5ed15eface28465f8ddca079bd4b2d23
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Fri Feb 4 00:19:48 2022 +0100

    Remove doc/draft_api.texi merged in doc/customization_api.texi
---
 doc/draft_api.texi | 295 -----------------------------------------------------
 1 file changed, 295 deletions(-)

diff --git a/doc/draft_api.texi b/doc/draft_api.texi
deleted file mode 100644
index e55b91aa85..0000000000
--- a/doc/draft_api.texi
+++ /dev/null
@@ -1,295 +0,0 @@
-
-@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
-