Re: Struggling with a targeted [Contents] button

[Patrice Dumas]

On Fri, Sep 13, 2024 at 06:56:22PM +0200, Rudolf Adamkovič wrote:
> Hi,
> 
> [I have been fighting the problem below for 3+ hours.]
> 
> In my HTML export, I would like to have
> 
>   a navigation button that links the current node in TOC,
> 
> the way
> 
>   texinfo_set_from_init_file('TOC_LINKS', 'true');
> 
> does.
> 
> So far, I have the following:
> 
>   sub _my_experiment_button {
>   my ($self, $direction) = @_;
> 
>   # I SHOULD PROBABLY PASS IN SOME "COMMAND" ?!
>   my $href = $self->command_contents_href(1, 'contents');
>   
>   return ("Contents", 1);
>   }
>   
>   my $experiment_button = ['This', \&_my_experiment_button];
>   my $section_buttons = [ ...  ..., $experiment_button];
>   
>   texinfo_set_from_init_file('SECTION_BUTTONS', $section_buttons);
>   texinfo_set_from_init_file('SECTION_FOOTER_BUTTONS', $section_buttons);
> 
> The resulting [Contents] button
> 
>   links to the TOC file --- YAY! ---
> 
> but the link
> 
>   is missing the '#toc-...' anchor.
> 
> Any help would be *deeply* appreciated.

As you notice, you should pass a Texinfo tree command element.
Conveniently, this is the next argument of the button formatting
function.  However, I tested it and it is not enough if the element
passed to the button formatting function is a node element, in addition,
the associated sectionning command has to be found, which requires
knowing more about the Texinfo tree.  The extra keys are documented in
https://www.gnu.org/software/texinfo/manual/texi2any_internals/texi2any_internals.html#Texinfo_003a_003aParser-Extra-keys-specific-of-certain-_0040_002dcommands-or-containers

Here is what worked for me:

  sub _my_experiment_button {
  my ($self, $direction, $element) = @_;

  if ($element->{'extra'}->{'associated_section'}) {
$element = $element->{'extra'}->{'associated_section'};
  }

  my $href = $self->command_contents_href($element, 'contents');

  return ("Contents", 1);
  }



As a side note, what you do is a good idea.  Maybe I'll add it to the
book.pm example.

-- 
Pat

Re: Navigation panels in "separate element" TOCs

[Patrice Dumas]

On Fri, Sep 13, 2024 at 04:39:30PM +0200, Rudolf Adamkovič wrote:
> Howdy!
> 
> Notice how the top and bottom
> 
>   navigation panels are not useful,
> 
> as the user is looking at their target.
> 
> Thus, I have two questions:
> 
>   - Why is this the default behavior?

That's because it is the result of the regular elements buttons output
when there are no Up/Next/Prev directions.  I agree that a [Top] would
be much more helpful ([Top] is used with the texi2html style).

>   - How can I replace [Contents] with [Top]? (*)

You can specify

texinfo_set_from_init_file('MISC_BUTTONS', ['Top', 'Index', 'About']);

However, I think that it is not an issue if the Contents button is there
for contents, as MISC_BUTTONS could be used for other separate elements,
such as footnotes.

In any case, I think that I will replace the Up button that is never
present for separate special elements by the [Top] button in the default
case, thanks for the report.

-- 
Pat

Re: texinfo 7.1.1 fails to compile with gcc 14 mingw toolchain

[Patrice Dumas]

On Tue, Sep 10, 2024 at 06:50:35PM +0300, Eli Zaretskii wrote:
> > Yes, this code appears never actually to have been tested on the platform
> > this code was for.
> 
> That's not true.  My MinGW port of Texinfo includes a fully functional
> Info reader.  It's simply that Patris made changes in that area
> recently, and since then I didn't have time to build a port and fix
> this, that's all.

It was Gavin patch, not mine.  Mine was correct for this function ;-).

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Thu, Sep 05, 2024 at 04:35:06PM +0200, Rudolf Adamkovič wrote:
> Patrice Dumas  writes:
> 
> That said, I wonder, would it be a good idea to center displayed
> mathematics by default?  Doing so is customary.

I agree, and it is also what is done in Texinfo TeX.

>  I tried to add
> 
>   
> .displaymath {
>   display: flex;
>   justify-content: center;
> }
>   
> 
> to my `EXTRA_HEAD', and it looks good.  In fact, it looks better even
> with MathJax, where newly rendered content "seemingly replaces" the
> original LaTeX code, as both are shown in the same spot.

I tried something more simple with text-align, but the result is bad.  I
do not feel at ease with that kind of complex CSS, but I guess that if
the browser do not support, they should still show something ok, so I'll
apply.

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Thu, Sep 05, 2024 at 04:11:03PM +0200, Rudolf Adamkovič wrote:
> Patrice Dumas  writes:
> 
> Further, MathJax is now loaded and runs only if the page actually
> contains math, which makes a difference.

I think that it should already have been the case prevously.

> However, as I cleaned up my "HTML build pipeline" today, I noticed that
> I still need to run one last fragile hack:
> 
>   find . \
> -type f \
> -name '*.html' \
> -exec sed \
>   -i '' 's/id="MathJax-script" async/id="MathJax-script"/g' {} \;
> 
> This is because Texinfo loads MathJax asynchronously, and that is it.
> If the user wants to load it synchronously, say to avoid the initial
> flicker when running locally, the user is out of luck.
> 
> I wonder, could we also introduce MATHJAX_ASYNCHRONOUS, set to true by
> default?  With that, the user will, at last, have full control over
> MathJax in Texinfo HTML exports.

The sed seems enough to me, especially for something that is more
relevant locally, we already have too many customization variables.

> P.S. The `INSTALL.generic' file opens with
> 
>   Basic Installation
>   ==
>   
>  The following shell commands:
>   
>test -f configure || ./bootstrap
>./configure
>make
>make install
> 
> but there is no `boostrap' file.  I eventually figured out what to do,
> but it added unnecessary friction.  As a person with "fresh eyes", I
> figured I should let you know about the problem.

Indeed, if I understood well, for texinfo, it should be

  test -f configure || ./autogen.sh

However, this file is not under our control, so I am not sure what we
could do.  Gavin, and idea?

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Tue, Sep 03, 2024 at 07:28:17AM +0100, Gavin Smith wrote:
> 
> You've convinced me.  I think we should change it for @displaymath but
> not for inline @math as the line breaks there are not meaningful.

Should be done:
https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=47b9e91e02d17359a9ce209901ab674b5b3814f4

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Tue, Sep 03, 2024 at 01:44:33AM +0200, Rudolf Adamkovič wrote:
> Patrice Dumas  writes:
> 
> > What would you have expected?  My feeling is that adding a
> > MATHJAX_CONFIGURATION variable with default:
> >   options: {
> > skipHtmlTags: {'[-]': ['pre']},
> > ignoreHtmlClass: 'tex2jax_ignore',
> > processHtmlClass: 'tex2jax_process'
> >   }, 
> > set if MATHJAX_CONFIGURATION is undef could work.  Do you have another
> > proposition?
> 
> That would be helpful.  It would allow me, for example, to load the
> physics extension, which is something I need.

Here it is:
https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=edc041b0aa896ecdf03b7951224e850041a3bed1

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Tue, Sep 03, 2024 at 04:39:55PM +0100, Gavin Smith wrote:
> On Tue, Sep 03, 2024 at 10:55:33AM +0200, Patrice Dumas wrote:
> > Should we add a possibility to get back to  with a customization
> > option?
> 
> I don't know.  Couldn't someone make a  behave pretty much like
> a  using CSS?  I doubt it is worth having a customization option
> for this.

That's what we will do, in any case, it was more for backward
compatibility, but maybe just documenting the change is enough, we
already have too many customization variables.

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Tue, Sep 03, 2024 at 07:28:17AM +0100, Gavin Smith wrote:
> 
> You've convinced me.  I think we should change it for @displaymath but
> not for inline @math as the line breaks there are not meaningful.

Agreed.  I also got convinced that the gain for text browser is
important enough and we can add CSS for the other cases to avoid
monospaced font and add emphasis.

> There is the minor issue that the display width of the browser may not
> match that used for the TeX code but I expect this would rarely matter.

And it is up to the browser to make it look good in that case.

Should we add a possibility to get back to  with a customization
option?

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Tue, Sep 03, 2024 at 01:44:33AM +0200, Rudolf Adamkovič wrote:
> Patrice Dumas  writes:
> 
> I think using  makes perfect sense semantically.  LaTeX is source
> code, just like SVG is.  It just happens that MathJax may (or may not)
> render it (soon enough).  What is more, it is often beneficial to read
> LaTeX code as formatted by its author, not re-formatted, which makes it
> doubly-important to use .  Virtually nobody presents SVG or LaTeX
> code, for un-rendered consumption, that is as source code, on a single
> line in a proportional fonts.  Are these good arguments?

First, a minor point, even though the point that TeX code could be
considered as code and not directly as math makes some sense, it is
quite different from SVG in term of readability, in general even though
TeX math is code in a way, it is much better in term of readability and
in some case as good as it can be compared to 'ascii' math (for somewhat
complex math).

More importantly, this misses the point that in Texinfo the @displaymath
or @math may not be LaTeX (nor TeX).  We strongly recommend using TeX
math code such that it renders correctly when processed by Texinfo TeX,
but semantically it is math, not code.  

So, I still do not think that considering TeX as output by Texinfo is
semantically code is the best.  A  that contains math is better
from a semantic point of view.  That being said, in HTML, math is almost
always TeX code, so, the presentation of math is TeX code, such that we
want to present TeX code as well as possible, and we can consider that
for that,  has the merit to keep end of lines as they are in the
original TeX for text based browsers.  If we do that, we will need to
use CSS to remove momospaced font and add emphasis, though, such that
the presentaiton is correct in graphical browsers.

> By the same line of reasoning, inline mathematics should use ,
> because well, it literally is "code" that has not been rendered yet.

I do not think that it would be a good idea, the @math TeX is, in
general, quite readable, and is presented inline anyway, so there is no
gain in term of presentation by using  and it is semantically
inferior to emphasizing, in my opinion.

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Fri, Aug 30, 2024 at 10:32:26AM +0200, Rudolf Adamkovič wrote:
> Patrice Dumas  writes:
> 
> Another point of friction was MathJax, namely its *hard-coded*
> configuration.  I ended up pointing `MATHJAX_SCRIPT' to a dummy file,
> and then configuring and loading MathJax myself in `EXTRA_HEAD'.

What would you have expected?  My feeling is that adding a
MATHJAX_CONFIGURATION variable with default:
  options: {
skipHtmlTags: {'[-]': ['pre']},
ignoreHtmlClass: 'tex2jax_ignore',
processHtmlClass: 'tex2jax_process'
  }, 
set if MATHJAX_CONFIGURATION is undef could work.  Do you have another
proposition?

> Speaking of MathJax, Texinfo puts each `displaymath' inside a `div' and
> `em', so with no-JavaScript browsers, and text readers, such fragments
> become LaTeX code with *no line breaks*, which makes them hard to read.
> Perhaps Texinfo could put displayed mathematics into some HTML element
> that preserves line breaks?

For no-JavaScript browsers with CSS support, a possibility could be to
add CSS with --css-include, with something like:

  div.displaymath {white-space: pre;}

(I tested with Firefox with and without JavaScript).  If you want to
propose something like that as the default, I think that it should be
discussed on the bug-texinfo list.

Even if the output could be better in text browsers (which, in general,
do not support CSS, so the above CSS use is not possible), my view is that
using a  is better from both a formatting and a semantic point of
view than using .  I could change my mind, but that would require
some good arguments.  Also, currently this would break MathJax, as pre
is excluded from MathJax elements, and this would probably require using
some CSS to avoid the monospaced font.

To me, if you really want a  for displaymath, the best is to
redefine the displaymath conversion command function.  It happens to be
a relatively small and simple default function.

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Thu, Aug 29, 2024 at 12:27:26AM +0200, Rudolf Adamkovič wrote:
> Patrice Dumas  writes:
> 
> It took me additional couple of hours to figure out:
> 
>   my $node_direction = 'Node'.$direction;

I am surprised that it using the node up NodeUp direction instead of the
section up Up direction changes the href.  I haven't tested, but unless
there are nodes without associated sections, it should be the same.

> This is definitely the longest it took me to add a button! :)
> 
> [One afternoon before I asked, and then one after that.]

Maybe better documentation could help, right now it may be too sparse.
That being said, some difficulties are inherent, as coding using a
peculiar API is needed, which necessarily requires time to understand.

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Mon, Aug 26, 2024 at 03:09:08PM +0200, Rudolf Adamkovič wrote:
> Hi there!
> 
> I would like to have a Texinfo navigation bar as follows:
> 
> Up: PARENT-SECTION   [Top] [Contents]
> 
> To get it, I wrote the following `texi2any-config.pm' file:
> 
> package Texinfo::Config;
> 
> texinfo_set_from_init_file(
> SECTION_BUTTONS,
> [['Up', 'section'], ' ', 'Top', 'Contents']);

As a side note, a button specification like ['Up', 'section'] is not
documented anymore and should not be used starting in 7.2.  This is
because it is unlikely to be useful with the default navigation panel
list and could even be confusing.  The code will stay as is until we
find something better to do with this case.  An example of something
better, though maybe too complicated could be ['Up', 'Up: {section}'].

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Wed, Aug 28, 2024 at 10:13:25AM +0200, Patrice Dumas wrote:
> Then you can select some directions only:
> texinfo_set_from_init_file(
>  'SECTION_BUTTONS',
>   ['Up', \&_my_button_direction_section_href],
>   #['Next', \&_my_button_direction_section_href], 
>   #['Prev', \&_my_button_direction_section_href], 
>   'Top', 'Contents']);

Sorry, this part should have been

texinfo_set_from_init_file(
 'SECTION_BUTTONS',
  [['Up', \&_my_button_direction_section_href],
  #['Next', \&_my_button_direction_section_href], 
  #['Prev', \&_my_button_direction_section_href], 
  'Top', 'Contents']);

-- 
Pat

Re: How to add "Up:" to Texinfo navigation bar?

[Patrice Dumas]

On Mon, Aug 26, 2024 at 03:09:08PM +0200, Rudolf Adamkovič wrote:
> Hi there!
> 
> I would like to have a Texinfo navigation bar as follows:
> 
> Up: PARENT-SECTION   [Top] [Contents]

Only with Up, or with Next and Prev too, using section names?

If you want to have section names instead of nodes in navigation bar,
you can already use:
@xrefautomaticsectiontitle on

> I tried to add `[\'Up:', ...]' but that results in:
> 
> Up:, PARENT-SECTION   [Top][Contents]
> 
> /Note the comma./

Indeed, a comma is added before most 'buttons' except for the first
(exceptions are space and a button formatted as [direction]).  I
realized that the documentation is wrong, it says that the delimiter is
printed after the button, while it is actually printed before the button
unless it is the first button, I will fix that shortly in the
development version.

You can use a function reference to put the PARENT-SECTION without
preceding comma. This also allows to have the a good output if
there is no associated section.  For Up it is not actually possible, but
if you want to do the same with Prev and Next, you'll always have the
Prev: and Next: even if there is no associated direction.  To format a
whole button with leading text, I think that there is no other way than 
defining a function, like:

sub _my_button_direction_section_href {
  my ($self, $direction, $source_command) = @_;

  my $href = $self->from_element_direction($direction, 'href',
   undef, undef, $source_command);
  my $section = $self->from_element_direction($direction, 'section');
  $section = '' if (!defined($section));

  my $link;
  if (defined($href) and $href ne '') {
$link = "$section";
  } elsif ($section ne '') {
$link = $section;
  } else {
return (undef, 0);
  }
  # here you can use something else than $direction for the leading text
  return ("$direction: $link", 1);
}

Then you can select some directions only:
texinfo_set_from_init_file(
 'SECTION_BUTTONS',
  ['Up', \&_my_button_direction_section_href],
  #['Next', \&_my_button_direction_section_href], 
  #['Prev', \&_my_button_direction_section_href], 
  'Top', 'Contents']);

-- 
Pat

Re: Math and the Emacs info viewer

[Patrice Dumas]

On Thu, Aug 01, 2024 at 02:52:44PM +0200, Rahguzar wrote:
> Patrice Dumas  writes:
> 
> I think this is fairly straightforward to do using the latex standalone
> class and then converting the produced document to an image using dvipng,
> pdftoppm or dvisvgm. This approach is used by Emacs's sage integration
> to display typeset output and I think other preview packages in Emacs
> use it too. I think dvisvgm is the better route since those images can
> scale better but high resolution bitmap images are also good enough.

Seems like LaTeX preview package + dvipng should probably be the best.
In Info we support only png and jpg.  Added to the TODO.

-- 
Pat

Re: Math and the Emacs info viewer

[Patrice Dumas]

On Wed, Jul 31, 2024 at 02:24:55PM +0100, Gavin Smith wrote:
> The first method, outputting the math as an image in Info as is already
> possible, would require the image to be generated.  texi2any can already
> generate images for @math/@displaymath in HTML output using either latex2html
> or tex4ht (accessed with the HTML_MATH customization variable).  I expect
> it would be straightforward to do something similar with Info output.

That could be doable, but not straightforward as the latex2html or
tex4ht output is HTML, which is included in texi2any generated HTML.  I
do not know if it is possible to do images systematically.  Another
issue is that (maybe) there could be more that one image for a math or
displaymath.  If there was some software that do images and not HTML
based on latex/tex it could be easier.

-- 
Pat

Re: No title in HTML output

[Patrice Dumas]

On Sun, Jun 02, 2024 at 07:09:50AM +, Jean-Christophe Helary wrote:
> Ok. I'm using Texinfo 7.1 from brew (macOS) and with the same file and 
> same command I get "Previous", "Up", "Top" and "Footnotes".
> 
> I guess there is a bug in the installation process.
> 
> How can I check where does texinfo take its FR strings from?

It is not easy to check at runtime, as the gettext framework does not allow to 
get
information on the directories actually searched for.

It is possible to check if there is a file in the directory that is
expected to be used. In texinfo-7.1, the explicit call to
Locale::Messages::bindtextdomain relevant for an installed package and
for translated strings in document is in texi2any 

 Locale::Messages::bindtextdomain($strings_textdomain,
File::Spec->catdir($datadir, 'locale'));

$datadir is set before, in the normal case, it should be set by
configure, you should be able to see, a code like (line 166)

if ('/usr/share' ne '@' . 'datadir@' and 'texinfo' ne '@' . 'PACKAGE@') {
  $datadir = eval '"/usr/share"';
  my $package = 'texinfo';
  $pkgdatadir = File::Spec->catdir($datadir, $package);
} else {

Ther locales file should be like
$datadir/locale/fr/LC_MESSAGES/texinfo_document.mo

-- 
Pat

Re: No title in HTML output

[Patrice Dumas]

On Sat, Jun 01, 2024 at 11:53:57PM +, Jean-Christophe Helary wrote:
> 
> 
> Now, I have footnotes and they appear after a "Footnotes" title even 
> though I have:
> 
> @documentlanguage fr_FR
> @documentencoding utf-8
> 
> in my headings.
> 
> Is there a way to fix that?

This should just work.  I tried with the attached manual with texinfo
7.1 (and the development version too) on a debian testing, and I get
"Notes de bas de page".  I called
 texi2any --html -c NO_TOP_NODE_OUTPUT=1 ex_fr.texi

One possibility could be a mismatch between the strings found and the
strings expected in texi2any as there were recent changes, with contexts
added for many translations and in particular all the special elements
headings.  Normally texi2any tries to use the translations strings from
were the texinfo package is installed, but I guess that the (Perl)
gettext framework could also use another location.

-- 
Pat


ex_fr.texi
Description: TeXInfo document

Re: No title in HTML output

[Patrice Dumas]

On Sat, Jun 01, 2024 at 03:53:36AM +, Jean-Christophe Helary wrote:
> I'm wondering why the following texinfo tags do not produce visible output in 
> HTML:
> 
> @settitle
> @copying
> @titlepage
> 
> I can see that the info is buried in  tags with the @settitle contents 
> appearing inside , but it seems to me that such information, 
> especially since Texinfo is designed for manuals, should be prominently 
> displayed as  and as a small paragraph below it.

For copying, if the corresponding text is to be output, @insertcopying
should be used.

For @settitle and @titlepage, in the default case they are indeed not
visible on the first page, with the rationale that for an online format
such as HTML, it is best to directly find the output, "By default the
HTML output is tailored for online viewing with a direct access to the
information at the Top node." (quoting from the development version
manual).

There is, however, some customization variables to get a title in HTML.
First, you can set NO_TOP_NODE_OUTPUT to remove the Top node, if this
what you want, it should add a title based on @titlepage or @settitle.
Second, you can set SHOW_TITLE to get a title with the Top node output.

For example

texi2any --html -c NO_TOP_NODE_OUTPUT=1 mymanual.texi


As a side note, in the upcoming version Texinfo manual, these
customizations should be much better described.

-- 
Pat

Re: texinfo: warning: @anchor should not appear on @item line

[Patrice Dumas]

On Mon, Mar 18, 2024 at 08:41:08PM +0100, Georg-Johann Lay wrote:
> > Well, I would say that it is borderline.  I do not like that it
> > is ok in @table and not in @vtable for instance, the constructs correct
> > in both should be the same.
> > 
> > Even if it not exactly the same and probably does not gives you the
> > exact expected output, I think that the following would be a more
> > expected construct:
> > 
> > @table @code
> > 
> > @item label1
> > @anchor{label1}
> > Text1
> > 
> > @end table
> 
> But this gives an ugly result.  When clicking on "labelX" (and there is
> much text prior to it) then the browser screen will look like
> 
> label1
> 
>   Text1
> 
> i.e. label1 is not visible. What I want is
> 
> 
> 
> label1
>   Text1

I do not deny that, I understand perfectly that the output you want to
generate is with the hyperlink at the beginning of the @item line.  But
the solution to do that is not very consistent with the kind of Texinfo
code that would be expected.

Maybe a tree transformation that associates anchors following an @item
to the @item could be another possibility, but it is not very attractive
either.

-- 
Pat

Re: texinfo: warning: @anchor should not appear on @item line

[Patrice Dumas]

On Mon, Mar 18, 2024 at 07:30:40PM +0100, Georg-Johann Lay wrote:
> 
> 
> > In my tests it seems so.  If a @vtable is used instead of a @table and
> > a printindex is used too, there are two  generated for the anchor,
> > but it does not seems to me to problematic.  More problematic is that
> > there is no visible link to the index entry generated in the @printindex
> > formatting, which could be investigated.
> 
> Hi Patrice,
> 
> thanks for the swift answer.  In my specific case it is only about
> @table @code.  If I understand you correctly, then this was a glitch
> in texinfo, and not that @anchor and @item are fundamentally
> incompatible.  That's good to hear.

Well, I would say that it is borderline.  I do not like that it
is ok in @table and not in @vtable for instance, the constructs correct
in both should be the same.

Even if it not exactly the same and probably does not gives you the
exact expected output, I think that the following would be a more
expected construct:

@table @code

@item label1
@anchor{label1}
Text1

@end table

-- 
Pat

Re: texinfo: warning: @anchor should not appear on @item line

[Patrice Dumas]

On Mon, Mar 18, 2024 at 07:13:42PM +0100, Patrice Dumas wrote:
> 
> In my tests it seems so.  If a @vtable is used instead of a @table and
> a printindex is used too, there are two  generated for the anchor,
> but it does not seems to me to problematic.  More problematic is that
> there is no visible link to the index entry generated in the @printindex 
> formatting, which could be investigated.

Actually, it is because nested  are not valid, and the way the
browser reorganizes the HTML have the  closed early and no more
hyperref.  My feeling is that we should not try to fix that kind of
situations more.  Maybe we could put in the manual that an anchor in an
index entry, be it a @*index or @vtable/@ftable @item is not a good
idea.

-- 
Pat

Re: texinfo: warning: @anchor should not appear on @item line

[Patrice Dumas]

On Mon, Mar 18, 2024 at 01:24:23PM +0100, Georg-Johann Lay wrote:
> In a texi file, I have a table where each item should get an anchor:
> 
> @table @code
> 
> @item @anchor{label1}label1
> Text1
> 
> @item @anchor{label2}label2
> Text2
> 
> @end table
> 
> What's the proper way to set an anchor for an item?
> The item should not be out-of-screen when following a generated link.
> 
> As for the texinfo version; I don't have control over that because I am
> not the owner of the project; I am just adding (small parts of) the
> documentation.
> 
> I fount thread
> https://lists.nongnu.org/archive/html/help-texinfo/2023-11/msg4.html
> 
> so is that warning problem already fixed in recent revisions?

In my tests it seems so.  If a @vtable is used instead of a @table and
a printindex is used too, there are two  generated for the anchor,
but it does not seems to me to problematic.  More problematic is that
there is no visible link to the index entry generated in the @printindex 
formatting, which could be investigated.

-- 
Pat

Re: HTML node names: Not emitting 'Top (Manual name)'

[Patrice Dumas]

On Thu, Mar 14, 2024 at 10:34:00PM +0100, Arsen Arsenović wrote:
> > By all means, if changing the page title for the Top node causes
> > significant problems, we can avoid making this change.  But it is
> > hard to imagine why it would cause a problem.
> >
> > I don't mind avoiding this time for the time being, if it is felt
> > there has been a lot of change to the HTML output recently.  Once
> > things settle down, we could revisit this.
> 
> This could be a customization variable or such in the meanwhile too.

I do not think that it is probelmatic to change if it is better.  I
think that the Top () conveys some information, although not very much,
both would be ok for me.  It is easier to explain what is done if we
keep the Top, though.

As for adding a customization variable, I do not think that such a
variation in formatting is worth a customization variable, however
something that could be considered is a customization variable for the
HTML title of the Top/first file in a split manual.

-- 
Pat

Re: HTML node names: Not emitting 'Top (Manual name)'

[Patrice Dumas]

On Fri, Mar 15, 2024 at 09:22:54AM +0200, Eli Zaretskii wrote:
> I'm not sure the HTML output of texi2any is (or can be) specifically
> tailored to the needs of presenting a project's manuals on the GNU
> Software Web site (https://www.gnu.org/software/).  For example, every
> manual is generated in 2 forms: a single HTML file and one file per
> node; texi2any does support each of these outputs, but the
> requirements from the heading lines and preambles for each one are
> slightly different, when the above site is targeted.

The HTML output of texi2any can be tailored extensively, and I do not
see the fact that there is a split and non-split manual a difficulty for
customization.  There vould be a different init file for each of those
cases.  There could also be conditionals based on the SPLIT value, which
would require some knowledge of perl, but some very basic knowledge.

-- 
Pat

Re: HTML node names: Not emitting 'Top (Manual name)'

[Patrice Dumas]

On Sat, Mar 16, 2024 at 09:55:59AM +0200, Eli Zaretskii wrote:
> Since there's so much material about customizations in the Texinfo
> manual, I never paid any attention to the texi2any_api manual (which
> is mentioned in the Texinfo manual exactly once, in a place where one
> rarely looks).
> 
> Looking at that manual now, it is mainly intended for Perl
> programmers, AFAIU.

Not necessarily, some simple customization can be done with almost no
knowledge of Perl.  Many possibilities for customization require a good
knowledge of Perl, though (starting with chapter 6).

>  Where the effects can be achieved via
> customization variables, it basically refers back to the Texinfo
> manual.

It depends on the section, in some sections the customization variables
are well described (for example the section on contents, if I recall
well), in other there is only a reference back to the
Texinfo manual.

> What I was looking for is some kind of combination, in a single
> manual, where one could find both the general background and
> description of the conversion process (as texi2any_api does), and
> description of the customizations via variables in the context of that
> description of the conversion process.  Customization by writing Perl
> function should be considered a whole different level of
> customizations, which I believe very few will go to, especially given
> the large number of variables which presumably should already allow to
> do a lot, and should therefore be described in separate subsections.

Ok.  The organization of documentation of customization variables in the
Texinfo document seems to me a relevant topic for discussion.  I'll
start a new thread on bug-texinfo on that specific subject.

> I indeed note that the first thing the texi2any_api manual says is
> this:
> 
>  Warning: All of this information, with the exception of
>  command-line options and search directories associated with command
>  line options (*note Loading Init Files::), may become obsolete in a
>  future Texinfo release.  Right now, the "API" described in this
>  chapter is immature, so we must keep open the possibility of
>  incompatible, possibly major, changes.  Of course we try to avoid
>  incompatible changes, but it is not a promise.
> 
> If still true, this doesn't encourage one, to say the least, to build
> serious tailoring on the facilities described in this manual.

It is true, the API has not been used that much for now, so it requires
a bit of time to be considered as stable.  The last of the API was added
in 2022-10-29 and it has been changed importantly since then, in
particular for the translation of HTML conversion to C.  Going forward
it should be more stable, but I think that it needs to be used a bit to
be sure that it is really ok as it is.  The Lilypond manual is now using
a relevant part of the API, so let's hope that it can become stable
soon.

> I hope the plight of a GNU maintainer who needs to tailor or customize
> the HTML form of the manual, for whatever reasons, is now evident, as
> are the reasons I don't much like the idea of non-trivial changes in
> the HTML output in future Texinfo releases.  I also hope that making
> these customization facilities more stable and better documented will
> be an important goal of the future Texinfo development, given the
> hoops through which we otherwise need to jump to get our job done.

It has been an important goal for a very long time.  This was one of the
reason why Karl pushed for texi2html to replace makeinfo in C in 2010.
In texi2html the inclusion of some kind of customization cannot be dated
with certainty, but dates from before 2000 according to my understanding
of the very first ChangeLog entry.  Progress may be slow, but it has
been an important goal for a long time.

-- 
Pat

Re: HTML node names: Not emitting 'Top (Manual name)'

[Patrice Dumas]

On Fri, Mar 15, 2024 at 09:42:28AM +0200, Eli Zaretskii wrote:
> > What we envisionned, instead, was to provide with the HTML customization
> > API to do the kind of modifications you want to do.  I can imagine a
> > number of reasons why this solution is not that attractive for your use
> > case, for instance it does not allow to be compatible with a wide range
> > of makeinfo releases, may not be that stable, is in Perl, and could
> > require important work.  Still, maybe you could consider using that
> > possibility in the future if you face incompatible changes again.
> 
> I think the main reason this solution is not used is that it is still
> a kind of "black magic" for almost everyone, definitely for me
> personally.  The relevant sections of the Texinfo manual are basically
> a very terse man-page style reference of options in alphabetical
> order, without any kind of tutorial or general explanations or
> examples (without which it is hard to even understand some of the
> customization variables unless one is an HTML expert).  This is very
> unlike the other sections of the manual, which invariably provide
> detailed background explanations for each group of commands, describe
> the recommended practices, and provide a lot of examples.  I write
> Texinfo manuals for 20 years, and still consult the Texinfo manual all
> the time, always finding valuable information in it in the sections
> that describe the Texinfo language and how to use them in a
> well-written manual.

The information on HTML output customization and on the HTML output
customization API is not mainly in the Texinfo manual, but in the
texi2any Output Customization manual:
https://www.gnu.org/software/texinfo/manual/texi2any_api/

This manual describes how the HTML output can be changed with
customization variables (although is not complete in that regard), but
also with use of functions and functions redefinitions (and should be
complete for that matter).  I think that it is more in line with the
expected organization of a manual as you describe than the customization
variables sections of the Texinfo manual.  That being said, it is
incomplete, a work in progress, probably with poor grammar, and I am
quite unhappy about the overall organization of some parts of the
manual.  I never know if it is worth it investing time in that manual
rather than in texi2any, it is not clear to me that it it is useful to
others...

> With better documentation, it is quite possible that we could consider
> switching most, if not all, of the code in admin.el to using the
> texi2any customization capabilities -- provided again that those
> customization variables can be relied upon to be stable enough,
> without fearing they will be completely redesigned at some future
> time.

The customization variables and API described in the texi2any Output
Customization manual are not supposed to be stable yet as the API has
been completed recently and may still need to evolve.  So we do not
commit to keeping that interface stable.  That being said, it is
probably on the way to stability now that the HTML output code has been
also translated to C and that the changes needed for that have been
made.

-- 
Pat

Re: HTML node names: Not emitting 'Top (Manual name)'

[Patrice Dumas]

On Wed, Mar 13, 2024 at 09:25:44PM +0200, Eli Zaretskii wrote:
> >   . for HTML output, place section names before the manual in page
> > titles, instead of after them, so it is easier to distinguish pages
> > if titles are truncated
> > 
> > Nobody complained about this breaking any stability.
> 
> Ha! the amount of grief those changes caused the Emacs maintainers is
> beyond complaining.  We have a script that massages the produced HTML
> manuals for the Web site, and we run the script each time another
> Emacs version is released and the manual needs to be updated on the
> Web site.  Every single release of Texinfo, until very recently, would
> break the script and cause me personally and my colleagues a lot of
> gray hair wand wasted time.  So much so that I seriously considered to
> stop updating to the latest Texinfo on the system where I usually work
> on Emacs releases.  Finally, a few Texinfo versions ago, these changes
> have stopped, and we had a few Emacs releases without a single problem
> in this area.  No longer, it looks like...
> 
> And no, I didn't complain, because I never imagined (and don't imagine
> now) that someone would seriously consider backing out the offending
> changes, just because one project suffers from them.  But you'd be
> wrong taking silence for a sign of no problems.

I had a look at the code in admin/admin.el that (unless I missed
something) seems to do that, and indeed, it makes extensive changes and
needs to parse specific constructs.  Also it seems that you try to
target a wide range of makeinfo versions output.  I think that we do not
actually try to keep the level of stability of the makeinfo HTML output
you would need to avoid the need to change your code now and then, and
although I agree that we should lean towards stability, I do not think
that we should target that level of stability, because we need to cater
for the needs of all the users, as you already mentionned.

What we envisionned, instead, was to provide with the HTML customization
API to do the kind of modifications you want to do.  I can imagine a
number of reasons why this solution is not that attractive for your use
case, for instance it does not allow to be compatible with a wide range
of makeinfo releases, may not be that stable, is in Perl, and could
require important work.  Still, maybe you could consider using that
possibility in the future if you face incompatible changes again.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Mon, Jan 22, 2024 at 08:48:03AM +, Jean-Christophe Helary wrote:
> > It's questionable whether this would be a correct use of 
> > and  or not.  The online DocBook documentation says,
> > 
> > "The AuthorGroup element is a wrapper around multiple authors or other
> > collaborators."
> > 
> > 
> 
> I guess there is a reason why you refer to DocBook 4.5 and not DocBook 5.0?

It is because texi2any generates DocBook 4.5.  I have no idea which
should be our target.  I do not want to maintain conversion to different
DocBook versions.  It seems that there is an xslt to convert 4.5 to 5,
this is in favor of outputing 4.5, but if nobody uses 4.5 anymore, it
may be right to switch to 5.0, I don't know.  If, however, there are
still many applications that prefer 4.5, we could stay with 4.5.

> https://tdg.docbook.org/tdg/5.0/ch01#introduction-whats-new
> 
> collabname and a few others have been merged into orgname.
> 
> collab now has the following children:  affiliation, org, orgname, person, 
> personname.
> 
> https://tdg.docbook.org/tdg/5.0/collab

That's actually an issue for conversion from Texinfo, as it means that
the generic collabname is gone, we have to choose between org/orgname,
which is inadequate, and person/personname which is not usable, as it is
incorrect when @author corresponds to many authors, and even if there is
one author, in Texinfo there is no way to get the elements of a name
needed for personname.  I am not sure that we used collabname correctly,
but at least it was practical.

Ideas to convert te lax Texinfo @author to DocBook 5 are welcome...

-- 
Pat

Re: Translating the Emacs manuals (a summary)

[Patrice Dumas]

On Sat, Jan 20, 2024 at 06:08:07PM +, Jean-Christophe Helary wrote:
> > On Jan 21, 2024, at 3:01, Patrice Dumas  wrote:
> > 
> > Not necessarily very important, but UTF-8 is the default input encoding
> > since Texinfo 6.7 (23 September 2019), depending on the Texinfo minimal
> > version you target, you could remove the "@documentencoding UTF-8",
> > and/or change the wording of the recommendation.
> > 
> > On Fri, Jan 19, 2024 at 06:00:34PM +, Jean-Christophe Helary wrote:
> >> - ’@documentencoding UTF-8’ is automatically included in the file since it 
> >> is in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.
> 
> Do you mean that all the manuals that include this directive predate 
> Texinfo 6.7 (very likely)

Not necessarily, this is needed if processed by older versions.

>  and that basically we could remove the 
> directive from all the manuals without changing anything (considering 
> that they'd be built with texinfo 6.7+)?

Yes.

-- 
Pat

Re: Translating the Emacs manuals (a summary)

[Patrice Dumas]

Not necessarily very important, but UTF-8 is the default input encoding
since Texinfo 6.7 (23 September 2019), depending on the Texinfo minimal
version you target, you could remove the "@documentencoding UTF-8",
and/or change the wording of the recommendation.

On Fri, Jan 19, 2024 at 06:00:34PM +, Jean-Christophe Helary wrote:
> - ’@documentencoding UTF-8’ is automatically included in the file since it is 
> in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.


-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Thu, Jan 11, 2024 at 05:08:28PM +0200, Eli Zaretskii wrote:
> This is a much more complex solution, and it has some problematic
> aspects: it requires a network connection and some users consideer
> such features an annoyance.

Of course, and not only that, it also requires a way to know which
manual exist, where they are, and possibly a way to install them or
point to a way to install.

> Having @anchor with the English node name will allow cross-manual
> links to go to a translated manual if it exists, falling back to the
> English manual: all it takes is try to find manual-LANG.info (when the
> user's language is LANG) before falling back to manual.info.  Whereas
> cross-references with the translated manual could use the translated
> node names instead.  This will also allow translators not to bother in
> cross-references about translations of node names in other manuals:
> they could simply use the English node names.

The node name may be visible in the output, so if English node names are
used they won't be in the translated manual language.  So I do not think
that is it correct, in general, to use the English node names even if
they link to the correct node in a translated manual with English node
names as anchors.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Thu, Jan 11, 2024 at 08:09:28AM +0200, Eli Zaretskii wrote:
> > Date: Wed, 10 Jan 2024 21:52:23 +0100
> > From: Patrice Dumas 
> > Cc: Eli Zaretskii , Stefan Kangas ,
> > Vincent Belaïche ,
> > emacs-de...@gnu.org, r...@gnu.org, help-texinfo@gnu.org
> > 
> > In any case, if a target manual is not yet translated, to me it is the
> > responsibility of the translator of amnual linking to it to either link
> > to the english manual, or to translate the node name in @ref even though
> > it won't lead to an existing manual and the name may need to be changed
> > later on to match with the actual name used in the translated manual.
> > To me both case could make sense depending on many criteria, such as
> > whether readers are likely to read english, whether manuals are
> > being translated...
> 
> The translator doesn't always know whether a translated manual exists
> when the translation is being written.  And even if a translated
> manual does exist, there's no reason to be sure it will be installed
> on the end-user's system.

Having nodes linking to non installed manuals is, in general, an issue.
But I do not think that defaulting to the english manual for non english
manuals is a good thing to do.  Instead, it could be confusing,
especially if the missing translated manual is not shown prominently and
an english manual is substituted without much information and would not
convey the intention of the manual writer.

In my opinion, it would be much better to design a way to help with
installing a manual that is not already installed but exists and is
linked to irrespective of the issue of translations and still leave the
responsibility to setup the cross reference to the translator.  Having
some way to check node links in Info through automatic downloading of
manuals and check of all the referencecs could be nice too, but without
any special treatments of manuals not in english.

> So it would be good to have some Texinfo feature that would make the
> behavior of Info readers more user-friendly in these cases.  Right
> now, the Texinfo features that can help are @documentlanguage and the
> suggestion by Gavin to have in the translated manual an @anchor for
> each @node with the original English name of that @node.

Having @anchor indeed can help if the translator wants to link to the
english manual with translated node names.  Still, in my opinion, it
should only happen if the translator has setup the @ref to link to the
english manual by using the english manual name as @ref manual argument.

> > In any case, I don't see any reason to do any automatic redirection in
> > the Info reader, it should remain simple and be the translators/writers
> > responsibilities.
> 
> I don't think I agree, because leaving this completely to the
> responsibilities of the translator could easily produce sub-optimal
> results.

On the contrary, I think that having translators be responsible of cross
manual references is the best possible solution.  It could mean a link
to an english or translated manual based on a choice and not on an
automatic rule.  In that case, a choice seems to be better to me.

It is different from gettext, I think.  When we use gettext having
something in english is, in most cases, better than having nothing.
For cross references between manuals I think that it is not true. Having
the information that the link does not point to an installed manual is
better than substituting an english manual. As I said above, even better
could be to have information on existing manuals (and node in them ?)
and propose to install the manual, but it is a separate issue.

> > Another reason is that it would not be possible to do the same in
> > HTML, as in HTML it is not possible to check if the target exists.
> 
> Even if this cannot possibly be done in HTML (and I'm not yet sure),
> it shouldn't stop us from doing that in Info.  After all, HTML output
> lacks several features of Info output already, and it doesn't stop us.

If we follow up the long term plan to have HTML on par with Info output
as outlined in TODO.HTML, we should think about that kind of feature and
its adaptation to HTML as early as possible in the design phase to make
things easier later on.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Sat, Jan 06, 2024 at 09:37:03AM +, Jean-Christophe Helary wrote:
> 
> > But, for such links to work, we
> > need a facility to tell the Info reader that when a link goes to a
> > manual named FOO.info, it should visit FOO-LANG.info instead.  Again,
> > something that involves a change in Texinfo and in all Info readers.
> 
> What are the practical cases where translating nodes would be a problem?
> 
> 1. I read a manual in English, there is a link with a node in English, 
> it directs to the other English manual.
> 
> It’s the expected behaviour.
> 
> 2. I read a manual in French, there is a link with a node in English, 
> it directs to the other English manual.
> 
> If the other manual exists in French, it is not the proper behaviour.
> 
> 3. I read a manual in French, there is a link with a node in French, it 
> directs to the other French manual.
> 
> If the other manual exists in French, it is the proper behaviour.
> 
> If it does not, we should have an error message that informs the reader 
> that the manual is not translated.

This is already the current behaviour, though it is not possible to know
if the node name is incorrect or untranslated, and I do not think that
we should do something special here.

In any case, if a target manual is not yet translated, to me it is the
responsibility of the translator of amnual linking to it to either link
to the english manual, or to translate the node name in @ref even though
it won't lead to an existing manual and the name may need to be changed
later on to match with the actual name used in the translated manual.
To me both case could make sense depending on many criteria, such as
whether readers are likely to read english, whether manuals are
being translated...

In any case, I don't see any reason to do any automatic redirection in
the Info reader, it should remain simple and be the translators/writers
responsibilities.  Another reason is that it would not be possible to do
the same in HTML, as in HTML it is not possible to check if the target
exists.

-- 
Pat

Re: How to avoid mini toc in HTML output

[Patrice Dumas]

On Sat, Dec 30, 2023 at 04:28:02PM +0100, Hilaire Fernandes wrote:
> Hi folks,
> 
> I just upgraded some documentation to 7.x.
> 
> How can I avoid the mini-toc in the middle of the html document. See in the
> examples below. The first example is really confusing.

How the 'menus' are formatted depend on FORMAT_MENU customization
variable, which is now 'sectiontoc' by default.  It is possible to get
back to menu, by setting FORMAT_MENU to menu.  From the command line:

 texi2any --html -c FORMAT_MENU=menu manual.texi

or remove completly any type of menu by setting FORMAT_MENU to nomenu:

 texi2any --html -c FORMAT_MENU=nomenu manual.texi

But it is not clear to me that it is what you want, as it seems to me
that a mini-toc or a menu is needed in some cases for navigation, as in
the following page:
https://cuis-smalltalk.github.io/TheCuisBook/The-Fundamentals-of-Morph.html

This would probably require some code and a replacement of the nodes and
sectioning commands conversion function, _convert_heading_command, with
a change where the mini_toc is output, and here output the mini toc only
if $element->{'extra'}->{'section_level'} is below a given level,
something like

if ($self->get_conf('FORMAT_MENU') eq 'sectiontoc') {
  if ($element->{'extra'}->{'section_level'} <= 1) {
$mini_toc_or_auto_menu = _mini_toc($self, $element);
  }

The level could depend on the split option, the document seems to be
split at sections.

This would require an init file where you can copy the _convert_heading_command
code from texinfo tp/Texinfo/Convert/HTML.pm file, rename the function,
modify it, and associate it to the node and sectioning commands
conversion with:

foreach my $command (keys(%Texinfo::Commands::sectioning_heading_commands), 
'node') {
  texinfo_register_command_formatting ($command, 
\&my_modified_convert_heading_command);
}



> 
> https://cuis-smalltalk.github.io/TheCuisBook/Daily-Workflow.html#Automate-your-image
> 
> https://cuis-smalltalk.github.io/TheCuisBook/Going-Vector.html
> 
> Of course the main table of contents is still needed.

-- 
Pat

Re: Table of Contents always after copying section in html output

[Patrice Dumas]

On Sat, Dec 30, 2023 at 04:50:12PM +0100, Hilaire Fernandes wrote:
> Hi,
> 
> Since upgrading to texinfo 7.0.3, when rendering html, the table of contents
> always appears after the copying, even if instructed differently.

Indeed, the default for CONTENTS_OUTPUT_LOCATION is now 'after_top' in the
default case.  If you want to have it appear where @contents is, you
should change it to 'inline'.

On the command line, that would be:

  texi2any --html -c CONTENTS_OUTPUT_LOCATION=inline manual.texi

-- 
Pat

Re: @anchor on @item line (was: emacs-29 889a550ca08: ; Fix Texinfo warnings)

[Patrice Dumas]

On Mon, Nov 06, 2023 at 07:29:50PM +, Gavin Smith wrote:
> On Sun, Nov 05, 2023 at 11:30:42AM +, Ihor Radchenko wrote:
> > May someone please explain the correct usage of @anchor in the above
> > example and why the warning is being thrown?
> 
> I don't think there's really much wrong with it.  We added more warnings
> for nested commands, trying to define which commands should occur in
> certain contexts.  We have given the @item command a class of
> "contain_basic_inline", which excludes anchor commands, as well as
> the cross-reference commands.
> 
> I don't remember, or never knew to start with, what the justification
> was for giving @item this class.

I agree that accepting @anchor and @*ref on @item in @*table line would
be ok.

> However, for whatever reason, this use of @anchor on an @item line
> didn't trigger the warning in earlier releases.

My guess is that the code has been fixed to really use the 'flags' of
item_LINE and not the flags of @item that appears in @itemize,
@enumerate and @multitable which alreay has no restrictions in its content.

> It would be easy, I expect, to remove this warning:
> 
> diff --git a/tp/Texinfo/command_data.txt b/tp/Texinfo/command_data.txt
> index 7d07b8bd54..df63c6ccd7 100644
> --- a/tp/Texinfo/command_data.txt
> +++ b/tp/Texinfo/command_data.txt
> @@ -254,8 +254,8 @@ printindex  
> line,formattable_line,close_paragraph,global,contain_pla
>  listoffloats
> line,formattable_line,close_paragraph,global,contain_basic_inline   LINE_line
>  exdent  line,formatted_line,close_paragraph
> LINE_line
>  # or nobrace skipspace, depending on the context
> -item_LINE   
> line,formatted_line,close_paragraph,contain_basic_inlineLINE_line
> -itemx   
> line,formatted_line,close_paragraph,contain_basic_inlineLINE_line
> +item_LINE   line,formatted_line,close_paragraphLINE_line
> +itemx   line,formatted_line,close_paragraphLINE_line
>  nodedescription line,close_paragraph   
> LINE_line
>  # in index entries
>  subentryline,in_index,contain_basic_inline  LINE_line
> 0$ 
> 
> However, I would like to wait to see if anybody else has any comments first.

Looks good to me.

-- 
Pat

[bug #64752] [request] make the "next" hyperlink take you the next page, even if deeper in the hierarchy

[Patrice Dumas]

Follow-up Comment #6, bug #64752 (project octave):

It is possible, there is a direction that corresponds to next in reading
order, called 'Forward' (and there is one for previous in reading order, which
is called 'Back'). Now, the difficulty is how to add it to the header buttons.
I attach an init file that adds the 'Forward' direction after a space button
to all the possibilities for buttons. This may not be suitable for your case,
but gives you an idea on how to do that.

Information on directions:
https://www.gnu.org/software/texinfo//manual/texi2any_api/html_node/Directions.html

Information on calling user defined functions:
https://www.gnu.org/software/texinfo//manual/texi2any_api/html_node/Init-File-Calling-at-Different-Stages.html

Information on buttons
https://www.gnu.org/software/texinfo//manual/texi2any_api/html_node/Simple-Navigation-Panel-Customization.html

(file #55234)

___

Additional Item Attachment:

File name: add_forward_button.pm  Size:0 KB




___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

Re: Using texinfo for works that are not software-related

[Patrice Dumas]

On Wed, Aug 30, 2023 at 06:54:45AM +, Oleander wrote:
> As far as I know latex3 does not support exporting to html, epub,
> ascii and I need those formats. I should have explained it better but
> I don't need all the formatting options latex offers since I mostly
> write prose with some code/quote blocks.
> 
> By "good things" I meant semantic elements, indexes, cross references.

Also it is now possible to export to LaTeX.

> I've explored other markup languages but I've always been on the fence
> about those and I keep switching.
> 
> Markdown does not support indexes so I tend to exclude it for long
> documentation.
> 
> Org Mode is great but it lacks semantic elements besides blocks.
> 
> Asciidoc: good markup syntax and support semantic elements but I read
> the tooling leaves something to be desired.
> 
> Restructured text: great tooling but I don't like the syntax of some
> elements.

At some point, I considered doing converters for those kind of markup
languages as I liked in general their lightweight syntax, but in general
they lacked some important features of Texinfo, either footnotes,
indices, or that kind of constructs.  It was some time ago, so maybe it
evolved, but I am not surprised that you find them lacking in some
features available in Texinfo.

For general purpose writing, I think that the main feature lacking in
Texinfo is support for bibliographies.

-- 
Pat

Re: warning about missing menu items?

[Patrice Dumas]

On Sun, Jul 16, 2023 at 02:46:10PM -0600, Karl Berry wrote:
> I seem to recall that in the past there was a warning when a
> normally-structured manual had a missing menu entry? That doesn't seem
> to happen now, and I failed to find anything in the manual. Am I just
> going crazy :)?

A warning was recently readded for that case, so in the development
version there is a warning.  With 7.0.3, to get the warning, you need to
pass
  -c CHECK_NORMAL_MENU_STRUCTURE=1

As a side note, to me it would be fine if there was no warning in the
default case as it could be on purpose that chap2 is not in the menu.

Another possibility would be to pass a tree transformation to get texi2any
to generate the missing menu entry:

./texi2any.pl -c TREE_TRANSFORMATIONS=complete_tree_nodes_menus file.texi

> I can run M-x texinfo-all-menus-update, but still, I thought makeinfo
> also noticed this.
> 
> For example, there are no warnings from makeinfo
> (texi2any (GNU texinfo) 7.0.3) about the following. --thanks, karl.
> 
> \input texinfo
> 
> @node Top
> @top Missing
> 
> @menu
> * chap1::
> @end menu
> 
> @node chap1
> @chapter chap1
> 
> @node chap2
> @chapter chap2
> 
> @bye
> 

Re: describing config files

[Patrice Dumas]

On Tue, May 23, 2023 at 09:58:47AM +0100, Joao Dinis wrote:
> Hi,
> 
> I'm a newbie on texinfo, using to write an users manual.
> In that process I found the need to detail a configuration file by showing a
> few lines of it, followed by a description of what those lines mean, then
> showing a few more, describing, and so on.
> 
> The full config file will go in an appendix (~500 lines long).  But, it
> would be great if the users could have a line number preceding each line.
> To make that work, the line numbers should be typeset slightly smaller or
> grayed (or even the two), to avoid confusion with the body of the config
> file.
> 
> I found no way to do that with texinfo.  I'm almost sure it can't be done
> straight out from the box.  Does anyone has some idea how to do it?

What output format would you want it for?  In Info, my guess is that it
would be quite confusing.  In HTML, LaTeX and PDF, it would probably
make sense.  I can imagine how to do it in HTML, and in LaTeX it would
depend on existing packages.

> If not possible, and since I think this could be useful in many scenarios,
> it would be great to have something like:

This does not follow the philosophy of Texinfo, to be mostly semantic.

I see two possiblities to do it more semantically
1) for @example only, add semantics to the second argument to set line
   counting. The line count would always start at 1
2) a global @set XXX or specific @-command that turns on lines counting
   for @example/@list/@display/@format... And @verbatim?  The line count
   would always start at 1
3) give an argument to @verbatiminclude (or use a new @-command) to
   include specific lines of an input file and another argument to
   have the line count shown.

Those two possibilities would not really correspond to your need, as it
seems to me that you also want to control the starting line 

> @example
> @color{gray}{11} start = 102
> @end example
> 
> to typeset the 11 in gray (in tt font), a space, and the the start = 102 in
> typewriter as usual.
> 
> Or perhaps even:
> 
> @example
> @datafile{11-21}{config.dat}
> @end example
> 
> To have lines 11 to 21 of config.dat (and only those) inserted there, with
> line numbers in gray, as exemplified above.  Without no line number argument
> it could insert the all file.

@verbatiminclude includes a whole file, but there is no equivalent for
@example.  And no possibility to start at a specific line, nor line
counting.

> Not sure if this is the right place for feature request, but here is it.

It is the right place.

-- 
Pat

Re: Playground pager lsp(1)

[Patrice Dumas]

On Wed, Apr 05, 2023 at 11:03:36AM +0200, to...@tuxteam.de wrote:
> 
> I was dreaming of a world where both doc systems converge
> in a way their respective users don't notice, and we end
> up with a Grand Unified Documentation (GUD) for all things
> free.

Because of the differences in design, as Eli described, I do not think
that it is really possible to have something really well unified, nor to
have users not noticing.  That being said, it may be possible to have
cross-manual links better handled accross different documentation
systems.

For HTML, we have in Texinfo a way to specify other manuals as described
here:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Link-Basics.html
Maybe it could be considered for a similar scheme for man pages, such
that the man pages can be specified as a Texinfo @xref (as documented at
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-References.html
) and could be used to link from/to man pages when both man pages and
Texinfo manuals are rendered as HTML.

Doing something with the Info format and the Info reader, especially the
standalone infor reader (maybe it could be easier with the Emacs Info
reader) is likely to be much more challenging if not impossible in my
opinion.  I cannot really imagine a way to have something really
integrated given the limitations of the Info format.  The standalone
Info reader already shows a man page when an info manual is not found,
but this is not true integration.

The Info format is described here, it is quite simple:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Info-Format-Specification.html

All that should probably be thought with other documentation systems,
for instance, it would make sense to include something like Mallard
(http://projectmallard.org/) in the reflexion, as the Mallard design is
again something else that Texinfo or man pages in term of design.

As a side note, we have a POD to Texinfo converter, POD explicitly
considers man pages (and POD design is clearly based on man pages), when
converting to Texinfo, I reused the Pod::Simple::HTML way of doing 
by having a link to 'ls (1)' becomes an url like
@uref{http://man.he.net/man1/ls}.  But again it is not very satisfying
as it is very specific of man pages.

If a discussion on cross formats links is started, I would be ok to be
in it, but I am not aware of such endeavour.

-- 
Pat

Re: Generalising @def*

[Patrice Dumas]

On Sat, Feb 11, 2023 at 11:59:07AM +, Gavin Smith wrote:
> 
> I've commited changes to texinfo.tex to introduce @defblock, @deflinex
> and @deftypelinex.  @deflinex is like @deffnx and @deftypelinex is like
> @deftypefnx.  The names of these could change, for example to remove the 'x'
> at the end of the commands, if we decide this would be better.
> 
> I believe this covers usage for @defvr, @deftypevr, @deftp.
> 
> I have gone off the idea of using @macro for this.  I am thinking a
> more limited command would be better, as mentioned in an earlier message
> 
>   @newdef defbuiltin = typed, tt, Built-in Function, fn
> 
> or similar.  This would cover the basics and be easy to use and understand.
> The example here would translate a @defbuiltin line to a @deftypelinex line
> within a @defblock.

I do not like that, as this adds commands that are not in the language
and it is always a pain.  I liked the generic command + separate index
entries, that could be grouped with @macro better.

-- 
Pat

Re: Generalising @def*

[Patrice Dumas]

On Fri, Feb 10, 2023 at 01:35:15PM +, Gavin Smith wrote:
> On Thu, Feb 02, 2023 at 07:14:53PM +, Gavin Smith wrote:
> > I imagine that there would be another type of block
> > like @defblock ... @end defblock which could contain the @def lines,
> > which would allow the same formatting without the use of @macro.
> 
> I expect that I'll be able to implement this in texinfo.tex.
> My current work is at the end of this mail.
> 
> I've commented out the code to create the index entry in \printdefunline,
> which until recently wasn't part of \printdefunline anyway, so it should
> be straightforward to remove this once I reverse the changes to introduce
> a @useindex command.  Apart from this, adding a new block command for
> a definition block, along with new line commands to print definition lines,
> seems straightforward.  With the patch below, the following input outputs
> as you would expect.

I have understood that the use can use any index command, simply by
adding it before the @deflinex, but I did not understand where the user
definition comes in?

> \input texinfo
> 
> @defblock
> @deflinex Functionoid bar (args)
> @deflinex Monoid bar2 (args, nineyy)
> hello
> 
> @end defblock
> 
> @bye 
> 
> I expect that once this is in texi2any, any @?index lines in
> the @defblock should be handled along with recent/ongoing changes
> for copiable anchor links for definition commands.
> 
> User-defined definition commands could be limited to macros that use
> @deflinex (or similar line commands that we will introduce).  There
> will be no definitions on the @defblock line itself.  Thus we can avoid
> or delay the question of allowing users to define their own block commands
> with a corresponding "@end" line.
> 
> I'll post more once this work is more complete.
> 
> 
> diff --git a/doc/texinfo.tex b/doc/texinfo.tex
> index 0f57611a5e..b1e3cb8cee 100644
> --- a/doc/texinfo.tex
> +++ b/doc/texinfo.tex
> @@ -7570,9 +7570,9 @@ might help (with 'rm \jobname.?? \jobname.??s')%
>  % call \deffooheader:
>  #1#2 \endheader
>  % create the index entry
> -\defcharsdefault
> -\edef\temp{\noexpand\doind{\the\defidx}{\the\deftext}}%
> -\temp
> +% \defcharsdefault
> +% \edef\temp{\noexpand\doind{\the\defidx}{\the\deftext}}%
> +% \temp
>  % common ending:
>  \interlinepenalty = 1
>  \advance\rightskip by 0pt plus 1fil\relax
> @@ -7587,6 +7587,19 @@ might help (with 'rm \jobname.?? \jobname.??s')%
>  
>  \def\Edefun{\endgraf\medbreak}
>  
> +\envdef\defblock{%
> +  \startdefun
> +}
> +\let\Edefblock\Edefun
> +
> +\def\deflineheader#1 #2 #3\endheader{%
> +  \defname{#1}{}{#2}\magicamp\defunargs{#3\unskip}%
> +}
> +
> +\def\deflinex{%
> +\parseargusing\activeparens{\printdefunline\deflineheader}%
> +}
> +
>  % \makedefun{deffoo} (\deffooheader parameters) { (\deffooheader expansion) }
>  %
>  % Define \deffoo, \deffoox  \Edeffoo and \deffooheader.
> 
> 

Re: info info; man info (documentation about info)

[Patrice Dumas]

On Tue, Jan 10, 2023 at 05:57:29PM +0100, Arsen Arsenović wrote:
> Hi Eli,
> 
> Eli Zaretskii  writes:
> 
> > I'd expect downstream distros to do that already.  If they don't,
> > maybe Texinfo should (although I'm not sure how to arrange for that in
> > a way that won't make the job of Texinfo release too complicated).  I
> > definitely agree that it would be good to have info.info accompany the
> > Texinfo installation.
> 
> Checking Fedora, Debian and Gentoo, it'd appear none of them do that.

For Debian, info.info is in emacs-common-non-dfsg,
"GNU Emacs common non-DFSG items, including the core documentation"
which is in non-free, because of invariant sections.  I do not think
that there are invariant sections in info.texi, but I guess that the
Debian packagers do not try to distinguish each manual in Emacs based on
the specific conditions.  I think that it makes it more difficult to
setup info to depend on a subpackage to be done that would include
info.info only.

Maybe it could be possible to open bugs to have both info readers depend
on info.info in the diverse distributions.

-- 
Pat

Re: Last(est) Texinfo version that generates HTML4 output?

[Patrice Dumas]

On Wed, Jan 04, 2023 at 05:08:09PM +0700, Nutchanon Wetchasit wrote:
> Hello,
> 
> So what I would like to know is: what is the last version of GNU Texinfo
> that its `makeinfo` or `texi2html` utility produces SGML-style HTML output
> which DOES NOT make _any_ use of HTML construct introduced after HTML 4.01?

The current version does not use HTML constructs introduced after HTML
4.01 except for a custom attribute, as far as I can tell.  So normally,
simply setting the DOCTYPE and setting the customization variable that
removes the custom attribute should be all you need to do, like

texi2any --html -c DOCTYPE='http://www.w3.org/TR/html4/loose.dtd";>' -c 
'NO_CUSTOM_HTML_ATTRIBUTE=1' myfile.texi

Some attributes that were dropped in 4.01 strict and readded in HTML 5
may be present, though, but I am not very sure, and I think that they
were still in the transitional HTML 4.01.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sun, Nov 27, 2022 at 10:34:15AM +, Gavin Smith wrote:
> On Sat, Nov 26, 2022 at 11:11:52PM +0100, Patrice Dumas wrote:
> > I spotted two cases for which the index entry could also be with the
> > table term (in xtables inter_item_commands_in_table test), with a
> > comment between index entry and @item or an empty line between index
> > entry and @item:
> > 
> > @table @code
> > @cindex cindex in table 
> > @c comment in table
> > @item abb
> > l--ine
> > @end table
> > 
> > @table @samp 
> > @cindex cindex before line
> > 
> > @item asamp--bb2
> > @end table
> 
> I had seen those but they didn't seem important.  They would need handling
> of the empty line and comments, which probably wouldn't be difficult.

I did it for the comments.  For empty lines, it does not seem that clear
actually, it could be considered as signaling that the index entry
should be with the text before.

> What is more awkward is when there is no blank line before the index command:
> 
> @table @asis
> @item aaa
> text
> @cindex XXX
> @item bbb
> text
> @end table
> 
> producing
> 
> 
> aaa
> text
> 
> 
> bbb
> text
> 
> 
> 
> There are several such usages in the Texinfo manual; for example, in the table
> of units in (texinfo)Image Scaling.  Adding an extra blank line before the
> index command adds an extra blank line in the Info output, which is not
> desired for some tables, in this case looking like
> 
> pt
>  point (72.27pt = 1in)
> pc
>  pica (1pc = 12pt)
> bp
>  big point (72bp = 1in)
> in
>  inch
> 
> and adding extra blank lines between the entries would waste space on the
> screen.
> 
> The issue is that @cindex is included with the paragraph.  This should be
> fixable by making index commands close a paragraph, although it would remove
> the possibility of having an index target part way through a paragraph, which
> could be important.  (For example, in paginated output with a paragraph
> crossing over a page, with the relevant material on the later page - the
> index entry should refer to the later page, not the earlier page.)
> In texinfo.tex output,
> 
> aaa
> @cindex foo
> bbb
> 
> produces output that looks like, simply, "aaa bbb".
> 
> So I am not too keen on making index commands close paragraphs.
> 
> I don't have a good solution at the moment. Another idea that came to
> mind was to reparent trailing index entries in paragraphs, so that with
> 
> aaa
> @cindex foo
> 
> bbb
> 
> the "foo" index entry isn't part of the first paragraph.

For such cases, it is not clear to me what the output should be
actually, the index entry could belong to the previous or next @item.
Since the result is ok, I think that we can leave it as it is.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 11:11:52PM +0100, Patrice Dumas wrote:
> It is a help for formats that have restrictions on what can be in
> tables.  Maybe would be a good think to check that the DocBook is also
> valid.

Seems like that it is better as index entries are better in  in
DocBook too.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 08:18:43PM +, Gavin Smith wrote:
> On Sat, Nov 26, 2022 at 03:59:00PM +, Gavin Smith wrote:
> > I still haven't put index entries before the very first
> > @item in a @table inside the  - I need to do something with the
> > 'before_item' element.
> 
> It should be done now.  I tried never adding a 'before_item' element
> in the first place, but this appeared to have repercussions throughout
> the code leading to failures in several places that I couldn't understand,
> so I fixed it in a more limited way.

It is a help for formats that have restrictions on what can be in
tables.  Maybe would be a good think to check that the DocBook is also
valid.

> which I think is good.

Agreed.

I spotted two cases for which the index entry could also be with the
table term (in xtables inter_item_commands_in_table test), with a
comment between index entry and @item or an empty line between index
entry and @item:

@table @code
@cindex cindex in table 
@c comment in table
@item abb
l--ine
@end table

@table @samp 
@cindex cindex before line

@item asamp--bb2
@end table


-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 05:49:54PM +0100, Arsen Arsenović wrote:
> 
> I wanted to give implementing that an attempt, but while trying to
> configure and build the texinfo trunk, I get:

This should be fixed by
https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=3ae7857e9f958386864f5ad4b7536ae50a130c8b

> 
>   make[4]: Entering directory '/home/arsen/gnu/texinfo/_build/doc/tp_api'
>   restore=: && backupdir=".am$$" && \
>   rm -rf $backupdir && mkdir $backupdir && \
>   if (/usr/bin/perl -I ../../../tp/ ../../../tp/texi2any.pl --version) 
> >/dev/null 2>&1; then \
> for f in texi2any_internals.info texi2any_internals.info-[0-9] 
> texi2any_internals.info-[0-9][0-9] texi2any_internals.i[0-9] 
> texi2any_internals.i[0-9][0-9]; do \
>   if test -f $f; then mv $f $backupdir; restore=mv; else :; fi; \
> done; \
>   else :; fi && \
>   if /usr/bin/perl -I ../../../tp/ ../../../tp/texi2any.pl -c 
> INFO_SPECIAL_CHARS_WARNING=0  -I ../../../doc/tp_api \
>-o texi2any_internals.info `test -f 'texi2any_internals.texi' || echo 
> '../../../doc/tp_api/'`texi2any_internals.texi; \
>   then \
> rc=0; \
>   else \
> rc=$?; \
> $restore $backupdir/* `echo "./texi2any_internals.info" | sed 
> 's|[^/]*$||'`; \
>   fi; \
>   rm -rf $backupdir; exit $rc
>   Can't locate Texinfo/ModulePath.pm in @INC (you may need to install the 
> Texinfo::ModulePath module) (@INC contains: ../../../tp ../../../tp/ 
> /etc/perl /usr/local/lib64/perl5/5.36/x86_64-linux-thread-multi 
> /usr/local/lib64/perl5/5.36 
> /usr/lib64/perl5/vendor_perl/5.36/x86_64-linux-thread-multi 
> /usr/lib64/perl5/vendor_perl/5.36 
> /usr/lib64/perl5/5.36/x86_64-linux-thread-multi /usr/lib64/perl5/5.36 
> /usr/lib64/perl5/vendor_perl/5.34) at ../../../tp/texi2any.pl line 78.
>   BEGIN failed--compilation aborted at ../../../tp/texi2any.pl line 107.
>   make[4]: *** [Makefile:1449: texi2any_internals.info] Error 2
>   make[4]: Leaving directory '/home/arsen/gnu/texinfo/_build/doc/tp_api'
>   make[3]: *** [Makefile:1414: all] Error 2
> 
> Though, this can be worked around with ./pre-inst-env make.  It seems
> like the $(builddir)/tp directory isn't added to the include path (this
> is an out-of-tree build, which is the configuration I normally opt for,
> since it allows multiple configurations at one time, as well as easier
> cleanup).
> 
> -- 
> Arsen Arsenović

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 05:49:54PM +0100, Arsen Arsenović wrote:
> 
> Gavin Smith  writes:
> 
> > I have nuked the relate_index_entries_to_table_entries transformation
> > which made this association.  According to the changelog, I introduced
> > this code in November 2020.  This may remove some copiable anchors from
> > HTML manuals, for @item in @table.  We'll have to decide if and when
> > such should still be output.
> 
> I wanted to give implementing that an attempt, but while trying to
> configure and build the texinfo trunk, I get:

I cannot reproduce it with make or make check (in an out of tree build),
but with make html.  I will try to fix it.  As a side note make pdf does
not work if texi2pdf is not installed, I don't know if it should be
fixed to use in-source texi2pdf.

So, what exactly triggered that error?

> 
>   make[4]: Entering directory '/home/arsen/gnu/texinfo/_build/doc/tp_api'
>   restore=: && backupdir=".am$$" && \
>   rm -rf $backupdir && mkdir $backupdir && \
>   if (/usr/bin/perl -I ../../../tp/ ../../../tp/texi2any.pl --version) 
> >/dev/null 2>&1; then \
> for f in texi2any_internals.info texi2any_internals.info-[0-9] 
> texi2any_internals.info-[0-9][0-9] texi2any_internals.i[0-9] 
> texi2any_internals.i[0-9][0-9]; do \
>   if test -f $f; then mv $f $backupdir; restore=mv; else :; fi; \
> done; \
>   else :; fi && \
>   if /usr/bin/perl -I ../../../tp/ ../../../tp/texi2any.pl -c 
> INFO_SPECIAL_CHARS_WARNING=0  -I ../../../doc/tp_api \
>-o texi2any_internals.info `test -f 'texi2any_internals.texi' || echo 
> '../../../doc/tp_api/'`texi2any_internals.texi; \
>   then \
> rc=0; \
>   else \
> rc=$?; \
> $restore $backupdir/* `echo "./texi2any_internals.info" | sed 
> 's|[^/]*$||'`; \
>   fi; \
>   rm -rf $backupdir; exit $rc
>   Can't locate Texinfo/ModulePath.pm in @INC (you may need to install the 
> Texinfo::ModulePath module) (@INC contains: ../../../tp ../../../tp/ 
> /etc/perl /usr/local/lib64/perl5/5.36/x86_64-linux-thread-multi 
> /usr/local/lib64/perl5/5.36 
> /usr/lib64/perl5/vendor_perl/5.36/x86_64-linux-thread-multi 
> /usr/lib64/perl5/vendor_perl/5.36 
> /usr/lib64/perl5/5.36/x86_64-linux-thread-multi /usr/lib64/perl5/5.36 
> /usr/lib64/perl5/vendor_perl/5.34) at ../../../tp/texi2any.pl line 78.
>   BEGIN failed--compilation aborted at ../../../tp/texi2any.pl line 107.
>   make[4]: *** [Makefile:1449: texi2any_internals.info] Error 2
>   make[4]: Leaving directory '/home/arsen/gnu/texinfo/_build/doc/tp_api'
>   make[3]: *** [Makefile:1414: all] Error 2
> 
> Though, this can be worked around with ./pre-inst-env make.  It seems
> like the $(builddir)/tp directory isn't added to the include path (this
> is an out-of-tree build, which is the configuration I normally opt for,
> since it allows multiple configurations at one time, as well as easier
> cleanup).
> 
> -- 
> Arsen Arsenović

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 04:45:24PM +, Gavin Smith wrote:
> On Wed, Nov 23, 2022 at 11:56:30PM +0100, Patrice Dumas wrote:
> > As I said before I do not think that it is right to merge the first
> > index entry with the @item, but that's a separate issue.
> 
> I have nuked the relate_index_entries_to_table_entries transformation
> which made this association.  According to the changelog, I introduced
> this code in November 2020.  This may remove some copiable anchors from
> HTML manuals, for @item in @table.  We'll have to decide if and when
> such should still be output.

Looks perfect to me.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 03:58:59PM +, Gavin Smith wrote:
> On Thu, Nov 24, 2022 at 12:07:47AM +0100, Patrice Dumas wrote:
> > It is also possible to do something when the element is first
> > encountered, with $default_types_open{'table_term'} = 
> > \&_open_table_term_type;
> > though I am not sure at all that it would help you.
> 
> I used this, thanks.  I opened  at the 'table_term' so that it
> would include any index entries that were inside the 'table_term'.

I just pushed a commit which removes _open_table_term_type.  Feel free
to revert it if you need to.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Sat, Nov 26, 2022 at 03:58:59PM +, Gavin Smith wrote:
> On Thu, Nov 24, 2022 at 12:07:47AM +0100, Patrice Dumas wrote:
> > It is also possible to do something when the element is first
> > encountered, with $default_types_open{'table_term'} = 
> > \&_open_table_term_type;
> > though I am not sure at all that it would help you.
> 
> I used this, thanks.  I opened  at the 'table_term' so that it
> would include any index entries that were inside the 'table_term'.

I do not think that this is actally needed.  I will try to do it with
_open_table_term_type only, and see if it is ok.

> I still haven't put index entries before the very first
> @item in a @table inside the  - I need to do something with the
> 'before_item' element.

Ok.

> Ideally the parser should produce a sensible parse tree itself and this
> would be sufficient for the conversions, without the need for any
> "transformations", although this may not be possible.

The parse tree is sensible as it is now (or as you changed it), but tree
transformations suited to output formats may make sense, and be only
valid for some output formats.  In our case, in HTML there is no
constraint on having only one line in a , so it is possible that a
tree that makes sense for HTML, with index entries being put in a @item,
or in the table_term type container, while in other formats where table
@item must be on a line it would not be possible.

That being said, it seems to me that for that case your change is good,
and there is no need for a transformation, which is better.

> One concern is matching the behaviour of the texinfo.tex PDF output -
> it's much more difficult to move index entry targets around there.

It may not be necessary either, maybe this could change in the future,
but in the texinfo.tex PDF the link is to the page, not to the precise
entry, and even if I am mistaking and it is to the precise location of
the entry, I think that in pdf not being as precise as in HTML is not
necessarily bad.  Also it seems to me that in HTML we care more about
the nesting of elements than in PDF.  The HTML result can be further
used by javascript/CSS such that the constraints are not the same.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Fri, Nov 25, 2022 at 10:12:21PM +, Gavin Smith wrote:
> On Tue, Nov 22, 2022 at 09:49:33PM +, Gavin Smith wrote:
> > On Tue, Nov 22, 2022 at 10:23:24PM +0100, Patrice Dumas wrote:
> > > Maybe not important if there are other changes afterwards, but with the
> > > change, in HTML, the result is now invalid, as the index entries end up
> > > not associated with the index term , but after the index term.  This
> > > is not correct, as the outer  should only contain  and .  It
> > > may not be an issue at all if you do further changes, or it could be an
> > > issue to be solved in the HTML converter.
> > 
> > I'll check this output and see I can change it to be valid again.
> 
> I've reverted my change as I couldn't make it work out right and it is
> not clearly right.
> 
> I'm starting to think that it should be index entries *before* the @item that
> are associated with the @item, not after it.  I feel this may be easier to
> implement.  This would leave the Info output unaltered.

I thought a bit more on that issue, and indeed, even if the index
entries lead to the @item when they are before the item, it could still
make sense to reparent them to the @item, at the beginning instead of
being before the @item, and, in HTML in the end of the previous  or
.

I still think that a tree transformation that gather the index entries
before the @item, between @item and @itemx and after @itemx and reparent
them to the @item would be the best option.  I do not think that it is
the job of the parsing to reorganize the tree.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Fri, Nov 25, 2022 at 10:12:21PM +, Gavin Smith wrote:
> There may be a related issue with associating index entries with other
> constructs.  For example, a paragraph:
> 
> @cindex paragraph 1
> This is a paragraph.
> 
> outputing in HTML as
> 
> 
> This is a paragraph.
> 
> 
> Arguably, the following may be better:
> 
> This is a paragraph.
> 
> 
> However, this may be more difficult to achieve than just focusing on
> the @table case.

Actually, I see that the issue is that the index entry is not in the
paragraph, so I think that the best may be

 
 This is a paragraph.
 

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Fri, Nov 25, 2022 at 10:12:21PM +, Gavin Smith wrote:
> On Tue, Nov 22, 2022 at 09:49:33PM +, Gavin Smith wrote:
> > On Tue, Nov 22, 2022 at 10:23:24PM +0100, Patrice Dumas wrote:
> > > Maybe not important if there are other changes afterwards, but with the
> > > change, in HTML, the result is now invalid, as the index entries end up
> > > not associated with the index term , but after the index term.  This
> > > is not correct, as the outer  should only contain  and .  It
> > > may not be an issue at all if you do further changes, or it could be an
> > > issue to be solved in the HTML converter.
> > 
> > I'll check this output and see I can change it to be valid again.
> 
> I've reverted my change as I couldn't make it work out right and it is
> not clearly right.
> 
> I'm starting to think that it should be index entries *before* the @item that
> are associated with the @item, not after it.  I feel this may be easier to
> implement.  This would leave the Info output unaltered.

Index entries before the @item already appear at the item when linked
to.  So keeping them as they are is ok too.  Index entries after an item
appears to be after the item, while the intention of th ewriters is
often for the entries to be associated with the @item.  So I still think
that your original attempt, to associate index entries following @itemx
and @item to the @item, and possibly having all the  elements before
the text in the  would seem right to me.

> There may be a related issue with associating index entries with other
> constructs.  For example, a paragraph:
> 
> @cindex paragraph 1
> This is a paragraph.
> 
> outputing in HTML as
> 
> 
> This is a paragraph.
> 
> 
> Arguably, the following may be better:
> 
> This is a paragraph.
> 
> 
> However, this may be more difficult to achieve than just focusing on
> the @table case.

I am not convinced that it is right, as the information that
id="index-paragraph-1" relates to an index entry is lost.  With a
separate  with the class="index-entry-id" the structure is better
kept.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Thu, Nov 24, 2022 at 12:07:47AM +0100, Patrice Dumas wrote:
> of the elements, but for a tree that is given.  The TREE_TRANSFORMATIONS
> are much better suited for changing the tree.

As a side note the relate_index_entries_to_table_entries_in_tree
transformation replace index entris in tables, and sort of do something
similar with what you want to do (if I read the code well), but only for
the first index entry.
see _relate_index_entry_to_table_entry in Texinfo/Common.pm.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Wed, Nov 23, 2022 at 09:31:07PM +, Gavin Smith wrote:
> I made this change by adding a new conversion for the 'table_term' type
> in HTML.pm, which outputs the , so that everything inside the
> 'table_term' (@item, @itemx and @?index) is output inside the .
> 
> This might be the wrong way of approaching this (hence my not sharing the
> code).  If both @item and @itemx should produce their own , but they
> are both children of the same 'table_term', then something else would need
> to be done to get the index entries inside one of the  elements.
> 
> It might work if there was some way of controlling the conversion more
> inside 'table_term'.  When I implemented a conversion for 'table_term'
> (by using a line
> 
> $default_types_conversion{'table_term'} = \&_convert_table_term_type;
> 
> along with a new function), the conversion function had the contents
> already converted.

It is also possible to do something when the element is first
encountered, with $default_types_open{'table_term'} = \&_open_table_term_type;
though I am not sure at all that it would help you.

I have not looked hard into this issue, but a possibility is that
modifying the tree may be simpler to implement the change.  In my
experience, and by design, the HTML API is not fit for changing the
tree, the objective of the API is to be able to customize the formatting
of the elements, but for a tree that is given.  The TREE_TRANSFORMATIONS
are much better suited for changing the tree.  As I said, I do not have
really looked at that issue, it is possible that what you want to
achieve cannot be achieved with a different Texinfo elements tree, but
if it could, my feeling is that a tree transformation would be simpler
to implement.  In addition, the speed penalty should not be particularly
important, as the tree is already traversed for other transformations,
it would just be a matter of adding another transformation during the
traversal.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Wed, Nov 23, 2022 at 09:31:07PM +, Gavin Smith wrote:
> 
> I've been working on this, and with my current code I have, with the
> following input:
> 
> @table @asis
> @item AAA
> @itemx BBB
> @vindex index1
> @vindex index2
> @vindex index3
> Hello
> 
> @end table
> 
> the following output:
> 
>
>AAABBB id="index-index2">
>
> ¶
>Hello
>
>
>

> I think this works well, apart from the treatment of @itemx, which is no
> longer its own  element, which is questionable.  There may be
> better ways than simply separating the @item and @itemx output with .
> I couldn't easily find documentation of the HTML  that said it was
> okay to have two  elements following each other.

It is ok to have two  elements following each other as Arsen
reported too.  Using  is not right, as the semantic meaning of
@itemx is lost.  The output should better be along (need to check
whether the copiable anchor is rendered correctly):


AAA 
¶


BBB
Hello




As I said before I do not think that it is right to merge the first
index entry with the @item, but that's a separate issue.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Tue, Nov 22, 2022 at 09:49:31PM +, Gavin Smith wrote:
> On Tue, Nov 22, 2022 at 10:23:24PM +0100, Patrice Dumas wrote:
> > Maybe not important if there are other changes afterwards, but with the
> > change, in HTML, the result is now invalid, as the index entries end up
> > not associated with the index term , but after the index term.  This
> > is not correct, as the outer  should only contain  and .  It

Should read, the outer  should only contain  and .

> > may not be an issue at all if you do further changes, or it could be an
> > issue to be solved in the HTML converter.
> 
> I'll check this output and see I can change it to be valid again.

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Tue, Nov 22, 2022 at 09:49:31PM +, Gavin Smith wrote:
> > > I think deciding on the right output for the existing usage and
> > > implementing such is more important than devising and implementing
> > > new language constructs.
> > 
> > Sure, except that for that case, I do not think that we can decide what
> > is the best output for the existing usage, as some users could want
> > index entries merged with @ftable @item while some other may not.
> > Adding a new language construct allows to make everyone happy.  The
> > current @ftable keeps not having index entries merged with @item, while
> > they are in the new construct, and in a more explicit/controlled way.
> > Of course this should be weighted against one more new language
> > construct, but to me, automatically merging one preceding/following
> > index entry to @ftable @item is not right.
> 
> @ftable and @vtable may be treated differently to @table as they provide
> their own index entries.

I actually meant @table in my paragraph above:

For that case, I do not think that we can decide what
is the best output for the existing usage, as some users could want
index entries merged with @table @item while some other may not.
Adding a new language construct allows to make everyone happy.  The
current @table keeps not having index entries merged with @item, while
they are in the new construct, and in a more explicit/controlled way.
Of course this should be weighted against one more new language
construct, but to me, automatically merging one preceding/following
index entry to @table @item is not right.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Tue, Nov 22, 2022 at 09:11:58PM +, Gavin Smith wrote:
> 
> I've committed a change to move the index entries to the 'table_term'
> element, and updated the code in the 'relate_index_entry_to_table_entry'
> tree transformation to look for an index entry in the new place.  My
> intention is that table items will be associated with the same index
> entries as before.  This was a preliminary change to allow other changes
> afterwards.

Maybe not important if there are other changes afterwards, but with the
change, in HTML, the result is now invalid, as the index entries end up
not associated with the index term , but after the index term.  This
is not correct, as the outer  should only contain  and .  It
may not be an issue at all if you do further changes, or it could be an
issue to be solved in the HTML converter.

> The changes to the test results seemed acceptable, but I would like to
> check which tests check combinations of @item/@itemx/@?index and
> add more tests if needed.
> 
> > I think that it would be better to separate the issue of index entries
> > repositioning from the issue of having a table command associated to
> > another index type, and to have an index entry not matching the @item
> > argument.
> > 
> > Could be for example
> > 
> > @itable
> > @item v, pedantic, -pedantic
> > 
> > @end itable
> 
> I think deciding on the right output for the existing usage and
> implementing such is more important than devising and implementing
> new language constructs.

Sure, except that for that case, I do not think that we can decide what
is the best output for the existing usage, as some users could want
index entries merged with @ftable @item while some other may not.
Adding a new language construct allows to make everyone happy.  The
current @ftable keeps not having index entries merged with @item, while
they are in the new construct, and in a more explicit/controlled way.
Of course this should be weighted against one more new language
construct, but to me, automatically merging one preceding/following
index entry to @ftable @item is not right.

-- 
Pat

Re: @defun and @defvr in the "same" block?

[Patrice Dumas]

On Tue, Nov 22, 2022 at 07:21:05AM -0800, Raymond Toy wrote:
> On Tue, Nov 22, 2022 at 12:59 AM Patrice Dumas  wrote:
> 
> I personally find it kind of weird to mix deffn and defvrx in the same
> block.  If I were writing this from scratch, I would have separated them.
> But this is a conversion of an old Scribe doc, so that's way too much
> effort.  I might just do
> 
> @defun
> @end defun
> @defvar
> 
> @end defvar

Seems good enough.

> to get the entries into the right index and still have it look as if
> they're together as in the original doc.  This is mostly busy work.
> 
> Oh, and for the record, look at
> https://cmucl.common-lisp.dev/doc/encycmuclopedia/devenv/cim.ps for the
> original Scribe version.  Look at the bottom of page 7.
> 
> For the conversion, see the bottom of page 6 of
> https://cmucl.common-lisp.dev/docs/hem/cim/cim.pdf
> 
> just so the various bits are in the correct index.

This looks right.

-- 
Pat

Re: @defun and @defvr in the "same" block?

[Patrice Dumas]

On Mon, Nov 21, 2022 at 08:35:01PM -0600, Jacob Bachmeyer wrote:
> Patrice Dumas wrote:
> > Currently yes.  But indeed, it would be natural in that case to follow
> > @deffn by @defvarx.  I think that it would not be hard to implement that
> > in texi2any, but I am not sure that we want to have that possibility in
> > the Texinfo language.
> 
> What would be wrong with it?

I don't know, but if it is not already in the language, it may be
because there could be some issues.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Mon, Nov 21, 2022 at 10:04:16PM +0100, Patrice Dumas wrote:
> To have the 'pedantic' variable index entry associated with the
> '-pedantic' table term label.  Instead of @item, it could be another
> command, like @itemindex, so something like
> 
> @itable @code
> @itemindex v, pedantic, -pedantic
> @itemindexx op, -Wpedantic@comma{} option, -Wpedantic
> description
> @end itable

And if the second argument is omited, it would default to the third
arg, so for example below the op index entry would be -pedantic, the
same as the item term label.

@itable @code
@itemindex op,, -pedantic
description
@end itable

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Mon, Nov 21, 2022 at 08:49:34PM +, Gavin Smith wrote:
> My current work is at the bottom of the email.  This will need more testing
> and also implementing in the XS parser, so it will take me at least few days 
> to
> finish.

It could also be a tree transformation that is applied after the
tree parsing.

> The idea is to put the index entries in the 'table_term' element rather
> than 'table_item', and in the transformation in Texinfo::Common,
> to reorder inside table_term to put index entries first, taking the
> first index entry that occurs as the copiable anchor.  So
> 
> @table @asis
> @item -Wpedantic
> @itemx -pedantic
> @vindex pedantic
> @vindex Wpedantic
> @vindex Wno-pedantic
> a
> 
> bbb
> @end table
> 
> produces
> 
> 
> 
> 
> -Wpedantic href='#index-pe
> dantic'> ¶
> -pedantic
> a
> 
> bbb
> 
> 
> 
> Does this seem ok?

The repositioning of index entries look ok, but automatically
associating one to the table_term does not look clearly ok to me.  In
some cases it could what the user wanted, but in other cases not.  I
think that it would be better to separate the issue of index entries
repositioning from the issue of having a table command associated to
another index type, and to have an index entry not matching the @item
argument.

Could be for example

@itable
@item v, pedantic, -pedantic

@end itable

To have the 'pedantic' variable index entry associated with the
'-pedantic' table term label.  Instead of @item, it could be another
command, like @itemindex, so something like

@itable @code
@itemindex v, pedantic, -pedantic
@itemindexx op, -Wpedantic@comma{} option, -Wpedantic
description
@end itable


-- 
Pat

Re: @defun and @defvr in the "same" block?

[Patrice Dumas]

On Mon, Nov 21, 2022 at 11:37:10AM -0800, Raymond Toy wrote:
> However, I've run into a small issue.  The original Scribe did things like:
> 
> @defun[fun {check-region-query-size}, args {@i[region]}]
> @defhvar1[var {Region Query Size}, val {30}]
> @enddefun
> 
> This basically looks like as if I'd done defunx, except Region Query Size
> is marked as a Hemlock Variable.
> 
> My translation is
> 
> @deffn {Function} {check-region-query-size} {@i{region}}
> @deffnx {Hemlock Variable} {Region Query Size} @val{30}
> 
> @end deffn
> 
> The output matches the Scribe output.  But Region Query Size is in the
> Function Index, and not the Variable Index.
> 
> Is the only way to fix this is to use separate these two out and use @defvr
> for Region Query Size and potentially rewrite the description to match?

Currently yes.  But indeed, it would be natural in that case to follow
@deffn by @defvarx.  I think that it would not be hard to implement that
in texi2any, but I am not sure that we want to have that possibility in
the Texinfo language.

-- 
Pat

Re: Relating multiple index entries to one table item

[Patrice Dumas]

On Mon, Nov 21, 2022 at 03:29:29PM +0100, Arsen Arsenović wrote:
> 
> The solution of using an indexing table command (like @vtable) seems to
> be the better one generally, though.

It does not solve the case of wanting more than one index entry per
table item.

> I see now that the generic case is
> in the TODO; I'll see if I can work on that next week (as I have quite a
> bit of work already added up for this week).  What I was imagining is
> making @def[code]index generate an @XXtable command, where XX is the
> name passed to @def[code]index; does that sound okay?

It looks consistent with the language, but having @-command dynamically
generated is a pain for implementation (other than using @alias or
@macro).  For instance, the dynamically generated @-commands for index
obtained from @def[code]index are not practical in many situations in
implementation, though they are practical for the Texinfo writers.

Using arguments would make implementation easier, in general, in my
opinion.

-- 
Pat

Re: Backslashes in macros and texi2html

[Patrice Dumas]

On Sat, Oct 22, 2022 at 06:23:43PM +0200, Jean Abou Samra wrote:
> Hi,
> 
> \command
> 
> Note: command
> 
> Note the missing backslash after "Note:".
> 
> Unfortunately, LilyPond is still using texi2html, and it is
> difficult for us to switch to makeinfo --html aka. texi2any.

We are preparing for a Texinfo release right now, but for the
following release, it could probably be nice to try to have everything
in texi2any that is needed for LilyPond to switch.  This is a good
time, I think, as the HTML customization API is part of the release,
such that the API is probably somewhat stabilized.  The API is
incomplete, though, customization of translated strings is still
missing, and I think that it is needed for LilyPond but this should
be a good thing to have it in the following release.

> Do you know of a workaround for this? Werner found something
> where the input is changed,
> https://lists.gnu.org/archive/html/lilypond-devel/2022-10/msg00168.html
> but is there, by any chance, a way to write the @warning macro
> differently so as not to trigger this (apparent) bug?

I do not think that there is a way to change the macro to avoid that
issue.  Another possibility, with change in the input, would be to use
@backslashchar{}command
instead of
\command
in macro argument.  You need to check if texi2html handles
@backslashchar{}, though, I don't remember.

-- 
Pat

Re: Customizing html file names

[Patrice Dumas]

Hello,

A new version, no functional change, but code could be more clear
like that.

On Mon, Oct 10, 2022 at 09:40:34AM +0200, Patrice Dumas wrote:
> Hello,
> 
> The API changed again, for the new API, the attached init file should be
> ok.
> 
> -- 
> Pat

> # Make the output file names consist of the base name followed by a number.
> use strict;
> 
> # REMARK: if more than one manual is processed, $file_nr, 
> %reference_file_name_file_nr
> # and $after_appendix_printindex should be reset, using a handler
> 
> my $file_nr = -1;
> 
> my %reference_file_name_file_nr = ();
> 
> my $after_appendix_printindex = 0;
> 
> sub filename_simple()
> {
>   my $converter = shift;
>   my $element = shift;
>   my $filename = shift;
>   my $filepath = shift;
> 
>   return ($filename, $filepath) if (defined($filepath));
> 
>   my $prefix = $converter->get_info('document_name');
>   # If we're not splitting, just return the name.
>   if (!$converter->get_conf('SPLIT')) {
> return $prefix.'.'.$converter->get_conf('EXTENSION');
>   }
>   if ($converter->element_is_tree_unit_top($element)) {
> # The table of contents file should be named this.
> return "maxima_toc.html";
>   } else {
> if ($after_appendix_printindex) {
>   return ($filename, undef);
> } else {
>   # FIXME would be more efficient to set it up in a handler (probably 
> 'init')
>   # once for all
>   my $printindex_element = $converter->global_direction_element('Index');
>   if (defined($printindex_element) and $printindex_element eq $element) {
> $after_appendix_printindex = 1;
> return ($filename, undef);
>   }
>   if ($element->{'extra'} and $element->{'extra'}->{'unit_command'}) {
> my $associated_command_element = 
> $element->{'extra'}->{'unit_command'};
> my $sectioning_command;
> if ($associated_command_element->{'cmdname'} eq 'node') {
>   if ($associated_command_element->{'extra'}
>   and 
> $associated_command_element->{'extra'}->{'associated_section'}) {
> $sectioning_command
>   = 
> $associated_command_element->{'extra'}->{'associated_section'}->{'cmdname'};
>   }
> } else {
>   $sectioning_command = $associated_command_element->{'cmdname'};
> }
> if (defined($sectioning_command) and $sectioning_command =~ 
> /appendix/) {
>   $after_appendix_printindex = 1;
>   return ($filename, undef);
> }
>   }
> }
> if (defined($reference_file_name_file_nr{$filename})) {
>   $file_nr = $reference_file_name_file_nr{$filename};
> } else {
>   $file_nr++;
>   $reference_file_name_file_nr{$filename} = $file_nr;
> }
> if ($file_nr == 0) {
>   return ($prefix.'.'.$converter->get_conf('EXTENSION'), undef);
> } else {
>   return ($prefix.'_'.$file_nr.'.'.$converter->get_conf('EXTENSION'), 
> undef);
> }
>   }
> }
> 
> texinfo_register_file_id_setting_function('tree_unit_file_name', 
> \&filename_simple);

# Make the output file names consist of the base name followed by a number.
use strict;

# ./texi2any.pl --split=chapter --no-node-files --html -c OUTPUT_ENCODING_NAME=UTF-8 --force -e 1 --init-file init/examples_init/maxima_file_names.pm --set-customization-variable HTML_MATH=mathjax maxima_init.texi

# REMARK: if more than one manual is processed, $file_nr, %reference_file_name_file_nr
# and $after_appendix_printindex should be reset, using a handler

my $file_nr = -1;

my %reference_file_name_file_nr = ();

my $after_appendix_printindex = 0;

sub filename_simple()
{
  my $converter = shift;
  my $element = shift;
  my $filename = shift;
  my $filepath = shift;

  return ($filename, $filepath) if (defined($filepath));

  my $prefix = $converter->get_info('document_name');
  # If we're not splitting, just return the name.  Note that it should
  # not happen, as in that case the $filepath should be set and the previous
  # condition should also hold.
  if (!$converter->get_conf('SPLIT')) {
return ($prefix.'.'.$converter->get_conf('EXTENSION'),
undef);
  }
  if ($converter->element_is_tree_unit_top($element)) {
# The table of contents file should be named this.
return ("maxima_toc.html", undef);
  } else {
if ($after_append

Re: Customizing html file names

[Patrice Dumas]

On Mon, Oct 10, 2022 at 09:12:40AM -0700, Raymond Toy wrote:
> Thanks for the new version.  I assume this will probably be the API for the
> next texinfo release?

Yes.  I do not think that the API will change again, I think that the
new release is for sometime soon.

>  (I tried to require at least 6.8, but some people
> still want to be able to build the maxima docs with version 5.1 because
> that's what is installed by default on some Ubuntu long-term release.  I
> think 5.1 mostly works, but I don't have anything so old.)

> This also begs the question:  will the current version that I posted
> originally  still continue to work?  (I guess I can try that out myself)

No, it won't work with the upcoming version, the API changed completely.

-- 
Pat

Re: Customizing html file names

[Patrice Dumas]

Hello,

The API changed again, for the new API, the attached init file should be
ok.

-- 
Pat
# Make the output file names consist of the base name followed by a number.
use strict;

# REMARK: if more than one manual is processed, $file_nr, %reference_file_name_file_nr
# and $after_appendix_printindex should be reset, using a handler

my $file_nr = -1;

my %reference_file_name_file_nr = ();

my $after_appendix_printindex = 0;

sub filename_simple()
{
  my $converter = shift;
  my $element = shift;
  my $filename = shift;
  my $filepath = shift;

  return ($filename, $filepath) if (defined($filepath));

  my $prefix = $converter->get_info('document_name');
  # If we're not splitting, just return the name.
  if (!$converter->get_conf('SPLIT')) {
return $prefix.'.'.$converter->get_conf('EXTENSION');
  }
  if ($converter->element_is_tree_unit_top($element)) {
# The table of contents file should be named this.
return "maxima_toc.html";
  } else {
if ($after_appendix_printindex) {
  return ($filename, undef);
} else {
  # FIXME would be more efficient to set it up in a handler (probably 'init')
  # once for all
  my $printindex_element = $converter->global_direction_element('Index');
  if (defined($printindex_element) and $printindex_element eq $element) {
$after_appendix_printindex = 1;
return ($filename, undef);
  }
  if ($element->{'extra'} and $element->{'extra'}->{'unit_command'}) {
my $associated_command_element = $element->{'extra'}->{'unit_command'};
my $sectioning_command;
if ($associated_command_element->{'cmdname'} eq 'node') {
  if ($associated_command_element->{'extra'}
  and $associated_command_element->{'extra'}->{'associated_section'}) {
$sectioning_command
  = $associated_command_element->{'extra'}->{'associated_section'}->{'cmdname'};
  }
} else {
  $sectioning_command = $associated_command_element->{'cmdname'};
}
if (defined($sectioning_command) and $sectioning_command =~ /appendix/) {
  $after_appendix_printindex = 1;
  return ($filename, undef);
}
  }
}
if (defined($reference_file_name_file_nr{$filename})) {
  $file_nr = $reference_file_name_file_nr{$filename};
} else {
  $file_nr++;
  $reference_file_name_file_nr{$filename} = $file_nr;
}
if ($file_nr == 0) {
  return ($prefix.'.'.$converter->get_conf('EXTENSION'), undef);
} else {
  return ($prefix.'_'.$file_nr.'.'.$converter->get_conf('EXTENSION'), undef);
}
  }
}

texinfo_register_file_id_setting_function('tree_unit_file_name', \&filename_simple);

Re: Customizing @var?

[Patrice Dumas]

On Sun, Sep 25, 2022 at 10:18:31PM -0700, Robert Dodier wrote:
> On Sat, Sep 24, 2022 at 2:07 AM Patrice Dumas  wrote:
> 
> > On Tue, Sep 20, 2022 at 04:31:08PM -0700, Raymond Toy wrote:
> > > Is it possible to customize what @var does (for info files) without
> > > redefining @var?
> > > Maxima redefines @var to
> > >
> > > @macro var {expr}
> > > <\expr\>
> > > @end macro
> >
> > This is not recommended, and could even be forbidden, in my opinion, to
> > redefine existing Texinfo @-commands.
> 
> I wonder if you can be more precise about "could even be forbidden".
> Do you mean to say it is allowed (with a warning) by the most recently
> released version of Texinfo, but it might be disallowed in a future
> version? If so, is there any definite plan about that? i.e., in what
> future version is it anticipated that it will become disallowed.

There is currently a warning.  There is no definite plan I know of to
turn the warning to an error, or to disallow completly, for example 
by ignoring the @macro.  But I suggest that you anticipate any future
error or change and replace by a user-defined name.  In the manual, it
is said:

   * It is not advisable to redefine any TeX primitive, plain, or
 Texinfo command name as a macro.  Unfortunately, this is a large
 and open-ended set of names, and the possible resulting errors are
 unpredictable.

That being said, I do not have a solution for the @table argument
issue (and there is a similar issue with @itemize argument).

-- 
Pat

Re: Customizing @var?

[Patrice Dumas]

On Tue, Sep 20, 2022 at 04:31:08PM -0700, Raymond Toy wrote:
> Is it possible to customize what @var does (for info files) without
> redefining @var?
> Maxima redefines @var to
> 
> @macro var {expr}
> <\expr\>
> @end macro
> 
> This breaks things like
> 
> @table @var

One possibility could be to use a macro for @item (I have not checked
with TeX):

@macro itemmyvar {expr}
@item <\expr\>
@end macro

@vtable @var
@itemmyvar my item
body
@item another item without < >
body2
@end vtable

@printindex vr

But it is not the same as having an @-command in argument of @vtable
in the resulting index, as the formatted index entry in @printindex
will have < >, which would not have been the case with a @-command as
@vtable argument.

-- 
Pat

Re: Customizing @var?

[Patrice Dumas]

On Tue, Sep 20, 2022 at 04:31:08PM -0700, Raymond Toy wrote:
> Is it possible to customize what @var does (for info files) without
> redefining @var?
> Maxima redefines @var to
> 
> @macro var {expr}
> <\expr\>
> @end macro

This is not recommended, and could even be forbidden, in my opinion, to
redefine existing Texinfo @-commands. 

> This breaks things like
> 
> @table @var
> 
> So I'm curious if there's some way to customize @var without defining it.

There is @definfoenclose, but it is deprecated.  I just tested that it
leads to a warning, but otherwise formats the output as you expected,
I think.

As a side note, this is documented:

   The '@table' command works with other commands besides those
 explicitly mentioned here.  However, you can only use predefined Texinfo
 commands that take an argument in braces.  You cannot reliably use a new
 command defined with '@macro', although an '@alias' (for a suitable
 predefined command) is acceptable.

It does not seems to me to be a good thing to accept @-commands defined
by @macro as @table argument, for two reasons
* it would not be possible to know if the command should be expanded
  immediatly like macro defined command usually are, or be expanded later
* the use of commands in argument to @table to format table @item is
  done during conversion, and not during parsing, at wihch time
  @-commands defined by @macro have all been expanded.

-- 
Pat

Re: Including files from parent dir

[Patrice Dumas]

On Thu, Sep 15, 2022 at 03:35:26PM -0400, Stefan Monnier wrote:
> > Have you tried the -I  option?
> 
> I had not, but I just tried and that doesn't help: apparently when
> the file starts with "." it's not searched along the list of include
> directories but only relative to pwd (whereas I'd need it to look
> relative to the includer's directory).

When it starts with . ou .. it is not searched for in include
directories, so indeed, it does not help.

-- 
Pat

Re: Including files from parent dir

[Patrice Dumas]

On Wed, Sep 14, 2022 at 10:16:16AM -0400, Stefan Monnier wrote:
> > Right now, I can't think of a way to make this happen.  The only
> > thing I can think of would be to change the code to consider that
> > only paths with leading . are considered differently.
> 
> Actually, from where I stand, what would make more sense is to make it
> so file names that start with . or .. are treated relative to the
> including file rather than searched through the include directories.

This is not so different, as the including file directory is either the
first (if it is the current directory), or the second directory in the
include directories.

-- 
Pat

Re: Including files from parent dir

[Patrice Dumas]

On Tue, Sep 13, 2022 at 08:14:48PM -0400, Stefan Monnier wrote:
> 
> There's something I don't understand about @include:
> 
> Say, I have:
> 
> doc/foo.texi
> doc/gpl.texi
> bar.texi
> 
> if my `foo.texi` has
> 
> @include gpl.texi
> @include ../bar.texi
> 
> I will be able to use successfully both
> 
> cd doc; makeinfo --no-split foo.texi -o ../foo.info
> 
> will work fine, but
> 
> makeinfo --no-split doc/foo.texi -o foo.info
> 
> will signal an error that it can't find `../bar.texi`
> (note: it *did* find `gpl.texi`).
> 
> Why are the two includes treated differently?

It is because includes with leading . or .. in their paths in or include
that are absolute paths are treated differently from other includes:
they are not searched for in include directories.

Also, when you call

 makeinfo --no-split doc/foo.texi -o foo.info

the doc/ directory is included in the @include search path in addition
to the current directory, therefore gpl.texi is found.  The ../bar.texi
include file is still only searched for relative to the working directory.

Unless I missed something, none of these two information is documented.

> How can I convince `makeinfo` to find the `bar.texi` file in both cases?

Right now, I can't think of a way to make this happen.  The only
thing I can think of would be to change the code to consider that
only paths with leading . are considered differently.

-- 
Pat

Re: Customizing html file names

[Patrice Dumas]

On Sun, Aug 14, 2022 at 11:50:12AM -0700, Raymond Toy wrote:
> On Sun, Aug 14, 2022 at 9:46 AM Patrice Dumas  wrote:
> 
> > On Sun, Aug 14, 2022 at 07:18:45AM -0700, Raymond Toy wrote:
> > > For a while maxima has been customizing the html file names that makeinfo
> > > uses.  Basically, the file names are of the form maxima_nnn.html or
> > > maxima_toc.html for the table of contents.
> > >
> > > I would like to be able to change this so that the appendices or indices
> > > don't get a number.  Using the original names makeinfo would have used is
> > > fine.  I don't know how to do that, so some help would be appreciated.
> >
> > A new version, with a proper use of the API for the document_name, with
> > a version that is an update of the code you shown adapted to the current
> > API, and the other is a file that does what you want, if I understood
> > correctly.
> >
> 
> Thank you very much for your help.  But I tried the maxima_file_names_old.pm
> and I get this error:
> 
> makeinfo: warning: error loading
> /home/toy/src/sourceforge/maxima-code/doc/info/es/../texi2html.init:
> Undefined subroutine
> &Texinfo::Config::texinfo_register_file_id_setting_function called at
> /home/toy/src/sourceforge/maxima-code/doc/info/es/../texi2html.init line 42.
> 
> I'm using texinfo 6.8.

The API I ported to is indeed the finished API from the development
version.  Previously, the API was not finished nor documented.  I do
not remember well how it was possible to do things like I did in the
file I sent, it is probably possible, but it is much less practical,
because of the lack of documentation (even for me...).  I would suggest
using the development version if you use the HTML customization allowed
by init files.  If you really can't, I could try to do something, but I
would suggest keeping the existing init files and not doing any change,
waiting for 6.9.

> In case it matters, texi2html.init also has this at the very top, before
> the code you provided:
> 
> $options->{"EXTRA_HEAD"} = '
> https://polyfill.io/v3/polyfill.min.js?features=es6</a>
> >">';

Should become, with the finished API

set_from_init_file('EXTRA_HEAD', '
https://polyfill.io/v3/polyfill.min.js?features=es6</a>
>">');

-- 
Pat

Re: Customizing html file names

[Patrice Dumas]

On Sun, Aug 14, 2022 at 07:18:45AM -0700, Raymond Toy wrote:
> For a while maxima has been customizing the html file names that makeinfo
> uses.  Basically, the file names are of the form maxima_nnn.html or
> maxima_toc.html for the table of contents.
> 
> I would like to be able to change this so that the appendices or indices
> don't get a number.  Using the original names makeinfo would have used is
> fine.  I don't know how to do that, so some help would be appreciated.

A new version, with a proper use of the API for the document_name, with
a version that is an update of the code you shown adapted to the current
API, and the other is a file that does what you want, if I understood
correctly.

-- 
Pat
# Make the output file names consist of the base name followed by a number.
use strict;

# REMARK: if more than one manual is processed, $file_nr and %reference_file_name_file_nr
# should be reset, using a handler

my $file_nr = -1;

my %reference_file_name_file_nr = ();

sub filename_simple($$$)
{
  my $converter = shift;
  my $element = shift;
  my $filename = shift;

  my $prefix = $converter->get_info('document_name');
  # If we're not splitting, just return the name.
  if (!$converter->get_conf('SPLIT')) {
return $prefix.'.'.$converter->get_conf('EXTENSION');
  }
  if ($converter->element_is_tree_unit_top($element)) {
# The table of contents file should be named this.
return "maxima_toc.html";
  } else {
if (defined($reference_file_name_file_nr{$filename})) {
  $file_nr = $reference_file_name_file_nr{$filename};
} else {
  $file_nr++;
  $reference_file_name_file_nr{$filename} = $file_nr;
}
if ($file_nr == 0) {
  return $prefix.'.'.$converter->get_conf('EXTENSION');
} else {
  return $prefix.'_'.$file_nr.'.'.$converter->get_conf('EXTENSION');
}
  }
}

texinfo_register_file_id_setting_function('tree_unit_file_name', \&filename_simple);
# Make the output file names consist of the base name followed by a number.
use strict;

# REMARK: if more than one manual is processed, $file_nr, %reference_file_name_file_nr
# and $after_appendix_printindex should be reset, using a handler

my $file_nr = -1;

my %reference_file_name_file_nr = ();

my $after_appendix_printindex = 0;

sub filename_simple($$$)
{
  my $converter = shift;
  my $element = shift;
  my $filename = shift;

  my $prefix = $converter->get_info('document_name');
  # If we're not splitting, just return the name.
  if (!$converter->get_conf('SPLIT')) {
return $prefix.'.'.$converter->get_conf('EXTENSION');
  }
  if ($converter->element_is_tree_unit_top($element)) {
# The table of contents file should be named this.
return "maxima_toc.html";
  } else {
if ($after_appendix_printindex) {
  return $filename;
} else {
  # FIXME would be more efficient to set it up in a handler (probably 'init')
  # once for all
  my $printindex_element = $converter->global_direction_element('Index');
  if (defined($printindex_element) and $printindex_element eq $element) {
$after_appendix_printindex = 1;
return $filename;
  }
  if ($element->{'extra'} and $element->{'extra'}->{'unit_command'}) {
my $associated_command_element = $element->{'extra'}->{'unit_command'};
my $sectioning_command;
if ($associated_command_element->{'cmdname'} eq 'node') {
  if ($associated_command_element->{'extra'}
  and $associated_command_element->{'extra'}->{'associated_section'}) {
$sectioning_command
  = $associated_command_element->{'extra'}->{'associated_section'}->{'cmdname'};
  }
} else {
  $sectioning_command = $associated_command_element->{'cmdname'};
}
if (defined($sectioning_command) and $sectioning_command =~ /appendix/) {
  $after_appendix_printindex = 1;
  return $filename;
}
  }
}
if (defined($reference_file_name_file_nr{$filename})) {
  $file_nr = $reference_file_name_file_nr{$filename};
} else {
  $file_nr++;
  $reference_file_name_file_nr{$filename} = $file_nr;
}
if ($file_nr == 0) {
  return $prefix.'.'.$converter->get_conf('EXTENSION');
} else {
  return $prefix.'_'.$file_nr.'.'.$converter->get_conf('EXTENSION');
}
  }
}

texinfo_register_file_id_setting_function('tree_unit_file_name', \&filename_simple);

Re: Customizing html file names

[Patrice Dumas]

On Sun, Aug 14, 2022 at 07:18:45AM -0700, Raymond Toy wrote:
> For a while maxima has been customizing the html file names that makeinfo
> uses.  Basically, the file names are of the form maxima_nnn.html or
> maxima_toc.html for the table of contents.
> 
> I would like to be able to change this so that the appendices or indices
> don't get a number.  Using the original names makeinfo would have used is
> fine.  I don't know how to do that, so some help would be appreciated.

Here it is, with a version that is an update of the code you shown
adapted to the current API, and the other is a file that does what you
want, if I understood correctly.

-- 
Pat
# Make the output file names consist of the base name followed by a number.
use strict;

# REMARK: if more than one manual is processed, $file_nr and %reference_file_name_file_nr
# should be reset, using a handler

my $file_nr = -1;

my %reference_file_name_file_nr = ();

sub filename_simple($$$)
{
  my $converter = shift;
  my $element = shift;
  my $filename = shift;

  my $prefix = $converter->{'document_name'};
  # If we're not splitting, just return the name.
  if (!$converter->get_conf('SPLIT')) {
return $prefix.'.'.$converter->get_conf('EXTENSION');
  }
  if ($converter->element_is_tree_unit_top($element)) {
# The table of contents file should be named this.
return "maxima_toc.html";
  } else {
if (defined($reference_file_name_file_nr{$filename})) {
  $file_nr = $reference_file_name_file_nr{$filename};
} else {
  $file_nr++;
  $reference_file_name_file_nr{$filename} = $file_nr;
}
if ($file_nr == 0) {
  return $prefix.'.'.$converter->get_conf('EXTENSION');
} else {
  return $prefix.'_'.$file_nr.'.'.$converter->get_conf('EXTENSION');
}
  }
}

texinfo_register_file_id_setting_function('tree_unit_file_name', \&filename_simple);
# Make the output file names consist of the base name followed by a number.
use strict;

# REMARK: if more than one manual is processed, $file_nr, %reference_file_name_file_nr
# and $after_appendix_printindex should be reset, using a handler

my $file_nr = -1;

my %reference_file_name_file_nr = ();

my $after_appendix_printindex = 0;

sub filename_simple($$$)
{
  my $converter = shift;
  my $element = shift;
  my $filename = shift;

  my $prefix = $converter->{'document_name'};
  # If we're not splitting, just return the name.
  if (!$converter->get_conf('SPLIT')) {
return $prefix.'.'.$converter->get_conf('EXTENSION');
  }
  if ($converter->element_is_tree_unit_top($element)) {
# The table of contents file should be named this.
return "maxima_toc.html";
  } else {
if ($after_appendix_printindex) {
  return $filename;
} else {
  # FIXME would be more efficient to set it up in a handler (probably 'init')
  # once for all
  my $printindex_element = $converter->global_direction_element('Index');
  if (defined($printindex_element) and $printindex_element eq $element) {
$after_appendix_printindex = 1;
return $filename;
  }
  if ($element->{'extra'} and $element->{'extra'}->{'unit_command'}) {
my $associated_command_element = $element->{'extra'}->{'unit_command'};
my $sectioning_command;
if ($associated_command_element->{'cmdname'} eq 'node') {
  if ($associated_command_element->{'extra'}
  and $associated_command_element->{'extra'}->{'associated_section'}) {
$sectioning_command
  = $associated_command_element->{'extra'}->{'associated_section'}->{'cmdname'};
  }
} else {
  $sectioning_command = $associated_command_element->{'cmdname'};
}
if (defined($sectioning_command) and $sectioning_command =~ /appendix/) {
  $after_appendix_printindex = 1;
  return $filename;
}
  }
}
if (defined($reference_file_name_file_nr{$filename})) {
  $file_nr = $reference_file_name_file_nr{$filename};
} else {
  $file_nr++;
  $reference_file_name_file_nr{$filename} = $file_nr;
}
if ($file_nr == 0) {
  return $prefix.'.'.$converter->get_conf('EXTENSION');
} else {
  return $prefix.'_'.$file_nr.'.'.$converter->get_conf('EXTENSION');
}
  }
}

texinfo_register_file_id_setting_function('tree_unit_file_name', \&filename_simple);

Re: Customizing html file names

[Patrice Dumas]

On Sun, Aug 14, 2022 at 07:18:45AM -0700, Raymond Toy wrote:
> For a while maxima has been customizing the html file names that makeinfo
> uses.  Basically, the file names are of the form maxima_nnn.html or
> maxima_toc.html for the table of contents.
> 
> I would like to be able to change this so that the appendices or indices
> don't get a number.  Using the original names makeinfo would have used is
> fine.  I don't know how to do that, so some help would be appreciated.

It should be doable, I will have a look.

How do you split your manual, in general (when split)?

-- 
Pat

Re: texi to epub

[Patrice Dumas]

On Thu, Jun 09, 2022 at 10:20:57AM -0500, Perry Smith wrote:
> Hi,
> 
> I found this thread in the bug-texinfo mailing list[1].  I’m wanting to 
> format the org-mode info file into ePub.  Indeed, I’d like to reformat many 
> of the info files into ePub assuming that I can find a tool chain that works 
> and produces nice results.
> 
> One of the last messages talks about a change but then the thread stops and 
> so I’m left wondering where the current state of the art is with regards to 
> info to ePub processing.  I believe the tact was to first produce valid XHTML 
> and then convert that to ePub perhaps via Calibre or perhaps by another 
> processor — I’m not sure.

It is implemented in the development version that you can take from git.
After installation it should be called with
 texi2any --init epub3.pm mymanual.texi
Any feedback appreciated.

There is a more recent thread on that subject:
 https://www.mail-archive.com/bug-texinfo@gnu.org/msg10445.html

-- 
Pat

Re: makeinfo warnings and errors list

[Patrice Dumas]

On Thu, Apr 21, 2022 at 10:48:50AM +0200, Yannick Sirjean wrote:
> Hi everyone,
> I'm newbie in texinfo system.
> I don't know where to find the warnings and errors list (and the
> description) for the makeinfo program. It's better to know them to
> understand "errors" in the "code".

There is no such description to my knowledge.  The error messages
are in po/texinfo.pot and could be filtered for instance as being in
tp/Texinfo/*.pm tp/Texinfo/*/*.pm.  However, not all the error messages
are useful as is, for example there are messages like "multiple @%s"
or "bad or empty @%s formal argument: %s".

My opinion is that the messages should be auto-documented and should not
need additional explanation, and that a more precise understanding of
the error should only require reading the Texinfo manual to understand
better what's going on.  There is in particular a section in appendix,
"@-Command Syntax" in the manual.

-- 
Pat

Re: texinfo-6.8 html changes

[Patrice Dumas]

On Mon, Mar 14, 2022 at 12:55:59PM +0100, H. Fernandes wrote:
> Hi, 
> 
> Should not the option be to the other way to preserve the default behavior. 

The new behaviour is considered to better for two reasons, one is that
the mini-tocs are considered to have a better usability than menus, menus
where originally there because of the Info output format which has
specific constraints.  The other is that we now allow menus to be
generated automatically in Info, in that case the mini-toc will contain
the same information better integrated in term of formatting.  Therefore
it is considered a better default.

A case where menus can be better is when there are useful descriptions
for menu entries, but we consider that it would not be the default.

-- 
Pat

Re: Loss of search facility in info in newer releases of Texinfo

[Patrice Dumas]

On Mon, Oct 11, 2021 at 02:22:57PM +, Alan Mackenzie wrote:
> 
> Again, I am asking for an option which would give a clean, clear way not
> to output Unicode >0x7f for the Texinfo formatting characters, whilst
> not affecting any of the other facilities for manipulating non-ASCII
> characters.  Are you prepared to implement or accept such a facility?

I must say that I am not thrilled by that prospect, because everyone
could want different classes to be left in ascii.  I think that the
current situation where @documentencoding absence changes the formatting
is problematic and I proposed a simplification to the bug-texinfo
mailing list, but this will definitively not satisfy your need.

To satisfy your need there would be a need to add a customization variable,
for instance DISABLE_PUNCTUATION_ENCODING that would selectively lead to
ascii being output in the resulting file with:
* added quotes as ASCII
* dashes and quotes appearing in the document ``, ---, ' as ASCII
* some brace_no_arg_commands @-commands as ASCII, those that are not
  in the 7bit ascii range and correspond to punctuation, maybe along
  @minus, @dots, @enddots, @quotedblleft, @quotedblright,
  @quoteleft, @quoteright.  Maybe also, but I am not sure, 
  @quotedblbase, @quotesinglbase.

Did I get it right?

-- 
Pat

Re: Loss of search facility in info in newer releases of Texinfo

[Patrice Dumas]

On Mon, Oct 11, 2021 at 08:47:40PM +, Alan Mackenzie wrote:
> 
> I think it is also undocumented that texi2any puts Unicode punctuation
> characters around things like @code{foo}.  It sometimes uses ASCII
> punctuation characters instead.  Which it uses and when, I think is also
> undocumented.  If so, that is also not good.

It is partly documented, but not completly.

> @documentencoding appears to be doing three jobs, which I think really
> ought to be done by separate directives: (i) It specifies the encoding
> used in the .texi file; (ii) It specifies the encoding to be used in the
> ..info file; (iii) It specifies whether to use Unicode or ASCII markers
> around @code{foo}, etc.  I'm not sure it does any of these jobs well.

I agree that (iii) should be unrelated to specifying (i) and (ii).

In texi2any, (ii) can be modified with the customization variable
OUTPUT_ENCODING_NAME.  So (i) only sets the default for (ii) which seems
right to me.

Since we consider input files to be utf-8 when there is no @documentencoding,
it means that the output encoding is utf-8 in the default case too,
which I think is the best as a default nowadays.

-- 
Pat

Re: Possible to set makeinfo options within texinfo file?

[Patrice Dumas]

On Tue, Dec 21, 2021 at 03:05:18PM -0500, Alfred M. Szmidt wrote:
>However, please consider whether it would be better to set this option on
>the command line rather than inside the Texinfo file itself as it may not
>be the best place for controlling details of the output.
> 
> An idea is to add support to makeinfo so that it reads a makeinfo.conf
> file (or equivalent) in the current working directory, which would
> contain all the options a user might want to pass to makeinfo.

It is not documented, but it is possible to use a perl file to set
customization variables.  From my reading of the code the file should be
named Config and is searched for in ., .texi2any, HOME/.texi2any,
$sysconfdir/texi2any and $datadir/texi2any.

In such a file, a customization variable can be set with

texinfo_set_from_init_file('USE_XML_SYNTAX', 1);
texinfo_set_from_init_file('contents', 1);

This is subject to change, though.

-- 
Pat

Re: Transforming XML or other intermediate representation of Texinfo; category system

[Patrice Dumas]

On Sat, Dec 18, 2021 at 06:05:53PM -0800, Robert Dodier wrote:
> Hi Pat, you mentioned it's not clear what I'm trying to do.
> 
> The Texinfo for such items looks like
> 
> @deffn foo (x, y, z)
> 
> Yadda yadda yadda, foo bar baz quux mumble blurf.
> 
> @opencatbox
> @category{Foobar}
> @category{Bazquux}
> @category{Mumbleblurf}
> @closecatbox
> 
> @end deffn
> 
> The easy part is to define @category{Foobar} as a macro which
> substitutes @ref{Category: Foobar, Foobar}. Also easy to define
> @opencatbox / @closecatbox as  /  .

What do you do for other output formats than HTML instead of
 / ?

> The hard part, for which I've concocted some scripts, is to extract
> the set of terms named as categories, and create the list of items
> which are tagged with each category. This is the operation for which I
> would like to inspect a parse tree of the Texinfo document.
> 
> The output of this second part is a bunch of stuff that looks like
> 
> @anchor{Foobar}
> @opencatbox
> @b{Category: Random blurfage}
> @ref{Item: foo, foo}
> @ref{Item: bar, bar}
> @ref{Item: baz, baz}
> @closecatbox
> 
> where foo, bar, and baz are @deffn's or @defvr's which contain
> @category{Foobar}.
> 
> So, in my world of dreams, I would get a parse tree for the document
> containing @deffn foo, etc., look for all the @category doodads, and
> build a lookup table to map categories to items. Then loop over all
> the categories, and emit the @anchor{whatever} and @ref{foo},
> @ref{bar}, etc., for each item claiming to be in category whatever.

You also need an @-command like @printindex, (which I call
@printcategories in the following), to print the categories table?
What is the Texinfo code corresponding to the formatting of this
table after expansion?

(the Texinfo code which generates output in a page like:
https://maxima.sourceforge.io/docs/manual/maxima_370.html
)

> In the current implementation, the stuff about looking for
> @category's, building the lookup table, and emitting the made-up
> Texinfo stuff for the categories is handled by the scripts I
> mentioned.

I see two possibilities to do that.  

In both cases, the texinfo code for categories would be protected
by @verbatim, and then the tree would be modified right after the
parsing, using a custom tree transformation (which is not possible
right now, but could easily be added).  The original code would be like

@verbatim
@opencatbox
@category{Foobar}
@category{Bazquux}
@category{Mumbleblurf}
@closecatbox
@end verbatim

@printcategories would also be protected in @verbatim, like

@verbatim
@printcategories
@end verbatim

The tree transformation code would get the @verbatim content parse its
content as Texinfo, expanding the macros (would probably be simpler if
those macros can operate on a Texinfo fragment and do not need to
operate on the whole document).


For the first possibility, the Texinfo tree corresponding to the parsing
of @opencatbox content would then be examined to get the categories
(presumably using the arguments of the @anchor or @ref @-commands
generated by the macros) and generate a Texinfo tree that can substitute
@printcategories.  This Texinfo tree could either directly be a perl
representation of Texinfo, or be some Texinfo code that is parsed into a
tree.


The second possibility would go through XML, the custom tree transformation
that expands the macros would simply replace @verbatim by another
non regular block Texinfo @-command, for instance with name opencatbox and
would also replace @printcategories @verbatim block by an @-command with
name printcategories.  Then the tree would be expanded as TexinfoXML,
with some code set up to have the TexinfoXML converter consider opencatbox
and printcategories to be regular @-commands.  The next step would be
done in an external tool you would do that starts from the augmented
TexinfoXML generated and that would substitute the opencatbox and
printcategories elements with TexinfoXML regular elements.  Then
txixml2texi would convert back the valid TexinfoXML to Texinfo, which
could then be converted as usual.


> 
> Hope that helps clarify what I'm trying to do, thanks for your interest.
> 
> Robert Dodier
> 
> PS. The scripts for this stuff can be found at:
> https://sourceforge.net/p/maxima/code/ci/master/tree/doc/info/
> namely build_html.sh.in, extract_categories1.sed, and extract_categories1.awk.
> However, I expect that stuff is all pretty much incomprehensible.

Re: Transforming XML or other intermediate representation of Texinfo; category system

[Patrice Dumas]

On Fri, Dec 17, 2021 at 08:37:11PM -0800, Robert Dodier wrote:
> Hi Pat, thanks for your message.
> 
> It doesn't look like the --ifsomething / --no-ifsomething options will
> help. Essentially the problem is that the @ commands which are going
> to end up as HTML need to be kept, without actually processing them
> into HTML. The --ifhtml option wants to process them, but I want to
> postpone that until a later pass.

I must be missing something, as --if* do not process anything, but
rather select what will be processed.  The parser ignores the @if*
sections based on --if* but does not do any processing, it is the
converters that do the processing.  But if you do not want any
conversion nor tree transformations, it is very unclear to me what
you are using texi2any for...

Note that HTML output can be customized through use of perl files that
replace formatting functions used in the default caes.  But it is only
for HTML output and it works on the intermediate tree of perl
structures, so the @macro defined @-commands are already expanded for
instance.

> Likewise with recovering macros from XML, essentially what I need to
> do is generate some stuff (related to the categories referenced in the
> .texi files) and append that to the original .texi, and then process
> the whole thing with makeinfo --html. Ideally I'd like to tell
> makeinfo, "don't do anything, just give me a representation of the
> document for now." Is there a way to tell makeinfo to not expand
> macros?

No, for the reason I said before, without macros expansions, the tree
may not be well formed, so not suitable for the "classical" intermediate
tree of perl structures representation.

> It seems like Texinfo isn't a good fit for the stuff I'm trying to do,
> so I'll just leave the existing aggregation of scripts in place. But
> it has been fun to think about, and maybe I learned a little bit in
> the process.

I feel like I am still missing some basic understanding of what you are
trying to achieve, if it is easy for you to point me at the scripts you
use right now, maybe I could have a look.

-- 
Pat

Re: Transforming XML or other intermediate representation of Texinfo; category system

[Patrice Dumas]

On Wed, Dec 15, 2021 at 09:20:32PM -0800, Robert Dodier wrote:
> Hi Patrice, thanks a lot for your message.
> 
> I looked into the possibility of a Texinfo --> Texinfo XML -->
> mogrifications --> Texinfo pipeline, but it looks like it's not going
> to work. The translation from Texinfo to XML is lossy -- any
> @ifsomething blocks are lost for something != xml.

That could be workaround with --if* on the command line, maybe for each
output format, and --no-ifxml?

> Likewise the
> translation from XML back to Texinfo is lossy -- there doesn't appear
> to be a way to recover macros which are present in the original
> Texinfo and for which I can generate an XML tag; the XML tag (e.g.
> bar) doesn't emit anything in the reconstituted Texinfo
> (@foo{bar} would be ideal, but anyway, nothing is generated).

Indeed, @macro defined @-commands, @value{} and @include are expanded and
cannot be recovered.  However, it is not clear to me why you would want
to keep those, maybe I missed something about your need.  See below an
example, the unexpanded @macro defined @-commands/@value{}/@include may
make the Texinfo not well structured.

> Given that, I can't see a way to treat Texinfo XML as an intermediate
> representation of a document, suitable for transformations, except for
> restricted-enough documents.
> 
> No fault on your part, I don't mean to assign blame or responsibility
> or whatever, just saying that it's too bad, I can't figure out a way
> to make it work. Thanks for your help all the same, I appreciate it.

There is a long term plan to make recoverable @macro defined @-commands,
@value{} and @include too, but it is challenging, so it should take
time.  It also may not be suitable for your need, as @macro defined
@-command may lead to invalid XML, as those defined @-command may be
used to generate well balanced Texinfo but not be well balanced.  For
example

 @macro foo {}
 @example
 @end macro

 @foo{}
 example text
 @end example

It probably does not work in texi2pdf, though.  The plan is more to keep
the information in the intermediate tree in perl, but not directly in
the regular tree, but as additional informations, as the @macro defined
@-command may not follow the tree structure that the final Texinfo document,
obtained after @macro defined @-command expansion always follows.

-- 
Pat

Re: Transforming XML or other intermediate representation of Texinfo; category system

[Patrice Dumas]

On Sun, Dec 12, 2021 at 11:00:12PM -0800, Robert Dodier wrote:
> Hi, I hope all is well with you-all.
> 
> First of all, am I reinventing a wheel here? Is there already an
> implementation of a category system for Texinfo? There wasn't when I
> got started but that was a long time (more than 10 years) ago. I
> searched again today but didn't find anything.

There are categories in Texinfo in the @def* commands but I guess that
it does not correspond to your need as it exists since a long time.

> Assuming there isn't such a system already, I am thinking a cleaner
> way to implement it would be to generate an intermediate
> representation of Texinfo documents, do some transformations on it,
> and then generate the output (info, html, pdf).

texi2any is structured around an intermediate representation.  It reads
texinfo, though the C parser (a pure perl parser exists too) and this
generates a structured intermediate representation of Texinfo documents,
which is a perl structure.  Then the Converters convert this structure
to HTML, Info, simple text, docbook, TexinfoXML, back to Texinfo.  (And,
it is in progress, but there is also a LaTeX converter half done).  But
it cannot directly produce pdf, so it is only for formats output by
texi2any.

> Is it possible to use
> XML as an intermediate representation? I know that one can generate
> XML via --xml -- the crucial step would be to be able to input XML as
> well. Is it possible for makeinfo to read XML as input?

One way to do it would be to use util/txixml2texi.pl to output Texinfo
corresponding to the TexinfoXML generated by texi2any which would
generate Texinfo.  But it needs to be TexinfoXML and not any other
type of XML.

I think that it could be theoretically possible to parse TexinfoXML
directly into a texinfo document structure used internally by texi2any,
using code similar to code in util/txixml2texi.pl, but going through
a texinfo file produced from TexinfoXML instead looks easier to me.

> Failing that, is there any other structured intermediate
> representation (i.e., can be either output or input) of Texinfo
> documents?

The perl structure used internally by texi2any is a structured
intermediate representation.  But I do not know if it would be so
practical for you to manipulate as you need to do it in perl.

The tree is documented in the pod section of tp/Texinfo/ParserNonXS.pm
in the texinfo source, after TEXINFO TREE.
pod2man tp/Texinfo/ParserNonXS.pm | man -l -

There are tree transformations that exist in texi2any documented in
the "Other Customization Variables" node of the Texinfo manual, at
TREE_TRANSFORMATIONS.  But it would only help you the extent that
you want to manipulate the internal texinfo tree before outputting
some output that texi2any can output, such as Texinfo, HTML, or Info,
but not pdf.

It should also be possible to change the HTML output by redefining the
formatting function for @def* and maybe other formatting functions, but
then it would only be for HTML.

-- 
Pat

Re: Bug in dumpdef's documentation

[Patrice Dumas]

On Tue, Oct 26, 2021 at 11:21:39AM -0500, Eric Blake wrote:
> On Tue, Oct 26, 2021 at 02:30:26AM +0200, 4dr14n31t0r Th3 G4m3r wrote:
> > The output documented is not what you get from executing the m4 commands as
> > documented. See https://www.gnu.org/software/m4/manual/m4.html#Dumpdef
> 
> Thanks for the report.  More details would have been nice (what you
> think was wrong, and what you were expecting), but I can reproduce
> that where the manual says:
> 
> dumpdef(`foo')
> error→foo: ⇒
> 
> in practice (given the earlier definition of foo in the example), it should 
> be:
> 
> dumpdef(`foo')
> error→foo:`Hello world.'
> ⇒
> 
> Looking at the source, in doc/m4.texi, there is:
> 
> @example
> $ @kbd{m4 -d}
> define(`foo', `Hello world.')
> @result{}
> dumpdef(`foo')
> @error{}foo:@tabchar{}`Hello world.'
> @result{}
> dumpdef(`define')
> @error{}define:@tabchar{}
> @result{}
> @end example
> 
> My initial guess is that there is a bug in the texi -> html conversion
> where @tabchar{} gets eaten incorrectly, resulting in the html output
> omitting the rest of the intended line.  But checking just now, I see
> the same problem in 'info m4' on the corresponding page, so it is not
> a bug in the conversion, but in the m4.texi source itself.  Earlier in
> the m4.texi, there is:

Is there a true tab character after the @ in the macro?  Or are there
spaces?  I assumed a tab, though it should not change the issue nor the
solution I propose

> @c @tabchar{}
> @c --
> @c The testsuite expects literal tab output in some examples, but
> @c literal tabs in texinfo lead to formatting issues.
> @macro tabchar
> @   @c
> @end macro
> 
> So maybe the problem is that the macro expansion is leaving a bare @c
> which then eats the rest of the line when using the macro within
> @example.

It is indeed what happens, the expansion of the texinfo conserves the
@c. (macro expansion can be tested with the -M option).  So `Hello world.'
and  disappear:

@example
$ @kbd{m4 -d}
define(`foo', `Hello world.')
@result{}
dumpdef(`foo')
@error{}foo:@   @c`Hello world.'
@result{}
dumpdef(`define')
@error{}define:@@c
@result{}
@end example

One possibility is to add an end of line in the macro definition, which
should work for texi2any:

@c @tabchar{}
@c --
@c The testsuite expects literal tab output in some examples, but
@c literal tabs in texinfo lead to formatting issues.
@macro tabchar
@   @c

@end macro

However, this needs to be tested with texi2pdf, as texi2pdf may need
something else.

-- 
Pat

Re: Loss of search facility in info in newer releases of Texinfo

[Patrice Dumas]

On Mon, Oct 11, 2021 at 11:35:06AM +, Alan Mackenzie wrote:
> Hello, Gavin.
> 
> 
> Apologies for not being all that clear in my initial post.  I hope I've
> now made it clear what I'm asking for - as an option, of course.
> --disable-encoding does not do what I want - it squeezes _all_
> characters into the ASCII range, rather than just the Texinfo formatting
> characters.

It does not change the characters in the text, only the characters
formatted by texi2any.  Which conversion is not ok for you with
--disable-encoding?

> > If you remove "@documentencoding UTF-8" from a file, the file is still
> > assumed to be in UTF-8, but less Unicode is used in the output where it
> > is not necessary.  Does that help?
> 
> Not really.  I've got too many info files on my system (Gentoo
> GNU/Linux) to remove that directive from them all each time there's a
> new version of the file.texi.

But does the output obtained when removing "@documentencoding UTF-8"
from the file suit you?

-- 
Pat

Re: Loss of search facility in info in newer releases of Texinfo

[Patrice Dumas]

On Sun, Oct 10, 2021 at 10:18:39AM +, Alan Mackenzie wrote:
> Hello, Jacob.
> 
> I have not yet figured out how to add a new command line option.  I
> envisage the new option being called --enable-utf8-punctuation, with a
> default value of ON.
> 
> So, my question.  Are the maintainers of Texinfo, in principle, willing
> to accept such an enhancement and to include it in future release
> versions?

You can already use --disable-encoding, but it has other consequences
than keeping the literal ` and '.

For simple quoted strings, you should be able to pass

 -c OPEN_QUOTE_SYMBOL=` -c CLOSE_QUOTE_SYMBOL='

(with proper shell script quoting) to set the quotes.  Would that be
enough?

-- 
Pat

Re: Cross-references without a web location

[Patrice Dumas]

On Sat, Sep 18, 2021 at 08:44:19PM -0700, Sarah Morgensen wrote:
> Hello,
> 
> Is there a way to avoid a non-functional link in the HTML output when
> there is no htmlxref.cnf entry for an xref?

The idea behind the specification of the HTML cross references file
destinations, when there is no htmlxref.cnf, is that non split manual
are all in a directory, and split manuals are in the same directoy, each
in its subdirectory.  See the node "HTML Cross-reference Link Basics" in
the Texinfo manual for more informations on that.

For distributions, it is possible to setup an htmlxref.cnf file in
sysconfdir.  It is also possible to use EXTERNAL_DIR customization
variable for the localisation of the manuals directory (though it is
likely not to be practical).

> Working on the GNU Guix manual, I've noticed that there are several
> xrefs for which there is no entry in htmlxref.cnf (because there is no
> published web location for them).  In the HTML output, there is still a
> link, but it redirects to a nonexistent relative url.  For example, a
> reference to the manual "gpm" yields a relative link to "gpm.html",
> which of course doesn't work because we don't publish that manual.

The generated HTML manual cannot easily be changed after it has been
generated.  And the target manual could appear later -- hopefully in
the location guessed by the generated manual.  At least that's what is
assumed by the HTML cross references specification, but if there are
better ideas, we can consider them.

> It would be nice to instead print something closer to what @inforef
> would print, but with the manual title as well.

In HTML @inforef is the same as @xref, with the third argument of
@inforef used as the fourth argument of @xref.  Are you referring to
that formatting of @inforef in HTML, or to some other possibility?

Can you please tell more precisely what you would envision as
* the text of the link
* the url of the link for the href= attribute

Thanks!

-- 
Pat

Re: automatic generation of @menu entries

[Patrice Dumas]

Resending, as for some reason Mike may not be in the recipients...

On Sun, Sep 12, 2021 at 03:09:30PM -0400, Mike Frysinger wrote:
> 
> based on the manual description, it sounds like the tree structure is
> accessible already since that's how the @contents are generated, and
> it's able to output that just fine.  so i (naively) assume that adding
> an automatic menu would be comparable.

As I said in another mail, it is already the case, in Info output a menu
is automatically added if there is none.  Also now, in the default case,
in HTML output the sectioning commands are used for directions, not
menus (default is 'sectiontoc' for FORMAT_MENU).

> > It would also mean the produced menu items will lack the short
> > descriptions, which are produced by a human typing them in Texinfo.
> 
> right, that's why i suggested a new @menudesc to retain that part 

I do not think that it is very relevant to add a separate @-command for
that.  My understanding of the @menu use-case is to allow to have
a control on the formatting of the menu for the Info format, to have
a menu that looks good in plain text, with control on spacing in
particular.  Having a separate @menudesc command would be more in line
with the semantic nature of the Texinfo language, but would see little
use, as, my feeling is that descriptions are not really useful if not
part of a menu.

> (if
> the existing @unnumberedsec and such are insufficient).

Node names are used in menus, not sectioning commands names.  There is
a TREE_TRANSFORMATIONS, insert_nodes_for_sectioning_commands, that uses
sectioning commands to setup nodes automatically using sectioning
commands names, but it is not the default setting.  With
@xrefautomaticsectiontitle and other customization variables
it is possible to use more section names, but in general it is not the
default.

-- 
Pat

Re: automatic generation of @menu entries

[Patrice Dumas]

On Sun, Sep 12, 2021 at 03:09:30PM -0400, Mike Frysinger wrote:
> 
> based on the manual description, it sounds like the tree structure is
> accessible already since that's how the @contents are generated, and
> it's able to output that just fine.  so i (naively) assume that adding
> an automatic menu would be comparable.

As I said in another mail, it is already the case, in Info output a menu
is automatically added if there is none.  Also now, in the default case,
in HTML output the sectioning commands are used for directions, not
menus (default is 'sectiontoc' for FORMAT_MENU).

> > It would also mean the produced menu items will lack the short
> > descriptions, which are produced by a human typing them in Texinfo.
> 
> right, that's why i suggested a new @menudesc to retain that part 

I do not think that it is very relevant to add a separate @-command for
that.  My understanding of the @menu use-case is to allow to have
a control on the formatting of the menu for the Info format, to have
a menu that looks good in plain text, with control on spacing in
particular.  Having a separate @menudesc command would be more in line
with the semantic nature of the Texinfo language, but would see little
use, as, my feeling is that descriptions are not really useful if not
part of a menu.

> (if
> the existing @unnumberedsec and such are insufficient).

Node names are used in menus, not sectioning commands names.  There is
a TREE_TRANSFORMATIONS, insert_nodes_for_sectioning_commands, that uses
sectioning commands to setup nodes automatically using sectioning
commands names, but it is not the default setting.  With
@xrefautomaticsectiontitle and other customization variables
it is possible to use more section names, but in general it is not the
default.

-- 
Pat