[Cin] Problems producing the manual

[Georgy Salnikov]

On Sun, 20 Feb 2022, Phyllis Smith via Cin wrote:

> In referring to BT 568, I believe I am using this version:
>
> > Latex2html version 2021.2 released:
> > https://github.com/latex2html/latex2html/releases/tag/v2021.2
> > It finally contains all the recent modifications necessary to translate
> > CGG manual with glossary, namerefs etc. features.

Exactly so! Do not even try to translate CGG manual if your version of
latex2html is less than 2021.2! A dozen of new features have been
implemented in latex2html especially to enable translation of various
constructs that appear in the CGG manual (listings.sty, nameref.sty,
nomencl.sty, documentclass memoir, additional parameters for aligning
figures, etc.) The process of adapting latex2html was finished only at the
version 2021.2.

Otherwise it is possible to install older latex2html from sources after
applying several important patches listed here:

http://nmr.nioch.nsc.ru/latex2html/

But even in this case it would be still better to install it from the latest
sources, not from some older ones.

Additional requirement: Perl must not be version 5.18. There is a bug in the
regex engine of perl-5.18 which influences latex2html. Perl-5.22 (and above)
are OK. Perl before 5.18 also OK.

> >> Fedora 35: Lots missing from the installation chapter in both PDF and
> >> HTML versions. This is because Fedora's latex2html (version 2020.2,
> >> 2020-07-01) stumbles over the $ in a listing, like 2>&1 . On Mint 20.2

In latex2html-2020.2 the support for the listings package was not yet
implemented. Could not work per definition!

> >> latex2html is version 2021 (2021-01-01).

In latex2html-2021 (before 2021.2) there is no support for the memoir
documentclass, and nameref not yet complete. The translation, although
possible, will not give the intended result.

> >> In addition, in translate_manual, I had to change -nouse_dvipng to
> >> -use_dvipng. otherwise it has big problems converting images (and
> >> texlive-pdfcrop is installed).

latex2html uses several additional tools (mainly from the netpbm package,
but also a special package from texlive which is used for cropping). These
tools are needed to generate images from that LaTeX constructions which
latex2html cannot interpret by itself.

latex2html uses somehow different algorithms (and different tools) to
generate these images depending on the options -use_dvipng/-nouse_dvipng,
and on the kind of the images (gif/png/svg). The result can look slightly
differently depending on the options. If the installation is incomplete, it
can happen that some combination of the options work, while another does
not. For example, if you have no working installation of the package 'gs'
(GhostScript == a free PostScript interpreter), then -nouse_dvipng cannot
work.

The particular problem related to images generation can be debugged.
Latex2html leaves the file images.tex in the resulting directory. One can
translate this file by pdflatex and inspect how it looks.

> > I am still making the manual on Fedora 32 with LaTeX2HTML Version 2021
> > (Released January 1, 2021).
> > See: https://www.cinelerra-gg.org/bugtracker/view.php?id=568

I think, it is not the stock latex2html-2021, it had applied a patch or two.

Many companies which produce commertial software containing platform
independent components, like manuals or even Java programs (in the form of
translated bytecode) do not retranslate their manuals or Java bytecode on
every supported platform. Instead, they produce bytecode on some convenient
platform and populate the result on the others.

I insist, there is no reason to recompile CGG manual on every imaginable
platform. It would be more reasonable to compile it somewhere (namely, where
it is complete and simply works) and use the result elsewhere. The CGG
context help system itself does not depend at all on the origin, where the
html manual was produced.

_______________________________________________________________________________

Georgy Salnikov
NMR Group
Novosibirsk Institute of Organic Chemistry
Lavrentjeva, 9, 630090 Novosibirsk, Russia
Phone   +7-383-3307864
Email   sge at nmr.nioch.nsc.ru
_______________________________________________________________________________