/[texi2html]/texi2html/doc/texi2html.texi
ViewVC logotype

Diff of /texi2html/doc/texi2html.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.34 by pertusus, Tue Aug 9 17:19:27 2005 UTC revision 1.35 by pertusus, Fri Aug 19 12:14:46 2005 UTC
# Line 222  version of the manual which contains the Line 222  version of the manual which contains the
222  * Customizing HTML::          Fine tuning of the @acronym{HTML} elements  * Customizing HTML::          Fine tuning of the @acronym{HTML} elements
223                                associated with the texinfo constructs                                associated with the texinfo constructs
224  * Internationalization::      Help translating!  * Internationalization::      Help translating!
225    * Incompatibilities::         Incompatibilities with previous versions
226    * Specificities::             The minor differences with regard with texinfo
227                                  valid for makeinfo or texi2dvi
228  * Indexop::                   Command Line Option Index  * Indexop::                   Command Line Option Index
229  * Indexvr::                   Variable Index  * Indexvr::                   Variable Index
230  * Indexcp::                   Concept Index  * Indexcp::                   Concept Index
# Line 3536  All these steps may be performed by @com Line 3539  All these steps may be performed by @com
3539  is added to @file{Makefile.am}.  is added to @file{Makefile.am}.
3540    
3541  @c --------------------------------------------------------  @c --------------------------------------------------------
3542    @node Incompatibilities
3543    @chapter Incompatibilities with previous versions
3544    
3545    @command{texi2html} has accumulated a lot of incompatibilities with previous
3546    versions. They are documented in the @file{NEWS} file, we discuss them
3547    here nevertheless. most of the incompatibilities were introduced in
3548    version 1.68.
3549    
3550    @itemize @bullet
3551    @item When the manual is split the default is to put resulting files in
3552    a directory with name the manual file basename (previously they were left in
3553     the current directory). To avoid that, call texi2html with
3554    @option{-output .}. This has been changed to be compatible with
3555    @command{makeinfo} and also because it fits better with the cross
3556    manuals reference scheme.
3557    @item The option @option{--output} signification changed. It now
3558    has the same meaning than for @command{makeinfo}. It seems
3559    that in 1.66 it was the same than @option{-out-file}.
3560    @option{--output} new meaning allows to replace @option{-out-file} and
3561    @option{-subdir} with a unique option.
3562    
3563    More precisely @option{-out-file} forces the output to be unsplit
3564    while @option{--output} behaves differently when split (it specify
3565    the directory
3566    where the manual files should be outputted) and unsplit (it specify
3567    the output file). @option{-subdir} is retained for backward compatibility.
3568    
3569    If you want a backward compatibility you can use @option{-subdir}
3570    for the output directory if the document is split, and @option{-out-file}
3571    if the document isn't split. This hasn't been tested extensively though.
3572    @item Many options has been obsoleted but they are retained for
3573    backward compatibility.
3574    @item The init files are searched in new directories, however they
3575    are still searched for in the old directories for backward
3576    compatibility.
3577    @item the option @option{--glossary} doesn't do anything. Likely
3578    nothing specific is done regarding bibliographies. This has been
3579    decided because this added some semantics to the texinfo formatting
3580    language that weren't part of texinfo.
3581    
3582    It should be possible to do
3583    something similar with macros. See for example @file{glossary.texi}
3584    for glossary and @file{my-bib-macros.texi} for bibliography
3585    in the directory @file{examples}. In the web2c package there is
3586    an example of use of BibTeX, see @url{http://tug.org/texlive/devsrc/Build/source/TeX/texk/web2c/doc/} (the examples for bibliography are taken from the
3587    texinfo home page @url{http://www.gnu.org/software/texinfo/texinfo.html}).
3588    @item don't use @code{T2H_CENTER_IMAGE}. @code{@@center} should be used
3589    insead, it will give the right output for all the formats.
3590    @item If a directory creation fails the program aborts. This is much safer.
3591    @item The interface for internationalisation changed, although
3592    the previous wasn't documented a lot.
3593    @item the API described in this manual changed a lot. A important
3594    change was to use the @code{Texi2HTML::Config} names space instead of
3595    variables prefixed with @samp{T2H_} or  @samp{t2h_}. To cope with
3596    the change the prefix should be removed from variables in init files.
3597    Some variables are now in @code{%Texi2HTML::THISDOC}.
3598    @item @code{@@ifinfo} regions are not expanded by default. This may lead
3599    to warnings or errors especially if the Top node is enclosed in
3600    @code{@@ifinfo}, as some node won't appear in menus. The quick fix
3601    is to call @command{texi2html} with the option @option{--ifinfo} and
3602    the right way should be to make more use of @code{@@ifnottex}.
3603    @item The code appearing before the first node is now outputted, it was
3604    ignored before. @option{--ignore-preamble-text} revert to the previous
3605    behaviour. Enclosing in @code{@@ifnothtml} would be much cleaner.
3606    @end itemize
3607    
3608    @c --------------------------------------------------------
3609    @node Specificities
3610    @chapter How little texi2html texinfo differs from GNU texinfo
3611    
3612    For features documented in the texinfo manual, the texinfo interpretation
3613    by @command{texi2html} shouldn't differ from the interpretation of
3614    @command{makeinfo} or @command{texi2dvi}. However for constructs with
3615    unspecified behaviour @command{texi2html} often doesn't lead to the
3616    same result than @command{makeinfo} or @command{texi2dvi}. @command{makeinfo}
3617    and @command{texi2dvi} are also inconsistent in most of these cases (or
3618    broken). You are urged not to use these features unless absolutely necessary.
3619    This information is only here to help understand why @command{texi2html}
3620    differ from other texinfo interpreters, it may be inacurate and the
3621    @command{texi2html} behaviour may change in the future and was different
3622    in the past.
3623    
3624    @table @asis
3625    @item @@-commands with text on the line
3626    In the texinfo manual it is specified that block @@-commands should appear
3627    on a line without text and the closing @code{@@end} should also be on a
3628    line by himself. With @command{texi2html} it is possible to add
3629    text before and after the command, so the following is right:
3630    
3631    @example
3632    something @@example the example @@end example after the example
3633    @end example
3634    
3635    @command{makeinfo} and @command{texi2dvi} may also accept text before
3636    the command and text after the @code{@@end} command, sometimes ignoring
3637    it after the @code{@@end}.
3638    
3639    This is a feature you should especially not rely on.
3640    
3641    @item special @@-commands handling
3642    The special @@-commands are commands like @code{@@pagesizes}, @code{@@sp},
3643    @code{@@evenheading}, @code{@@raisesections}, @code{@@defindex} and a lot
3644    more. In many cases @command{makeinfo} and @code{texi2dvi}
3645    don't parse those commands the same way too. @command{texi2html} may also
3646    show some differences in parsing of the arguments of these commands,
3647    in case there are wrong arguments, and also ignore differently things
3648    following those commands. How user defined macros, set and values
3649    are expanded in those commands may also be different.
3650    Part of the specification of how these commands are handled is
3651    configureable (@pxref{Other and unknown commands}), but not what
3652    happens during the beginning of the parsing for some of those commands.
3653    
3654    @item features different between @command{makeinfo} and @command{texi2dvi}
3655    When @command{makeinfo} or @command{texi2dvi} use a feature which
3656    is reserved for one or the other translator, @command{texi2html} uses that
3657    feature. So for example @code{@@definfoenclose} which is ignored by
3658    @command{texi2dvi} is taken into account and @code{@@kbdinputstyle} which
3659    is ignored by @command{makeinfo} is taken into account.
3660    
3661    @item user defined macros and values
3662    In this area @command{makeinfo} and @command{texi2dvi} also differ a lot.
3663    The reference implementation is the @command{makeinfo} implementation as
3664    @command{texi2dvi} is easily broken when macros are not used simply.
3665    
3666    @itemize @bullet
3667    @item @code{@@rmacro} and @code{@@macro} behave exactly the same. In fact
3668    this goes against a documented behaviour, however if a user don't
3669    want a recursive macro he can simply avoid reusing the macro in the
3670    definition. If somebody report that the feature is usefull we could try
3671    to implement it.
3672    @item It is possible to escape the end of a macro definition with
3673    @example
3674    \@@end macro
3675    @end example
3676    with the @samp{\} being removed after the first expansion. Otherwise
3677    it is not possible to produce a @code{\@@end macro} in a macro.
3678    @item @code{@@unmacro} is interpreted during the macro argument expansion.
3679    Don't know what @command{makeinfo} exactly do.
3680    @item Some @code{@@value} may be expanded later than the others, those
3681    that are in special commands, like @code{@@node}.
3682    @end itemize
3683    
3684    @item @code{@@,} in @code{@@node}
3685    Like @command{texi2dvi} but unlike @command{makeinfo} @code{@@,} don't
3686    break @code{@@node} arguments like a regular @samp{,}.
3687    @item Things before first node or preamble
3688    Things before the first node or before the preamble may not be exactly
3689    interpreted or discarded as @command{makeinfo} or @command{texi2dvi} do.
3690    @item encodings
3691    @command{texi2html} knows more encodings, in fact all encodings @command{perl}
3692    knows about.
3693    @item commands in @code{@@ifset} and @code{@@ifclear}
3694    @command{texi2html} doesn't need a proper nesting of internal @code{@@ifset}
3695    or @code{@@ifclear} if they are in ignored or raw regions (like @code{@@html}
3696    or @code{@@verbatim}). For example the following is accepted by
3697    @command{texi2html} and not by @command{makeinfo}:
3698    
3699    @example
3700    @@ifset notset
3701    @@ignore
3702    @@ifset
3703    @@end ignore
3704    @@end ifset
3705    @end example
3706    
3707    In @code{@@ifset} and @code{@@ifclear} texi2html also accepts
3708    a lot more of invalid constructs. For example the following is accepted
3709    by @command{texi2html} but not by @command{makeinfo}:
3710    
3711    @example
3712    @@set flag
3713    @@ifset flag
3714    @@itemize
3715    @@item my item
3716    @@end ifset
3717    text
3718    @@ifset flag
3719    @@end itemize
3720    @@end ifset
3721    @end example
3722    @end table
3723    
3724    @c --------------------------------------------------------
3725  @c commandline option index.  @c commandline option index.
3726  @node Indexop  @node Indexop
3727  @appendix Command Line Option Index  @appendix Command Line Option Index

Legend:
Removed from v.1.34  
changed lines
  Added in v.1.35

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26