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 |
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 |