where the
@flushright command is and to
for the
paragraphs within the @flushright.
Class names *- with a Texinfo @-command name were
reserved for uses related to @-command . For example
classes like summary-letter-printindex, cp-entries-printindex or
cp-letters-header-printindex for the different parts of the @printindex
formatting.
def- and -def are used for classes related to @def*, in general without
the specific command name used.
For the classes not associated with @-commands, the names were selected to
correspond to the role in the document rather than to the formatting style.
In HTML, some @-commands do not have an element with a class associated, or the
association is not perfect. There is @author in @quotation, @-command affected
by @definfoenclose. @pxref and similar @-commands have no class for references
to external nodes, and don't have the 'See ' in the element for references to
internal nodes. In general, it is because gdt() is used instead of direct
HTML.
Notes on protection of punctuation in nodes (done)
==================================================
This is implemented, in tp/Texinfo/Transformations.pm in _new_node for
Texinfo generation, and in Info with INFO_SPECIAL_CHARS_QUOTE. *[nN]ote
is not protected, though, but it is not clear it would be right to do.
There is a warning with @strong{note...}.
Automatic generation of node names from section names. To be protected:
* in every case
( at the beginning
* In @node line
commas
* In menu entry
* if there is a label
tab comma dot
* if there is no label
:
* In @ref
commas
In Info
in cross-references. First : is searched. if followed by a : the node
name is found and there is no label. When parsing a node a filename
with ( is searched for. Nested parentheses are taken into account.
Nodes:
* in every case
( at the beginning
* in Node line
commas
* In menu entry and *Note
* if there is a label
tab comma dot
* if there is no label
:
Labels in Info (not index entries, in index entries the last : not in
a uoted node should be used to determine the end of the
index entry).
:
* at the beginning of a line in a @menu
*note more or less everywhere
Interrogations and remarks
==========================
Should more Converter ignore the last new line (with type
last_raw_newline) of a raw block format?
There is no forward looking code anymore, so maybe a lex/yacc parser
could be used for the main loop. More simply, a binary tokenizer, at
least, could make for a notable speedup.
def/end_of_lines_protected_in_footnote.pl the footnote is
(1) -- category: deffn_name arguments arg2 more args with end of line
and not
(1)
-- category: deffn_name arguments arg2 more args with end of line
It happens this way because the paragraph starts right after the footnote
number.
in HTML, the argument of a quotation is ignored if the quotation is empty,
as in
@quotation thing
@end quotation
Is it really a bug?
In @copying things like some raw formats may be expanded. However it is
not clear that it should be the same than in the main converter. Maybe a
specific list of formats could be passed to Convert::Text::convert, which
would be different (for example Info and Plaintext even if converting HTML).
This requires a test, to begin with.
In HTML, HEADERS is used. But not in other modules, especially not in
Plaintext.pm or Info.pm, this is determined by the module used (Plaintext.pm
or Info.pm). No idea whether it is right or wrong.
From vincent Belaïche. About svg image files in HTML:
I don't think that supporting svg would be easy: its seems that to embed an
svg picture you need to declare the width x height of the frame in
which you embed it, and this information cannot be derived quite
straightforwardly from the picture.
With @image you can declare width and height but this is intended for
scaling. I am not sure whether or not that these arguments can be used
for the purpose of defining that frame...
What I did in 5x5 is that coded the height of the frame directly in
the macro @FIGURE with which I embed the figure, without going through
an argument.
The @FIGURE @macro is, for html:
@macro FIGURE {F,W}
@html
@end html
@end macro
Use of specialized synopsis in DocBook is not a priority and it is not even
obvious that it is interesting to do so. The following notes explain the
possibilities and issues extensively.
Instead of synopsis it might seem to be relevant to use specialized synopsis,
funcsynopsis/funcprototype for deftype* and some def*, and other for object
oriented. There are many issues such that this possibility do not appear
appealing at all.
1) there is no possibility to have a category. So the category must be
added somewhere as a role= or in the *synopsisinfo, or this should only
be used for specialized @def, like @defun.
2) @defmethod and @deftypemethod cannot really be mapped to methodsynopsis
as the class name is not associated with the method as in Texinfo, but
instead the method should be in a class in docbook.
3) From the docbook reference for funcsynopsis
"For the most part, the processing application is expected to
generate all of the parentheses, semicolons, commas, and so on
required in the rendered synopsis. The exception to this rule is
that the spacing and other punctuation inside a parameter that is a
pointer to a function must be provided in the source markup."
So this mean it is language specific (C, as said in the docbook doc)
and one have to remove the parentheses, semicolons, commas.
See also the mails from Per Bothner bug-texinfo, Sun, 22 Jul 2012 01:45:54.
specialized @def, without a need for category:
@defun and @deftypefun
TYPE NAMEargs
specialized @def, without a need for category, but without DocBook synopsis
because of missing class:
@defmethod, @deftypemethod: methodsynopsis cannot be used since the class
is not available
@defivar and @deftypeivar: fieldsynopsis cannot be used since the class
is not available
Generic @def with a need for a category
For deffn deftypefn (and defmac?, defspec?), the possibilities of
funcsynopsis, with a category added could be used:
TYPE NAMEPARAMTYPE PARAM
Alternatively, use funcsynopsisinfo for the category.
Generic @def with a need for a category, but without DocBook synopsis because
of missing class:
@defop and @deftypeop: methodsynopsis cannot be used since the class
is not available
defcv, deftypecv: fieldsynopsis cannot be used since the class
is not available
Remaining @def without DocBook synopsis because there is no equivalent,
and requires a category
defvr (defvar, defopt), deftypevr (deftypevar)
deftp
Misc notes
==========
Test validity of Texinfo XML or docbook
export XML_CATALOG_FILES=~/src/texinfo/tp/maintain/catalog.xml
xmllint --nonet --noout --valid commands.xml
tidy -qe *.html
profiling: package on debian:
libdevel-nytprof-perl
In doc:
perl -d:NYTProf ../tp/texi2any.pl texinfo.texi
nytprofhtml
# firefox nytprof/index.html
Test with 8bit locale:
export LANG=fr_FR; export LANGUAGE=fr_FR; export LC_ALL=fr_FR
xterm &
Turkish locale, interesting as ASCII upper-case letter I can become
a (non-ASCII) dotless i when lower casing. (Eli recommendation).
export LANG=tr_TR.UTF-8; export LANGUAGE=tr_TR.UTF-8; export LC_ALL=tr_TR.UTF-8
convert to pdf from docbook
xsltproc -o intermediate-fo-file.fo /usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl texinfo.xml
fop -r -pdf texinfo-dbk.pdf -fo intermediate-fo-file.fo
dblatex -o texinfo-dblatex.pdf texinfo.xml
Open a specific info file in Emacs Info reader: C-u C-h i
In tp/tests/, generate Texinfo file for Texinfo TeX coverage
../texi2any.pl --force --error=100000 -c TEXINFO_OUTPUT_FORMAT=plaintexinfo -D valid layout/formatting.texi > formatting_valid.texi
From doc/
texi2pdf -I ../tp/tests/layout/ ../tp/tests/formatting_valid.texi
mkdir -p val_res
for file in t/*.t ; do bfile=`basename $file .t`; echo $bfile; valgrind -q perl -w $file > val_res/$bfile.out 2>&1 ; done
For tests in tp/tests, a way to have valgrind -q prependend is to add, in tp/defs:
prepended_command='valgrind -q'
rm -rf t/check_debug_differences/
mkdir t/check_debug_differences/
for file in t/*.t ; do bfile=`basename $file .t`; perl -w $file -d 1 2>t/check_debug_differences/XS_$bfile.err ; done
export TEXINFO_XS_PARSER=0
for file in t/*.t ; do bfile=`basename $file .t`; perl -w $file -d 1 2>t/check_debug_differences/PL_$bfile.err ; done
for file in t/*.t ; do bfile=`basename $file .t`; diff -u t/check_debug_differences/PL_$bfile.err t/check_debug_differences/XS_$bfile.err > t/check_debug_differences/debug_$bfile.diff; done
firefox opens tex_encodé_utf8_html/Chapter.html but does not find the image
and shows a path like tex_encodé_utf8_html/tex_encodé_utf8_tex4ht_tex0x.png
mixing latin1 and utf8.
Tests in utf8 locales
---------------------
The archive epub file is not tested in the automated tests.
epub for utf8 encoded manual in utf8 locale
./texi2any.pl --force -I tests/ --init ext/epub3.pm tests/formatting/osé_utf8.texi
The following tests require latin1 encoded file names. Note that it
could be done automatically now with
tp/maintain/copy_change_file_name_encoding.pl.
However, there is already a test with an include file in latin1, it
is enough.
./texi2any.pl tex_encod*_latin1.texi
The following tests not important enough to have regression test
./texi2any.pl --force -I tests/ -o encodé/raw.txt -c TEXINFO_OUTPUT_FORMAT=rawtext tests/formatting/os*_utf8.texi
./texi2any.pl --force -I tests/ -c TEXINFO_OUTPUT_FORMAT=rawtext -c 'SUBDIR=subdîr' tests/formatting/os*_utf8.texi
Test more interesting in non utf8 locale
./texi2any.pl --set TEXINFO_OUTPUT_FORMAT=debugtree --set USE_NODES=0 -o résultat/encodé.txt ./t/input_files/simplest_no_node_section.texi
résultat/encodé.txt file name encoded in utf8
./texi2any.pl --set TEXINFO_OUTPUT_FORMAT=debugtree --set USE_NODES=0 -o char_latin1_latin1_in_refs_tree.txt ./t/input_files/char_latin1_latin1_in_refs.texi
char_latin1_latin1_in_refs_tree.txt content encoded in latin1
Notes on classes names in HTML
==============================
In january 2022 the classes in HTML elements were normalized. There are no
rules, but here is descriptions of the choices made at that time in case one
want to use the same conventions. The objective was to have the link between
@-commands and classes easy to understand, avoid ambiguities, and have ways to
style most of the output.
The class names without hyphen were only used for @-commands, with one
class attribute on an element maximum for each @-command appearing in the
Texinfo source. It was also attempted to have such a class for all
the @-commands with an effect on output, though the coverage was not perfect,
sometime it is not easy to select an element that would correspond to the
most logical association with the @-command (case of @*ref @-commands with
both a and a for example).
Class names