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

[Gavin Smith]

On Sun, Mar 17, 2024 at 02:27:11PM +0100, pertu...@free.fr wrote:
> > The code that appears to strip the comment out is very short and probably
> > not the main source of complexity in the Emacs Lisp program:

> I am not sure that it is that code, as texi5 is defined by, I believe
> 
>   let ((texi5 (search-forward " opoint)
> 
> So it should be set as there is a " releases.  I think that the code you flagged out was there to remove the
> CSS or something along for makeinfo <= 4.

I expect you are right.

> My feeling is that the removal of the Copyright comment is
> inentended, as it is left in HTML files split by node.  I believe it is
> rather because of the following that deletes everything between the
> first meta, which should be
>   
> and :
> 
> (search-forward "")
> (delete-region opoint (match-beginning 0))
> (search-forward "\n")
> 
> But it is more a wild guess.
> 
> -- 
> Pat

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

[Gavin Smith]

On Sat, Mar 16, 2024 at 05:48:39PM +0200, Eli Zaretskii wrote:
> > Date: Sat, 16 Mar 2024 16:13:35 +0100
> > From: pertu...@free.fr
> > Cc: gavinsmith0...@gmail.com, ar...@aarsen.me, help-texinfo@gnu.org
> > 
> > On Sat, Mar 16, 2024 at 04:49:11PM +0200, Eli Zaretskii wrote:
> > > > Here are my interrogations.  First I have three questions about removed
> > > > HTML in the that look suspicious to me.  I think that it should be
> > > > checked if this is intended, my wild guess is that it is not:
> > > > 1) the Copyright notice in comments at the very beginning is removed.
> > > 
> > > Is it important?
> > 
> > I think so, it is purposely done that way, I believe, and matches with
> > the '(maintain)Copyright Notices' node information:
> 
> The copyright is stated elsewhere anyway, so this is not relevant.

It would be easy enough to add a customization variable to omit the
copyright notice but I don't know if it is worth it.

The code that appears to strip the comment out is very short and probably
not the main source of complexity in the Emacs Lisp program:

(unless texi5
  (search-forward 

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

[Gavin Smith]

On Sun, Mar 17, 2024 at 12:29:01PM +0100, pertu...@free.fr wrote:
> On Sat, Mar 16, 2024 at 09:29:59AM +0200, Eli Zaretskii wrote:
> > If and when we understand the rationale for that code, and you can
> > suggest how to achieve the same with texi2any customizations, I can
> > assure you that we in the Emacs maintenance will enthusiastically
> > consider switching to those customizations.
> 
> Here is a proposal for an init file.  The  placement in split case
> was not that easy to achieve.

Unless I have missed something, nobody has said why the extra 
was being added in the first place, so I don't see the purpose in
adding complicated customization code in Perl to add it, to replace the
complicated post-processing in Emacs Lisp.  It would be the simplest to
eliminate adding the  altogether.

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

[Gavin Smith]

On Sat, Mar 16, 2024 at 03:13:04PM +0100, pertu...@free.fr wrote:

> My last important interrogation is about CSS.  The whole CSS added by
> texi2any is removed, instead of using the possibility offered by the
> command-line.  My feeling is that what is done right now would be better
> achieved either by calling with
>  --css-include=/software/emacs/manual.css
> although it may not lead to the wanted result if there is some
> disagreement between the CSS output bu texi2any and the emacs CSS.
> Another possibility would be to add a file named, for example
> import_emacs_css.css which would only contain
> 
> @import url('/software/emacs/manual.css');
> 
> and use
>   --css-ref=/import_emacs_css.css
> at the command-line.
> 
> I think that it would be better if the texi2any CSS was kept as some is
> important for some features, such as copiable links.  In the CSS file
> https://www.gnu.org/style.css I also noticed that some parts refer to
> classes no longer used, which is ok if old releases are targeted, but
> the new class is not there, which makes wonder if some of the code is
> still needed.

I asked about this in the past:

"Online HTML manuals for Emacs missing important CSS"
https://lists.gnu.org/archive/html/help-gnu-emacs/2023-04/msg7.html

> See for example:
> 
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Misc-X.html#index-_002d_002dbasic_002ddisplay.
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Choosing-Window-Options.html
> 
> There are ¶ (pilcrow) symbols visible indicating copiable links.
> 
> texi2any outputs CSS rules to hide these unless the users moves their
> mouse pointer over the text:
> 
> a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
> span:hover a.copiable-link {visibility: visible}
> 
> However, these rules are missing.  Presumably they are removed when
> the Emacs manuals are built for the web.
> 
> Could I suggest that either these CSS rules not be removed, or that
> they be included in the "manual.css" file referenced by these pages?

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

[Gavin Smith]

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

It is probably better to use customization with options and variables
("data driven") than customization based on writing code that hooks into the
internals ("code driven"), if the former is possible to achieve.  This
is simpler and easier to understand.

For example, I looked at the mentioned code at
https://git.savannah.gnu.org/cgit/emacs.git/tree/admin/admin.el
(the manual-html-fix-* functions) and it is not instantly apparent what
all of the code is supposed to achieve.

Hence, it would be better to try to understand what the Emacs distribution
code is doing to the HTML output and if customization variables and/or
the default output could support this.

The code driven customization is more coupled to internals that
could change, although in theory is more powerful.

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

[Gavin Smith]

On Wed, Mar 13, 2024 at 09:25:44PM +0200, Eli Zaretskii wrote:
> > 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.

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.

> Once again: IME making breaking changes "just because we can" is not
> the best strategy for stable projects.  But I'm not a Texinfo
> maintainer, so my opinions on this probably doesn't mean much...

The change being proposed here wasn't for no reason.

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

[Gavin Smith]

On Tue, Mar 12, 2024 at 10:04:11PM +0100, Arsen Arsenović wrote:
> Hi Eli,
> 
> [my apologies - I did not use a wide reply, so I am reposting this.
>  sorry for the inconvenience]
> 
> Eli Zaretskii  writes:
> 
> > Before making this change, please look at the manuals posted on the
> > GNU Software pages, and see if any of them really needs this.
> 
> Note that this change request originated from inside the project.
> Tobias Burnus asked about it in the context of GCC.  I imagine any
> Texinfo manual (broader than just GNU.org/s/) would benefit (or at least
> not lose anything) also.  I'm not sure I see a downside.

Agreed, I'm not sure why it would differ from one manual to another.

> > Changing such long-standing behavior just because it looks like
> > "redundant" is not the best idea IME, but if no manuals and no
> > browsers use this, maybe it's not as painful as I fear it could be.
> 
> Note that this behavior has been here since GNU Texinfo 6.4, and is
> generally good.  I am only proposing altering the 'Top' node (usually,
> index.html).

As you point out, the page title changed in that version of Texinfo,
as before it was like "Using the GNU Compiler Collection - Top" with
the manual name first.  NEWS entry:

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

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

[Gavin Smith]

On Tue, Mar 12, 2024 at 01:14:19PM +0100, Arsen Arsenović wrote:
> Hello,
> 
> Currently, makeinfo generates HTML  elements that contain a node
> name.  This is good.  However, for the top node, emitting the title name
> is redundant, and should likely be replaced with simply the manual name
> (since the node name 'Top' is uninteresting).
> 
> Specifically, in the example of
> https://www.aarsen.me/~arsen/gcc/ST/gcc.html/ the HTML title is 'Top
> (Using the GNU Compiler Collection)' rather than just simply 'Using the
> GNU Compiler Collection'.  This behavior is desirable on all other nodes
> (e.g. https://www.aarsen.me/~arsen/gcc/ST/gcc.html/Solaris-2-Options.html
> being titled Solaris 2 Options (Using the GNU Compiler Collection
> (GCC))) is good.
> 
> Is there a way to achieve this?
> 
> TIA, have a lovely day.

It seems like a good idea, does anybody have any opposition to making
this change?

Re: My problems on translating a texinfo document to chinese

[Gavin Smith]

On Mon, Feb 12, 2024 at 07:17:37PM +0200, Eli Zaretskii wrote:
> > From: Gavin Smith 
> > Date: Mon, 12 Feb 2024 16:03:19 +
> > Cc: help-texinfo@gnu.org
> > 
> > I started by simply running "xetex emacs.texi" in the files you sent me.
> > I had an error message about nested footnotes:
> > 
> > (./commands.texi 章 2
> > ! Nested footnotes not supported in texinfo.tex, even though they work in 
> > makei
> > nfo; sorry.
> > @footnote ... though they work in makeinfo; sorry}
> >
> > l.49 labeled @key{Alt})@footnote
> > {We refer to @key{Alt} as @key{Meta} for
> > 
> > Inside screen.texi, which is included by emacs.texi before commands.texi,
> > there appears to be an unterminated footnote:
> > 
> >   所选窗口中的光标显示大多数编辑命令生效的位置，称为 @dfn{光标}@footnote{''光标'' 来自字符 @samp{.}，这是 
> > TECO（Emacs的编写语言）中用于访问编辑位置的命令。 许多 Emacs 命令将光标移动到缓冲区中的不同位置;例如，您可以通过单击鼠标按钮 
> > 1（通哦常是左键）将点放置在所需位置。
> > 
> > 
> > Supplying an extra closing brace led the rest of the input to appear in
> > the output "emacs.pdf".
> 
> I see no unterminated footnote in the current development sources.
> Where did you see it, exactly, and in what Emacs version?

This was in the emacs-manual-zh.tar.xz attachment Ralph Lin sent.

Re: My problems on translating a texinfo document to chinese

[Gavin Smith]

On Mon, Feb 12, 2024 at 05:40:24PM +0800, Ralph Lin wrote:
 This is a follow-up for my last email.
> 
> I didn't get your method working with the tex file short-sample-
> zh.texi. 
> 
> The working method is by installing auctex(a emacs package) and
> use Texing options - Xetex engine, then use C-c C-a to compile.
> 
> After that, it complains me about Metric TFM files not found, and
> there are some cross-references and TOC not found.
> 
> I'm actually working on the Emacs Manual(see attached files), and
> by removing @cite, the whole Preface section is now working, but
> the rest of the book can't be printed even with converting dvi to
> pdf.
> 
> Thanks.

On Linux Mint 21.2 I had to install the packages

texlive-lang-chinese
texlive-xetex
fonts-arphic-ukai

(I don't keep these installed usually because of the disk space they
take up.)

I started by simply running "xetex emacs.texi" in the files you sent me.
I had an error message about nested footnotes:

(./commands.texi 章 2
! Nested footnotes not supported in texinfo.tex, even though they work in makei
nfo; sorry.
@footnote ... though they work in makeinfo; sorry}
   
l.49 labeled @key{Alt})@footnote
{We refer to @key{Alt} as @key{Meta} for

Inside screen.texi, which is included by emacs.texi before commands.texi,
there appears to be an unterminated footnote:

  所选窗口中的光标显示大多数编辑命令生效的位置，称为 @dfn{光标}@footnote{''光标'' 来自字符 @samp{.}，这是 
TECO（Emacs的编写语言）中用于访问编辑位置的命令。 许多 Emacs 命令将光标移动到缓冲区中的不同位置;例如，您可以通过单击鼠标按钮 
1（通哦常是左键）将点放置在所需位置。


Supplying an extra closing brace led the rest of the input to appear in
the output "emacs.pdf".

  所选窗口中的光标显示大多数编辑命令生效的位置，称为 @dfn{光标}@footnote{''光标'' 来自字符 @samp{.}，这是 
TECO（Emacs的编写语言）中用于访问编辑位置的命令。 许多 Emacs 命令将光标移动到缓冲区中的不同位置;例如，您可以通过单击鼠标按钮 
1（通哦常是左键）将点放置在所需位置。}

(I just stuck the } on the end but it probably is supposed to appear earlier.)

I suspect the issue with @cite may be due to missing font files.  I found
that @cite changes the font for Chinese text.  For example, the output for

@cite{散文} 散文

looks as in the attached image.

By adding \XeTeXtracingfonts=1\relax to the beginning of the file, I
got the following in the log file:

Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 10.78pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 10.78pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 8.66pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 8.66pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 7.7pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 7.7pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 19.63pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 19.63pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 16.63pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 16.63pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 13.86pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 13.86pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 12.65pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 12.65pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 9.62pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 9.62pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc
Requested font "[NotoSerifCJK-Regular.ttc:2]:mapping=tex-text" at 11.55pt
 -> /usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc
Requested font "[ukai.ttc]:mapping=tex-text" at 11.55pt
 -> /usr/share/fonts/truetype/arphic/ukai.ttc

Hopefully this will help you install the necessary fonts.

Re: My problems on translating a texinfo document to chinese

[Gavin Smith]

On Tue, Feb 06, 2024 at 07:49:57PM +, Gavin Smith wrote:
> On Tue, Feb 06, 2024 at 03:22:59PM +0800, Ralph Lin wrote:
> > As you just said, I checked the texinfo source code, and the "txi-
> > zh" and "texinfo-zh" do exist, but not for the texinfo v6.8 that
> > I'm currently using.
> > 
> > I added those files into the documentation source;
> > 
> > and I run the texi2any command with argument "--pdf", it complains
> > about the lack of XeTeX.
> > 
> > My machine has XeTeX installed alongside TeX Live, but I don't
> > know how to set it up as the default TeX engine.
> > 
> > Thanks.
> 
> Can you try running "TEX=xetex texi2pdf your-manual.texi" or
> "PDFTEX=xetex texi2pdf your-manual.texi"?

Did you get it to work?

I have added a new node to the manual, as it was not well documented
before.  The current draft is below.  Please let us know if there is
anything missing.

19 Printing Japanese and Chinese


Texinfo comes with support files for processing input in the Japanese
and Chinese languages.

   For Japanese, you use the ‘texinfo-ja.tex’ file.  Your main input
file should begin with a ‘\input texinfo-ja’ line, rather than the
standard ‘\input texinfo’.  Use the UTF-8 character encoding as usual.
You must process the files with either XeTeX or LuaTeX.

   For Chinese, you use the ‘texinfo-zh.tex’ file.  Your main input file
should begin with a ‘\input texinfo-zh’ line, rather than the standard
‘\input texinfo’.  Use the UTF-8 character encoding as usual.  You must
process the files with XeTeX.

   For example, you would run ‘PDFTEX=xetex texi2pdf MY-INPUT-FILE.TEXI’
to use XeTeX to produce PDF output.  You may have to install XeTeX (or
LuaTeX), the ‘zhspacing’ package, and/or font packages.

   Neither Japanese nor Chinese is supported with the standard TeX (or
pdfTeX) program, as it cannot support the fonts and thousands of glyphs
needed for these languages.

   The Texinfo distribution comes with a couple of sample files that you
can use to test support for these languages: ‘short-sample-ja.texi’ for
Japanese, and ‘short-sample-zh.texi’ for Chinese.

   For more information on these extensions to TeX, see the XeTeX home
page (https://tug.org/xetex/) and the LuaTeX website
(https://www.luatex.org/).

Re: My problems on translating a texinfo document to chinese

[Gavin Smith]

On Tue, Feb 06, 2024 at 03:22:59PM +0800, Ralph Lin wrote:
> As you just said, I checked the texinfo source code, and the "txi-
> zh" and "texinfo-zh" do exist, but not for the texinfo v6.8 that
> I'm currently using.
> 
> I added those files into the documentation source;
> 
> and I run the texi2any command with argument "--pdf", it complains
> about the lack of XeTeX.
> 
> My machine has XeTeX installed alongside TeX Live, but I don't
> know how to set it up as the default TeX engine.
> 
> Thanks.

Can you try running "TEX=xetex texi2pdf your-manual.texi" or
"PDFTEX=xetex texi2pdf your-manual.texi"?

Re: My problems on translating a texinfo document to chinese

[Gavin Smith]

On Mon, Feb 05, 2024 at 02:48:15PM +, ralphli...@hotmail.com wrote:
> To whom it might concern:
> 
> I have some problems on translating the Emacs manual, a texinfo document, 
> to Chinese.
> 
> Specifically, when I use the following command:
> 
> texi2pdf emacs.texi -o emacs.pdf
> 
> I have following errors:
> 
> Unicode char @u8:找 not defined for Texinfo
> 
> Where "找" is a Chinese character.
> 
> And outputing the documentation in plain text and HTML
> works(theoretically also info), but
> not for everything TeX.

You need the special support file texinfo-zh.tex that comes with Texinfo;
moreover you cannot process your source files with regular pdfetex.  You
have to use XeTeX.  Rather than the first line of the file being

\input texinfo

you must, instead, write

\input texinfo-zh

As well as XeTeX, you may need to install some other packages for
TeX (zhspacing.sty).

Some manuals have been translated into Japanese which is supported the
same way, except it uses texinfo-ja.tex instead of texinfo-zh.tex.
These files are distributed as part of Texinfo.


> 
> and I also added following in emacs.texi:
> 
> @documentencoding UTF-8
> @documentlanguage zh_CN

That should be ok.

> Also I translated txi-en.tex in the Emacs source file to Chinese as
> txi-zh_CN.tex and it is included in the directory of the maunual. A
> brief description is included in the file:
> 
> "This is read when a source document says @documentlanguage zh_CN." 
> 
> but the above output appeared for every Chinese character.

There is already a translation of txi-en.tex, txi-zh.tex, that comes with
Texinfo.

> 
> I tried to read the info manual and found out that using a unicode
> letter requires the use of "@u8{HEX}", which is not the way to go.
> 
> The texinf-ja.tex probably has the answer...

I don't know what that file refers to - there is a file "texinfo-ja.tex"
but you need to use "texinfo-zh.tex".

Re: Command to open info node with these special characters: `'“”

[Gavin Smith]

On Mon, Jan 29, 2024 at 11:34:32PM +, Mekeor Melire wrote:
> Hello,
> 
> Emacs Org-Mode's manual "org" has a chapter called
> 
>   15.3.1 Bibliography options in the “biblatex” and “csl” export
>   processors
> 
> You can find it online here:
> 
>   
> https://orgmode.org/manual/Bibliography-options-in-the-_0060_0060biblatex_0027_0027-and-_0060_0060csl_0027_0027-export-processors.html
> 
> I wonder, which command-line argument do I have to pass to "info" in
> order to jump to this node? Especially, I wonder how to quote the
> special symbols “ and ”. This did not work for me:
> 
>   info '(org)Bibliography options in the “biblatex” and “csl” export
>   processors'
> 
> (Sorry for the confusing newlines.)

Hi Mekeor, I believe you would do

info "(org)Bibliography options in the ``biblatex'' and ``csl'' export 
processors"

The __0027 and __0060 in the URL refer to ASCII apostrophe and backquote.

Normally, Info node names would not have such quoting characters in them
as use of literal quotation marks is unusual in node names.  It would
be more usual to have

@node Bibliography options in the @command{biblatex} and @command{csl} export 
processors

than

@node Bibliography options in the ``biblatex'' and ``csl'' export processors

in the Texinfo source.  I have just checked that the later does not
ouput quotation marks in the Info output.

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

[Gavin Smith]

On Thu, Jan 11, 2024 at 10:03:29PM +0200, Eli Zaretskii wrote:
> > From: Gavin Smith 
> > Date: Thu, 11 Jan 2024 19:46:30 +
> > Cc: pertu...@free.fr, jean.christophe.hel...@traductaire-libre.org,
> > stefankan...@gmail.com, vincent@hotmail.fr, emacs-de...@gnu.org,
> > r...@gnu.org, help-texinfo@gnu.org
> > 
> > > > Although it's not ideal, using cross-reference labels may be the best
> > > > solution.  It would be a temporary solution if the targetted manual
> > > > obtained an English translation later.  Once that is the case, the
> > > > first manual could be updated with the translated node name, so
> > > > "*note Choisir Tampon:(emacs)Select Buffer." becomes
> > > > "*note (emacs)Choisir Tampon::", eliminating the English.
> > > 
> > > You mean, the Info reader should do that?  It would mean that the Info
> > > reader will need to access all its cross-manual links in a node before
> > > it can display the node with or without the English node names.
> > 
> > I meant that the maintainers of the translated document would update it.
> 
> That'd mean whenever a new translated manual is released, the
> translators will need to update all the manuals that cross-reference
> to the newly-released one, and users will then need to update their
> manuals.  Should be possible, of course, but quite a hassle, IMO.

Well, they wouldn't *need* to update the manuals.  The links to the
English node names would still work as long as the translated manual
has the @anchor commands with those node names.

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

[Gavin Smith]

On Thu, Jan 11, 2024 at 09:26:51PM +0200, Eli Zaretskii wrote:
> > The Info output, I believe.  Suppose there is a cross-reference to a node
> > in the Emacs manual, "Select Buffer".  This would appear in Info output
> > as "*note (emacs)Select Buffer::."  The English words "Select Buffer"
> > would appear incongruous surrounded by non-English text.
> 
> But so is "note", and you said we won't (and probably cannot) use
> something else instead.  So English is already there.

Readers of other languages can easily learn to recognize "*note" as a
marker of a cross-reference.  That is much different to a node name
which could be any English text.

> > Although it's not ideal, using cross-reference labels may be the best
> > solution.  It would be a temporary solution if the targetted manual
> > obtained an English translation later.  Once that is the case, the
> > first manual could be updated with the translated node name, so
> > "*note Choisir Tampon:(emacs)Select Buffer." becomes
> > "*note (emacs)Choisir Tampon::", eliminating the English.
> 
> You mean, the Info reader should do that?  It would mean that the Info
> reader will need to access all its cross-manual links in a node before
> it can display the node with or without the English node names.

I meant that the maintainers of the translated document would update it.

Info download service

[Gavin Smith]

On Thu, Jan 11, 2024 at 02:49:12PM +0100, Patrice Dumas wrote:
> 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.

This would be great to have on GNU/Linux distributions that don't install
many Info manuals by default (such as Debian-derived distributions due to
GFDL woes).  Users could opt in to Info manual downloads once, and then
get many uninstalled manuals easily, rather than having to spend time
working out how to install them every time (usually finding the exact
package name needed in the distribution package manager).  Currently,
"info" is not very helpful for manuals that aren't installed, giving
no clue about how to get the manual or even if one exists.

I can imagine that implementing such a thing may have complications,
though.

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

[Gavin Smith]

On Thu, Jan 11, 2024 at 06:09:20PM +0200, Eli Zaretskii wrote:
> > 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.
> 
> Sorry, I don't understand what you are saying.  What do you mean by
> "visible in the output"? which output?

The Info output, I believe.  Suppose there is a cross-reference to a node
in the Emacs manual, "Select Buffer".  This would appear in Info output
as "*note (emacs)Select Buffer::."  The English words "Select Buffer"
would appear incongruous surrounded by non-English text.

It's possible to supply a label for a cross-reference, so it could be
"*note Choisir Tampon:(emacs)Select Buffer.  (Apologies if this is bad
French.)  However, the English text is still visible.  It could be hidden
with Info-hide-note-references in Emacs or similar, but this is not an
ideal situation as the line lengths will be affected in a paragraph.

The problem with translating the node name is that a simple
cross-reference like "note (emacs)Choisir Tampon" would not work if
the manual and node did not exist.   First Info would have to know
the preferred language of the manual to find, and find a manual
"emacs-fr.info".  Then, if the manual does exist, the person
translating the manual may not have used that translation.  If they had
called it "Sélectionner buffer" instead it wouldn't be found.  Any manual
being translated would likely reference several others, many of which
will not have existing translations.  It's not right for a translator
just to make up their own translations of node names for manuals
which haven't been translated yet.

Although it's not ideal, using cross-reference labels may be the best
solution.  It would be a temporary solution if the targetted manual
obtained an English translation later.  Once that is the case, the
first manual could be updated with the translated node name, so
"*note Choisir Tampon:(emacs)Select Buffer." becomes
"*note (emacs)Choisir Tampon::", eliminating the English.

Automatic processing of other translated manuals could make node name
translations easily available.  You could imagine an Emacs command used
by a translator that would look up equivalent node and anchor names in
Texinfo documents, if they exist.  For example, if a translator translates
a file containing "@ref{Select Buffer,, emacs, The Emacs Editor}" and
supposing that emacs-fr.texi did exist with "@node Choisir Tampon" and
"@anchor{Select Buffer}" immediately after, the software could make
the @node name available to use in translating this @ref.  This would
require a translator to have the other translated manuals on their machines,
but you could imagine the same system working on an abbreviated version
of the manuals that solely had @node lines with following @anchor commands.

This all seems to me to be something to be worked out in software used
by translators as well as possibly processes to be followed by translation
teams.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 10:41:11PM +0200, Eli Zaretskii wrote:
> > There's a limit to how many languages one person can read, so they won't
> > need dozens of such directories.
> 
> I was thinking about automatic computation of Info-directory-list, the
> way we have in Emacs now.  That might need to account for directories
> that _might_ exist, but aren't necessarily there on every system.  The
> potential list of language-specific subdirectories _is_ long.
> 
> Having all of the manuals in a single directory with language-specific
> suffixes completely avoids these problems, and will work with the
> current standard Info directory trees without any changes.

If using language suffixes for Info manuals becomes common practice,
in the future we could add support to the standalone Info program to
look for such manuals when following cross-references, dependent on
users' settings.

I'm not insisting that the language suffixes shouldn't be used in
preference to language-specific installation directories, if that's
more convenient or practical, even if the latter way seems to have
some possible advantages.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 10:26:29PM +0200, Eli Zaretskii wrote:
> > From: Gavin Smith 
> > Date: Sat, 6 Jan 2024 19:41:27 +
> > Cc: Eli Zaretskii , stefankan...@gmail.com,
> >  vincent@hotmail.fr, emacs-de...@gnu.org, r...@gnu.org,
> >  help-texinfo@gnu.org
> > 
> > On Sat, Jan 06, 2024 at 01:49:53PM +, Jean-Christophe Helary wrote:
> > > Thinking out loud here, but @node currently requires the node-name 
> > > argument and has next/preious/up optional argument. It seems to me that 
> > > most of the issues would be fixed by adding a fifth argument that acts 
> > > like the cross-references' second argument (online-label). That way, 
> > > node-name can stay as it is and act as the pointer but is displayed as 
> > > "online-label", which is the translated part.
> > 
> > A document author can use @anchor to provide target text for a
> > cross-reference which does not appear in the reader-visible part
> > of the manual.  I don't see that extending the Texinfo language is
> > necessary.
> 
> Do you mean that a translated manual should have an @anchor for each
> @node, where nodes have translated names and the anchors give their
> original names in English?

Yes, exactly.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 09:24:14PM +0200, Eli Zaretskii wrote:
> > It's up to people writing the Texinfo manuals what they put for
> > @dircategory.  In practice it seems that there aren't any well-followed
> > conventions for this so top-level dir files end up quite disorganised.
> > 
> > There are no conventions that I know of for the @dircategory of translated
> > manuals.
> 
> I always thought that utils/dir-example is the de-facto standard of
> the categories which are "blessed" by the Texinfo project.

It was "categories of the Free Software Directory" but that no longer
follows the same structure as it did when that recommendation
was first made.

The Texinfo manual under @dircategory lists a few example categories
which could be used (fairly consistent with what is in util/dir-example)
but at this point it is up to document authors to decide what categories
to use.  They could look at what other documents do or invent their own
categories if none are appropriate.

> In this thread, we are raising the issue of some kind of
> standardization of the categories for translated manuals.  If you are
> saying that you don't think there should be such standardization, then
> I guess we in the Emacs project will come up with our own solutions,
> and the rest of the GNU Project will have to cope with that, since the
> categories we use gets copied to the system-wide DIR files when Emacs
> is installed.

As I said, my personal preference is that categories should be translated,
although it is the decision of the translator in conjunction with the
user community of that language.

> > If desired, users could have a directory containing solely Info manuals
> > in a certain language along with a dir file containing their dir entries.
> 
> That would mean INFOPATH will have to be amended to include such
> directories.  It also means that INFOPATH will eventually include a
> lot of directories, and search for Info manuals might become
> significantly slower.  I'm not sure this is a scalable arrangement.

There's a limit to how many languages one person can read, so they won't
need dozens of such directories.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 03:57:24AM -0800, Stefan Kangas wrote:
> Eli Zaretskii  writes:
> 
> >> If that’s the case, what about using “Translated manuals” for now,
> >> since the number of translated manuals is very low?
> >
> > I'd say the other way around: as long as we have very few
> > translations, keeping them together with the English version is
> > better.
> 
> I'm concerned that they'd get in the way, even if there are only few of
> them.
> 
> How about using something like `Info-streamline-headings' for this:
> 
> - Put manuals under "Translated manuals" for English locales.
> 
> - Move those relevant to the current locale to "Emacs".

> I'd probably take it a step further and completely hide translations (by
> default at least) outside of relevant locales.  We already do basically
> that for the tutorial.

I think it would be a good idea to hide them.  This could be dealt with
by installing translated manuals in a different location.

For example, in my top-level dir node, which I see by running "info",
I have the following lines:

Развој програма
* help2man-sr: (help2man-sr).   Самостално стварање 
  странице упутства.

Розробка програмного забезпечення
* help2man-uk: (help2man-uk).   Програма для 
  автоматичного створення сторінок 
  підручника (man).

软件开发
* help2man-zh_CN: (help2man-zh_CN).
自动手册页生成。

These are of no interest to me as I can't read the languages.  This
could potentially get worse if more manuals were translated and the
translations installed by default in the default Info directories.

Any support for supporting different installation directories for
different languages in Texinfo (or elsewhere, e.g. Automake) depends on
users of manuals in other languages explaining what exactly is needed
to support their use cases.

FWIW there is the following in the TODO file of Texinfo:

* Ideas that will not be implemented:

- Support installation of manuals in different languages, along these lines:
  . support a LINGUAS file or variable saying which subdirs LL in the
source to descend into (under doc/).
  . within each subdir LL, install the info files into $infodir/LL,
and run install-info on $infodir/LL/dir.
  . info (both emacs and standalone) should read $infodir/$LANG/dir
as the first dir file, and likewise read info files first from
$infodir/$LANG, before falling back to $infodir.
  . consider ways to avoid installing images in both places.
In fact, images probably need to be installed in a subdir
$infodir/MANUAL/ in the first place, to avoid conflicts of having
the same image name in different manuals.
  For a test case, see texinfo cvs, with its one translated manual
  (info-fr.texi).
  From Wojciech Polak.
  ... Except, in practice, people just name their manuals with a
  suffix for the language, and that seems to work well enough.  There
  aren't that many manuals even in English, let alone other languages,
  and there are almost no manuals in multiple languages.

The $infodir/LL and $infodir/LL/dir part of this seem like a good idea
to me.  This would require changes in package build and installation
systems (Automake), not necessarily in Texinfo itself.  Since users
can set INFOPATH (or Emacs equivalent) themselves, it is not urgent to
implement special support for language directories per se in 'info'
or 'install-info'.  This could be done once it is clear that people
are actually using installation directories that way.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 01:49:53PM +, Jean-Christophe Helary wrote:
> Thinking out loud here, but @node currently requires the node-name 
> argument and has next/preious/up optional argument. It seems to me that 
> most of the issues would be fixed by adding a fifth argument that acts 
> like the cross-references' second argument (online-label). That way, 
> node-name can stay as it is and act as the pointer but is displayed as 
> "online-label", which is the translated part.

A document author can use @anchor to provide target text for a
cross-reference which does not appear in the reader-visible part
of the manual.  I don't see that extending the Texinfo language is
necessary.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 12:25:55PM +, Jean-Christophe Helary wrote:
> I forgot. If I understand texinfo properly, if the manual name is 
> translated (and if the manual is translated) it is enough that the node 
> name is the same as in the target manual, so either both untranslated, 
> or both translated. So here, the node name only being left in English 
> is not so relevant. What matters most is whether the manual name is 
> translated or not. Am I correct?

You could be translating node names in cross-references to other
manauls that aren't translated yet!  Then how would you know what
exactly the node name should be exactly?

In the case of mutually referrent manuals (a common case), this situation
is impossible to avoid, unless you take on the project of translating
every single referenced manual, and every manual those manuals reference,
and so on, as well as maintaining all of these translations indefinitely.
That is not going to happen.

> Sure, but the situation where that would happen is indeed when there 
> are too few translated manuals to create a “monolingual ecosystem” 
> where manuals all link to each other.
> 
> Supposedly, the user has installed the manual independently and knows 
> that there will be limitations. Just like all web sites have default 404 
> pages and some have redirection, the error does not have to read like 
> a punishment.
> 
> And that can be a first solution before something more elaborate is 
> implemented. But indeed, that depends on how the TexInfo project wants 
> to solve the issue.

What is the issue exactly?  I don't think it has been clearly stated.

> Regarding the translation process, it seems like there are 2 steps here.
> 
> - The first is the translator who is conscious of the external nodes 
>   limitations and keeps all the external nodes in English.
> 
> - The second is preparing the ground to link to her translation by 
>   modifying external nodes in manuals that direct to it.
> 
> Little by little, the discrepancy will disappear and the translated 
> manuals are all properly linked to each other.

More likely that they link to other nodes with their English names, and
then never change them.  You are assuming a consistency of purpose and
action across socially disparate actors that is very unlikely to exist.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 09:37:03AM +, Jean-Christophe Helary wrote:
> >> Also, we will have to translate @node, because they appear in the
> >> Section index. I see that they were kept in English in the SES manual.
> > 
> > If we translate @node names, links from the doc strings and
> > cross-manual links will not work.
> 
> They will if they are translated in the other manuals. That’s what I’m 
> doing in the Emacs manuals at the moment.
> 
> > 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.

One option to account for this is use multiple infodirs, one for each
language.  Each of the infodirs would be on the INFOPATH, in order of
language preference.

Node names would not be translated, so that links to translated nodes
would work, if they became available.  Alternatively, the English node
name could be provided as an @anchor in addition to a non-English node
name.

> 
> 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.
> 
> 
> So instead of a complex look up system, just an error message for links 
> that don’t work should be sufficient. Don’t you think?

That word "just" implies it's easy and straightforward to implement,
which is a risky assumption.

One difficulty that comes to mind is how you tell the difference between
a manual that has not been translated yet, and one which just isn't
installed or or doesn't exist.

> 
> One issue seems to be that nodes have natural language IDs that also 
> appear in the manual. If nodes were just arbitrary IDs associated to a 
> string, like “2.1.2.fr” associated to “Ma section”, while “2.1.2.en” is 
> “My section”, it would be easier to do the lookup and the manual would 
> print the correct string.
> 
> In my current work on the Emacs manual, every time I find a node, I 
> look for it in all the other chapters/manuals and adapt its translation.
> 

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 10:36:28AM +0200, Eli Zaretskii wrote:
> > Would @author be also used for the translator?
> 
> @author is a TeX command and goes into the printed version.  For
> translation, we'd need a separate directive, I think, since a
> translator is not the author.  Again, this is something for the
> Texinfo folks to handle.

The Texinfo manual gives the example

 @author by Jane Smith and John Doe

The word "by" show that the argument of @author does not just have
to be the name of the author.  However, it may be confusing for some
output formats, such as DocBook.  The example in the Texinfo manual:

@titlepage
@title NAME-OF-MANUAL-WHEN-PRINTED
@subtitle SUBTITLE-IF-ANY
@subtitle SECOND-SUBTITLE
@author AUTHOR
@page
...
@end titlepage

yields, in DocBook:

NAME-OF-MANUAL-WHEN-PRINTED
SUBTITLE-IF-ANY
SECOND-SUBTITLE

AUTHOR



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



- and a translator is indeed a collaborator, although a word like "by"
is not part of their name.

In short I doubt it leads to practical problems putting a translator
in an @author line.  If they are clearly stated as a translator, and
not an author, there are no legal or moral problems.

If there are any real problems, these could of course be discussed.

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

[Gavin Smith]

On Sat, Jan 06, 2024 at 04:40:41AM +, Jean-Christophe Helary wrote:
> > I wasn't talking about the manuals.  But even for the manuals there
> > are some issues that need to be considered.  For example: what do we
> > do with the info/dir file for these translated manuals? what should be
> > @dircategory for them -- should it be a separate category, like
> > "Translated manuals", or should it be the same as in the original
> > English manuals?
> 
> 
> I suppose the @dircategory is also what appears in the Emacs info top 
> page under “*Menu:”?
> 
> If that’s the case, what about using “Translated manuals” for now, 
> since the number of translated manuals is very low?

(This is the first email that was CC-ed to help-texinfo@gnu.org and it's
not clear what the discussion is about or what if anything is being
asked, or what the context or history of the discussion is.  Hence,
I find this thread quite hard to follow based on the messages I have seen.)

It's up to people writing the Texinfo manuals what they put for
@dircategory.  In practice it seems that there aren't any well-followed
conventions for this so top-level dir files end up quite disorganised.

There are no conventions that I know of for the @dircategory of translated
manuals.  I think it is fine to translate the category.  For example,
on my system I have a manual "help2man-uk" which is listed with the
category of "Розробка програмного забезпечення", which Google Translate
tells me translates as "Software development".

If desired, users could have a directory containing solely Info manuals
in a certain language along with a dir file containing their dir entries.


> The day when we have a reasonable amount of translated manuals, it will 
> make sense to have them under the original English manuals. I guess it 
> won’t be too difficult to make the change.
> 
> So I guess the info/dir file would list the translated manuals in 
> “Translated manuals” for now.

I don't think that is the best category for non-English manuals as it
is too broad.

> In French that would be
> @author par Ted Zlatanov
> @author traduit en français par Achille Talon

That seems fine to me.

I will read through other messages in this thread and see if I have anything
to add.

Re: Cross-reference for a non-English book

[Gavin Smith]

On Sun, Dec 31, 2023 at 03:08:22PM +0200, Eli Zaretskii wrote:
> We have current-iso639-language, but its value is a 2-letter string,
> the first 2 characters of the locale's name.  So I think this should
> be a new variable, and Info-documentlanguage sounds like a good
> candidate.

Done in commit 85091d47f (2023-12-31).

> > There is the minor question of what to do if a document has more than
> > one @documentlanguage directive, but if that is the case, we can take
> > the first one that occurs, or the last, or none at all, whichever is
> > easiest.
> 
> If this becomes an issue in Info manuals, we could extend the
> Info-documentlanguage variable to have values that are not just a
> single string, but, say, a list of elements of the form
> 
>   (LANG START END)
> 
> where START and END are character positions for the region whose
> language is LANG.  But I'd wait with such complications until they
> become a real problem.

Yes, agreed.  The document language is barely needed for Info output
as it is and multi-language manuals are rare to non-existent.  If
it is a genuine problem then a user could split their document into
separate Info files.

Re: Cross-reference for a non-English book

[Gavin Smith]

On Sun, Dec 31, 2023 at 08:52:20AM +0200, Eli Zaretskii wrote:
> Btw, what exactly does makeinfo produce for cross-references when
> @documentlanguage is not en_US?  Is the "*note" thing still produced,
> or is it replaced by something else?  I'm guessing that "*note" is
> still produced, since the Info readers need that to recognize a
> cross-reference.  And if that is so, then "*note" is still in English,
> isn't it, and thus not very different from "see"?

It is still *note (for @ref and @pxref), or *Note (for @xref).

> And another question: if Emacs is expected to adapt itself to the
> document's language, and for Portuguese produce something like "veja"
> instead, then how can Emacs know what that language is?  The
> @documentlanguage directive leaves no trace in the Info output,
> AFAICT, so what should Emacs do to DTRT here?

You have hit the nail on the head.  makeinfo should be modified to
record the language of the document.  It would be sensible to place it
in the "Local Variables" section at the end of the file.  Currently,
it looks like


Local Variables:
coding: utf-8
End:

Such a section may be recognized by Emacs, too (see Info node
"(emacs)File Variables").

My question is whether the new variable should be "language",
"documentlanguage" or something else.  If Emacs already uses a similar
variable then we could use the same one.

I had a look at the "Language Environments" node in the "emacs" manual
but I doubt that this is what is needed as that is more to do with
character encoding and input methods.

Or perhaps the new variable should have an "Info-" prefix, as in
"Info-language"?

(I am not an Emacs user so may have to be told the obvious.)

There is the minor question of what to do if a document has more than
one @documentlanguage directive, but if that is the case, we can take
the first one that occurs, or the last, or none at all, whichever is
easiest.

Re: How to avoid mini toc in HTML output

[Gavin Smith]

On Sat, Dec 30, 2023 at 06:38:07PM +0100, Patrice Dumas wrote:
> The level could depend on the split option, the document seems to be
> split at sections.

Yes, it appears that the section toc is needed if the nodes are in a
different HTML file, but not needed/wanted if they are in the same file.

One option that does not need any changes to be made to texi2any, or for
an init file to be used (which is difficult for users) is to use
the @subheading command.  So instead of

  @node Daily Workflow
  @section Daily Workflow
  
  ...
  
  @node Automate your image
  @subsection Automate your image
  
  ...

it would become instead


  @node Daily Workflow
  @section Daily Workflow
  
  ...
  
  @subheading Automate your image
  
  ...

This would have the side-effect that "Automate your image" would not
appear in the main table of contents (although the manual in question
doesn't appear to have a detailed table of contents, only a list of
the top-level chapters).  The numbering of the heading would also
disappear (so no "9.5.1") would appear before the heading.

If you needed to link to the subsection/subheading, you would have to
add an anchor:

  @node Daily Workflow
  @section Daily Workflow
  
  ...
  
  @anchor{Automate your image}
  @subheading Automate your image
  
  ...

Do you think this would be an acceptable workaround?

Re: Cross-reference for a non-English book

[Gavin Smith]

On Sat, Dec 30, 2023 at 07:04:52PM +0100, Patrice Dumas wrote:
> On Sat, Dec 30, 2023 at 02:48:17PM +, Daniel Cerqueira wrote:
> > Hi!
> > 
> > I am writing a info book in Portuguese (@documentlanguage pt). The book
> > is totally in Portuguese, except that when I do a cross-reference with
> > @ref , it is adding the text "see ..." before my cross-reference.
> 
> Which output format are you generating?

I wonder if the issue is that it is an Info file that is being displayed
in Emacs, and Emacs is displaying "*note" as "see".  For the other output
formats, @ref would not generate the word "see" (only @pxref might do that,
and @xref would generate "See").

See documentation of "Info-hide-note-references" in the Emacs manual.

https://www.gnu.org/software/emacs/manual/html_node/info/Emacs-Info-Variables.html#index-Info_002dhide_002dnote_002dreferences

Re: @anchor on @item line

[Gavin Smith]

On Sun, Nov 12, 2023 at 07:23:41PM +, Gavin Smith wrote:
> There is actually a problem with @ftable and @vtable.  If you put an
> @anchor on an @item line there, then it is the text of an index entry,
> which is a real problem.

Further to this, if @anchor should be allowed inside @item as long as the
@item is not creaing an index entry, it should also be allowed inside
@defline and @deftypeline (these are new commands), as these do not create
index entries.

I have made a commit today to allow @anchor in @item and also these
other commands, and will also add this change to the release branch so
that if there is ever a 7.1.1 release, this fix will be included.

We may still not want to allow other "non-basic inline" commands
(e.g. @xref) inside @item/@defline/@deftypeline as inappropriate for
one reason or another, but at the moment it seems the easiest way forward
is to allow these.

@anchor used inside @item inside @ftable/@vtable still leads to a warning
if the index is output, just the warning is slightly obscure.

I thought of allowing @anchor as basic inline content, but we would have
to come up with some other mechanism for detecting and warning about
@anchor inside index entries, and there are too many other commands where
we truly should not have @anchors (e.g. @node names, as cross-references
to those nodes would have to have the @anchor in them).  @anchor should
not appear in any context where it does not correspond to a single
position in the output file.

Re: @anchor on @item line

[Gavin Smith]

On Tue, Nov 07, 2023 at 11:29:24AM +0100, Patrice Dumas wrote:
> On Mon, Nov 06, 2023 at 07:29:50PM +0000, 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.

There is actually a problem with @ftable and @vtable.  If you put an
@anchor on an @item line there, then it is the text of an index entry,
which is a real problem.


@node Top

@ftable @asis
@item AA @anchor{xy}
one

@item BB
two

@end ftable

@node Index

@printindex fn

@bye 

This gives the warnings:

test.texi:4: warning: @anchor should not appear on @item line
test.texi:4: @anchor output more than once: xy

The anchor is processed a second time when the index is output.  Adding
further @printindex commands results in the same error being output again.

A warning is also given for @anchor in other index commands, like @cindex,
so this is consistent.

When I have time, I will look at how the warning could be given for
@ftable and @vtable only.

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

[Gavin Smith]

On Sun, Nov 05, 2023 at 11:30:42AM +, Ihor Radchenko wrote:
> However, there is a warning being produced when @anchor is found on the
> same line with an item:
> 
> org.texi:15975: warning: @anchor should not appear on @item line
> 
> The problematic .texi source is
> 
> @table @asis
> @item @samp{OrgOdtStyles.xml} @anchor{x-orgodtstyles-xml}
> This file contributes to the @samp{styles.xml} file of the final ODT
> document.  This file gets modified for the following purposes:
> 
> Here, the @anchor is referring to OrgOdtStyles.xml file and is not
> necessarily linked to the @item itself.
> 
> 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.  It was the case for Texinfo 7.0 too,
as seen in tp/Texinfo/XS/parsetexi/command_data.txt in that release:

item_LINE   line,close_paragraph,contain_simple_textLINE_line   

("contain_simple_text" has now been renamed "contain_basic_inline").

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

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.

Re: Which is the proper command to mark the name of menus and menu items?

[Gavin Smith]

On Wed, Nov 01, 2023 at 02:17:35PM +, Oleander wrote:
> Hello everyone,
> 
> which command do you use to represent input which is based on text
> presented by the system, such as the names of menus and menu items?
> 
> I write documentation for my team at work. When I want to point out that
> an issue should be reported to `group_foo` which also corresponds to the
> name to be selected in the menu of the ticketing program we use, which
> command would you use?
> 
> A) Send this request to @kbd{group_foo}.
> 
> B) Send this request to @samp{group_foo}.
> 
> This html guide
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd recommends
> to nest the  element inside a  element.
> 
> Since Texinfo has @kbd and @samp, does the same thing apply or is @samp
> the correct command?
> 
> Thank you!

I would use @samp, not @kbd, because it is not typed in; the user usually
clicks on the menu items using a pointing device such as a mouse.

I cannot think of a valid reason to put @samp inside of @kbd.

The MDN page you linked describes a possible usage in HTML:

  Nesting a  element inside a  element represents input which
  is based on text presented by the system, such as the names of menus
  and menu items, or the names of buttons displayed on the screen.

and gives the example

  To create a new file, choose the File
  ⇒New Document menu option.

It describes this as "doing some interesting nesting".

However, I do not recommend that you try to be interesting with the
corresponding Texinfo commands.  It seems to me that this is something
that somebody made up but nobody would never know what it meant unless
they went and studied the HTML specifications.

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

[Gavin Smith]

On Tue, Aug 29, 2023 at 08:22:19PM +, Oleander wrote:
> Hello everyone!
> 
> Does texinfo suit other works that are not software-related like sys
> admin documentation, lectures, long essays, fictional/non fictional
> books? From what I've read in the manual so far, it is possible to
> produce some of them but would you recommend it? Chapter 1 states:
> 
> > Texinfo was devised specifically for the purpose of writing software
> > documentation and manuals. If you want to write a good manual for
> > your program, Texinfo has many features which we hope will make your
> > job easier. However, Texinfo is not intended to be a general-purpose
> > formatting program.
> 

There's no reason why Texinfo couldn't be used for books and essays as
these will be mostly plain text with hardly any need for special marking
of text.

Texinfo can be converted to LaTeX so more fine tweaking of the PDF output
is possible, if needed.

> If not, what markup do you prefer for works that are not
> software-related, without missing most of the good things texinfo
> provides?
> 
> Thank you

It's a mystery to me.  I don't really have any recommendations, I'm afraid.
I'm sure there are documentation systems I'm unaware of that people use
for specific purposes.  For example, to my knowledge, nobody ever used
Texinfo to write a motor vehicle maintenance manual or instructions for
using a washing machine.  I'd say use what you are used to and what works
best for your purposes.

Re: texinfo 7.0.3; the main menu is missing in HTML output.

[Gavin Smith]

On Tue, Aug 08, 2023 at 01:17:06PM +, Alan Mackenzie wrote:
> Hello, Gavin.
> 
> On Mon, Aug 07, 2023 at 23:25:42 +0100, Gavin Smith wrote:
> > On Mon, Aug 07, 2023 at 09:16:36PM +, Alan Mackenzie wrote:
> 
> [  ]
> 
> > To get the menus output in HTML, use the FORMAT_MENU variable.  It
> > would look like "texi2any -c FORMAT_MENU=menu my-manual.texi".
> 
> Thanks for such a rapid and helpful reply!  That works!
> 
> I don't think there's a link to this option from the manual section on
> @menu, though.
> 
> [  ]

I've reworded it and added a cross-reference:

--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -2831,9 +2831,10 @@ @node Menus
 @findex menu
 
 @dfn{Menus} contain pointers to subordinate nodes.  In Info output,
-you use menus to go to such nodes.  Menus can be used in HTML output
-but are not used in the default case.  Menus have no role in printed
-manuals or other output formats.
+you use menus to go to such nodes.  @command{texi2any} can output menus in
+HTML output, but does not do so by default
+(@pxref{Other Customization Variables}, under @code{FORMAT_MENU}).
+Menus have no role in printed manuals or other output formats.
 
 Menus are automatically generated by @command{texi2any} when outputting
 Info for nodes followed by a sectioning command, without an explicit

Re: texinfo 7.0.3; the main menu is missing in HTML output.

[Gavin Smith]

On Mon, Aug 07, 2023 at 09:16:36PM +, Alan Mackenzie wrote:
> Hello, help-texinfo.
> 
> In texinfo-7.0.3, my main menu (a long menu starting with @menu and
> ending with @end menu) is not getting output in my HTML output.  This is
> failing to happen even with an older version of my .texi file which
> previously generated an HTML main menu under an earlier version of
> texinfo.
> 
> On page "menus" in the texinfo manual appears:
> 
> "Menus" contain pointers to subordinate nodes.  In Info output, you use
> menus to go to such nodes.  Menus can be used in HTML output but are not
> used in the default case.  Menus have no effect in printed manuals and
> do not appear in them.  Menus are ignored in DocBook output.
> 
> which I find confusing.  The first occurrence of "use" is talking about a
> user using a menu whilst reading an Info document.  The next sentence,
> sadly in the passive voice, says "Menus ... in HTML output ... are not
> used in the default case".  What does this sentence mean?  Who or what is
> doing this "using" and what is the nature of this use?

Yes, the passive voice can be confusing and this text could be reworded.

To get the menus output in HTML, use the FORMAT_MENU variable.  It
would look like "texi2any -c FORMAT_MENU=menu my-manual.texi".

> 
> Does this sentence mean that @menu ... @end menu by default produces no
> output in HTML?  After a long frustrating search, I could find no
> directions to override this default, if that's what it means.
> 
> Please help me get my main menu back again in HTML!
> 
> Thanks!
> 
> -- 
> Alan Mackenzie (Nuremberg, Germany).
> 

Re: texinfo 4.2 missing from ftp?

[Gavin Smith]

On Sat, Jan 28, 2023 at 10:00 PM Gavin Smith  wrote:
>
> On Thu, Jan 19, 2023 at 09:21:59AM +0100, Vitezslav Crhonek wrote:
> > Hi,
> >
> > Releases of texinfo used in Fedora can be found here (texinfo-4.2
> > included):
> > https://src.fedoraproject.org/lookaside/pkgs/texinfo/
> >
> > Given to Fedora guidelines they all should be unmodified. Later releases
> > are stored also with signature file.
>
> Thanks, this is great!
>
> I've had a look and tried to upload to ftp.gnu.org what was missing.
> However, ftp.gnu.org rejects the uploads:

> ...

> What would the thoughts be about doing something similar to get these
> missing releases uploaded: mainly 4.0, 4.2 and 4.3?

(link to thread in January:
https://lists.gnu.org/archive/html/help-texinfo/2023-01/msg00041.html)

Hello Vita and Rob,

I've finally uploaded those three releases to ftp.gnu.org for
historical purposes, using the files from Fedora.

Re: New @link command for plain links

[Gavin Smith]

On Sun, Jul 09, 2023 at 04:20:41PM +0200, Andreas Falkenhahn wrote:
> I don't know if it's related to the new @link command or if it's a general 
> new feature but I've observed the following:
> 
> When using texi2pdf with my old version of texinfo.tex, only the page number 
> of entries in the table of contents was actually clickable and was 
> highlighted using the link colour. 
> 
> With the new version of texinfo.tex almost everything in the TOC is a link 
> now, i.e. chapter index, chapter title and page number of the entries are now 
> clickable and they are all highlighted using the link colour. Since my link 
> colour is defined as dark red my whole table of contents appears in dark red 
> now because everything in the table of contents seems to be a link now. 
> 
> Is there any way to get the old behaviour back for the table of contents?

The more-clickable table of contents was a new feature, before @link was
implemented.

To avoid the table of contents text all changing colour, you could set the
link colour only after the table of contents, thus:

@contents

@tex
\gdef\linkcolor{0.8 0.4 0.4}
@end tex

The table of contents will still be clickable.  There isn't a way to
turn this off.

Re: New @link command for plain links

[Gavin Smith]

On Thu, Jun 29, 2023 at 09:17:18PM +0200, Andreas Falkenhahn wrote:
> Hi,
> 
> I've found a problem now with the new @link command. It happens when using
> constructions like this:
> 
> @example
> @link{One, One}
> Two
> @link{One, Three}
> @end example
> 
> When converting such a texi to pdf, the line "Two", which doesn't have a
> link, uses a different  indentation than the lines "One" and "Three", which
> do have links. Here's a full test file for you to check:

The issue is with the space before the second argument, so the label is
taken as " One" or " Three".  If it had been @link{One,One} and
@line{One,Three} instead the extra space wouldn't have been there.

I have committed a fix in commit 8a467e11c5.  It is still possible that
the space will still appear if the @link command is nested inside some
other construct but we will have to see if that happens in practice.

Re: semantic newlines?

[Gavin Smith]

On Sun, May 21, 2023 at 09:48:13PM +0200, Bruno Haible wrote:
> Hi,
> 
> Diffs of .texi files are often hard to review, because the committer has
> reformatted (refilled) the paragraph.
> 
> The Linux man-pages project has this guidance to avoid this problem (in
> groff -mandoc source, not in .texi files): [1]
> 
> Use semantic newlines
>In the source of a manual page, new sentences should be started
>on new lines, and long sentences should be split into lines at
>clause breaks (commas, semicolons, colons, and so on).  This
>convention, sometimes known as "semantic newlines", makes it
>easier to see the effect of patches, which often operate at the
>level of individual sentences or sentence clauses.
> 
> Has anyone already used this convention for .texi files? Is it a
> good convention to follow?
> 
> Bruno
> 
> [1] https://man7.org/linux/man-pages/man7/man-pages.7.html

I think there is nothing wrong with using this convention if you want
to.  I have considered using this when making changes to Texinfo files
in the past but have felt I needed to "tidy up" the file to have even
line lengths.  It depends on whether you think other people working on
the file in the future will be happy with wildly varying line lengths.

This kind of line breaking may have been more useful when people were
using text editors such as "ed" where it was easier to edit single
lines at a time.  I have sometimes tried to reduce the size of diffs
by not reflowing the text in a paragraph after the affected
text.  For example, if the last line affected ends up as 60 columns
wide, it might look okay in the source to leave the paragraph after
it with a wider fill width, e.g. 72 columns.  This is kind of a
hybrid convention rather than filling everything to the same width
automatically.

Re: New @link command for plain links

[Gavin Smith]

On Wed, May 03, 2023 at 10:52:58PM +0200, Andreas Falkenhahn wrote:
> On 03.05.2023 at 17:39 Gavin Smith wrote:
> 
> > That should be the case already?  The green was just from my example
> > code setting \linkcolor, but if you take that out then it should be
> > the default black.
> 
> Yes, it is black then but I think it doesn't make sense for links to
> default to black because it is the text color so nobody will be able
> to identify links. The @link color should default to the same color
> that is used by @xref by default...

Which is black.  As I said you can change the colour.  I don't want to
change the default from black.  This should be a deliberate choice in
case the PDF is only intended for use on a computer, not for printing.

Re: New @link command for plain links

[Gavin Smith]

On Tue, May 02, 2023 at 07:55:04PM +0200, Andreas Falkenhahn wrote:
> On 04.04.2023 at 23:12 Gavin Smith wrote:
> 
> > I've committed a change to texinfo.tex (2023-04-04.21) to implement
> > a new @link command.  Please try it and see if it is what you want. It
> > is experimental and could change.  If this is a success we could implement
> > it in texi2any as well.
> 
> Finally had time to give this a try and it's working really well. I've tried
> a 1000+ page document with lots of cross references and found no issues.
> 
> I've one wish, though: Could the link color be made to default to the color
> used by @xref? I'd like to avoid hard-coding a color in the texi file
> because the color used by @xref seems to differ between different versions.
> E.g. my older texinfo installation uses some kind of dark red whereas
> a newer version seems to use green instead. So I think it would make sense
> if @link could just use the same color as used by @xref by default.

That should be the case already?  The green was just from my example
code setting \linkcolor, but if you take that out then it should be
the default black.

I plan to implement this in texi2any as well, when I have the time to
do so.

Re: man page rendering speed (was: Playground pager lsp(1))

[Gavin Smith]

On Fri, Apr 07, 2023 at 09:04:03PM +0200, Alejandro Colomar wrote:
> $ time man -w gcc | xargs zcat | groff -man -Tutf8 2>/dev/null >/dev/null
> 
> real  0m0.406s
> user  0m0.534s
> sys   0m0.042s
> 
> But as others said, I don't really care about the time it takes to format
> the entire document, but rather the first 24 lines, which is more like
> instantaneous (per your own definition of ~0.5 s).

Here's a sample comparison of "man" versus "info" on my system
(relevant as help-texinfo@gnu.org is being copied into this
discussion):

$ time info gcc > temp

real0m0.112s
user0m0.085s
sys 0m0.017s
$ ls -l temp
-rw-rw-r-- 1 g g 3.0M Apr  7 20:14 temp
$ time man gcc > temp
troff: :11612: warning [p 111, 6.0i]: can't break line
troff: :11660: warning [p 111, 13.8i]: can't break line

real0m0.620s
user0m1.004s
sys 0m0.114s
$ ls -l temp
-rw-rw-r-- 1 g g 1.2M Apr  7 20:16 temp

I find the startup of "info" to be instantaneous, whereas man pages often
have a noticeable delay.

Doubtless man would have more comparable runtimes were cat pages being used.

Being able to reformat the text for arbitrary widths is of limited use,
in my opinion, as text becomes more unreadable at long line lengths.  I
suppose cat pages could be provided in a series of sensible widths.  (The
same is true in theory for Info, but I've never heard of anybody using
widths for Info output other than the default 72 columns.)

Re: Playground pager lsp(1)

[Gavin Smith]

On Fri, Apr 07, 2023 at 09:36:10AM +0300, Eli Zaretskii wrote:
> This should be possible, but it flies in the face of the feature
> whereby formatted man pages are kept for future perusal, which is
> therefore faster: if the formatted pages reflect the particular size
> of the pager's window, it is meaningless to cache them.
> 
> >   ... Run the command 'sudo make uninstall'.  (If you successfully used
> >   'make install', simply run 'make uninstall'.)  At a minimum, some
> >   directories not particular to groff, like 'bin' and (depending on
> >   configuration) an X11 'app-defaults' directory will remain, as will
> >   one plain file called 'dir', created by GNU Texinfo's 'install-info'
> >   command.  (As of this writing, 'install-info' offers no provision for
> >   removing an effectively empty 'dir' file, and groff does not attempt
> >   to parse this file to determine whether it can be safely removed.)
> >   All other groff artifacts will be deleted from the installation
> >   hierarchy.
> > 
> > Any chance 'install-info' could get savvy as noted above?  (Maybe it
> > already has--I'm running 6.7.0.)
> 
> Why does it make sense to do that?  An "empty" DIR file is not really
> empty: it has instructions at its beginning, which are important for
> newbies.  Also, on well-maintained system, DIR will rarely become
> empty, and if it does, it will soon enough become non-empty again,
> since all the Info manuals installed on the system should be mentioned
> there, and why would we want to imagine a system which has no Info
> manuals at all, not even an Info manual that describes how to use Info
> (which comes with the Texinfo distribution)?

It falls under the same category as the "directories not particular
to groff" mentioned in the instructions.  You want install-info (or
Automake rules) to remove an empty dir file; you could equally claim
that install-info should remove the empty 'info' directory that contains
that dir file.

What are the benefits of removing the file?

Re: A less presumptive .info? (was: Re: Playground pager lsp(1))

[Gavin Smith]

On Thu, Apr 06, 2023 at 11:14:01AM +0300, Eli Zaretskii wrote:
> > The alternative is, of course, bringing HTML up to par feature-wise
> > (wrt. indices etc), but that'd be on the other end of the extreme, where
> > instead of being too easy to parse and lacking important information,
> > it'd be oververbose with and difficult to parse (not that such a thing
> > should not be done too, so that folks using ordinary browsers can enjoy
> > documentation, and so that projects can provide more accessible
> > documentation by the merit of more people having HTML than Info
> > viewers).
> > 
> > WDYT folks?
> 
> Gavin will tell, but AFAIU our plan is to develop js as the means
> towards the goals you mentioned.  That will allow using HTML browsers
> to read Texinfo documentation without losing the functionalities of
> the Info readers we value.  HTML rendering reflows as integral part of
> its workings, so that problem is not an issue if this plan succeeds.

Progress on this issue is described in the TODO.HTML file in the Texinfo
repository.

https://git.savannah.gnu.org/cgit/texinfo.git/tree/TODO.HTML

In short, the main avenue of progress appears to be the documentation
browser using the embedded WebkitGTK browser.

Re: Playground pager lsp(1)

[Gavin Smith]

On Thu, Apr 06, 2023 at 11:11:40AM +0300, Eli Zaretskii wrote:
> How do you find the description of, say, "dereference symbolic link"
> (to take just a random example from the Emacs manual) when the actual
> text of the manual include neither this string nor matches for any
> related regular expressions, like "dereference.*link"?
> 
> The way Info does it is to use the index (which should be present in
> any respectable reference document) to find description of the
> corresponding subject.  The indexing, which is done by the author of
> the document, if it's a good indexing, should include index entries
> that specify subjects the reader could have in mind when he/she is
> looking for this kind of information.
> 
> The corresponding index-searching commands of Info readers are a
> primary means for finding information quickly and efficiently,
> avoiding too many false positives and also avoiding frustrating
> misses, i.e., searches that fail to find anything pertinent.

In the future, there should be a local documentation search driven
by AI algorithms which handles synonyms and rewordings, so that if
the user searched for "dereference", they also found text about
"following a reference" even if the word "dereference" wasn't used.
Think of it like a version of G**gle running on your own machine.
Implementing such a thing is beyond me, though.

Re: Info vs man [was: Playground pager lsp(1)]

[Gavin Smith]

On Thu, Apr 06, 2023 at 08:29:19AM +0200, to...@tuxteam.de wrote:
> > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Info-Format-Specification.html
> 
 
> As a thought experiment: what would it take for that
> reference above to (also) open a local info viewer?
> 
> The technical part is easy: recognize the prefix and
> substitute it. The exciting part is rather: we need some
> rule set to "build" the URLs as the one above which is
> sufficiently stable to build applications on top of that.

It's not possible to do reliably or simply.  Here's an excerpt
from a file in the Texinfo repository (TODO.HTML):

  It was also an issue as to how to get the manual name from a link.
  In recent Texinfo releases, links to other manuals are annotated with the
  "data-manual" attribute.  This solves the problem of getting the manual
  name.
  
  Texinfo manuals are put on the web with a variety of URL formats and
  it is not possible to reliably get a manual name from a URL or even
  to tell if a URL is to a Texinfo manual or to some other webpapge.  It's
  unlikely we could persuade everybody to change their URL formats to
  be something a browser could parse reliably to get the manual name.  Here
  are some examples of URL's and the manual names:
  
  https://www.gnu.org/software/trans-coord/manual/cvs/html_node/ - "cvs"
  https://gmplib.org/manual/ - "gmp"
  http://lilypond.org/doc/v2.22/Documentation/internals/ - "lilypond-internals" 
  
  https://gcc.gnu.org/onlinedocs/gfortran/ - "gfortran"

Re: Playground pager lsp(1)

[Gavin Smith]

On Wed, Apr 05, 2023 at 12:11:44PM +0300, Eli Zaretskii wrote:
> > Date: Wed, 5 Apr 2023 11:03:36 +0200
> > From: to...@tuxteam.de
> > Cc: help-texinfo@gnu.org
> > 
> > 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.

Probably never going to happen IMHO.  "Imagine a world where all
programming languages converge and their users don't notice"...
see how that sounds?

Truth is that there are many historical or technical circumstances
as to why people might use one system or another, and while arguing
about which is better might be fun, it is mostly a waste of time.

I didn't see much relevance of this discussion thread for help-texinfo
other than to denigrate "the GNU guys".

Some points in response to this thread:

* It's possible to have a cross-reference from an Info file to a
manpage - it would look like *Note bash manpage:(*manpages*)bash(1).
But this is not recommended at all.  In fact, it may only work in
the info browser by accident, and not by design.

* info cannot reflow the text to adapt to different display widths.
This is a limitation of the Info format.  It is probably not so
different to the case of man pages, in fact, as they need to be
regenerated from the groff source to get a different width, as Eli
said in his recent message.  The difference is that the groff source
is installed and used by the "man" program, whereas Texinfo source is
not used by the "info" program.


> The future is already here: just use Texinfo manuals for everything.

LOL!

Using @defblock / @linemacro for API documentation

[Gavin Smith]

(switching from help-texinfo to bug-texinfo)

On Mon, Mar 06, 2023 at 10:45:05PM +0900, Jean-Christophe Helary wrote:
> >> I found the example with a nested @def* block interesting:
> >> 
> > 
> >> https://luis-felipe.gitlab.io/texinfo-css/Elements.html#Definitions
> >> 
> > 
> >> It reminded me of this thread:
> >> 
> > 
> >> https://lists.gnu.org/archive/html/bug-texinfo/2022-02/msg0.html
> >> 
> > 
> >> Nested @def* could be a good way to define parameters, return values, and
> >> so on. With the new @defline facility the user could define macros like
> >> @param that expanded to "@defline Parameter".
> > 
> > That would be nice because I think those kinds of nested definitions make 
> > it easier to find the information you're looking for compared to defining 
> > parameters within the paragraphs that explain a given command, procedure, 
> > etc.


Here's an example of how @defline and @linemacro can be used together
to imitate the format of the numpy documentation at
https://numpy.org/doc/1.24/reference/generated/numpy.fft.fft.html#numpy.fft.fft
(numpy was referred to in the previous discussion).

Currently this only works with texinfo.tex.


@linemacro param {param, type}
@defline Parameter @var{\param\} @code{ : \type\}
@end linemacro
@linemacro returns {param, type}
@defline {Return Value} @var{\param\} @code{ : \type\}
@end linemacro
@linemacro raises {exception}
@defline {Exception} \exception\
@end linemacro

@set txidefnamenospace
@clear txicodevaristt

@defblock
@defline Function fft.fft (a, n=@code{None}, axis=@code{-1}, norm=@code{None})  
Compute the one-dimensional discrete Fourier Transform.

@defblock
@param a array_like
Input array, can be complex.

@param n int, optional
Length of the transformed axis of the output.
If @var{n} is smaller than the length of the input, the input is cropped.

@param axis int, optional
Axis over which to compute the FFT.

@returns out complex ndarray
The truncated or zero-padded input.

@raises IndexError
If @var{axis} is not a valid axis of @var{a}.

@end defblock

@end defblock

Re: New style sheet for Texinfo 7.x

[Gavin Smith]

On Sun, Mar 05, 2023 at 03:26:17PM +, Luis Felipe wrote:
> Hi,
> 
> Just sharing a link to version 2.0.0 of my style sheet for documentation 
> generated with Texinfo 7's makeinfo program.
> 
> This new version comes with light and dark color schemes that are activated 
> automatically based on the visual theme selected by the user in their Desktop 
> or Browser.
> 
> Check the project manual, it uses the style sheet:
> 
> https://luis-felipe.gitlab.io/texinfo-css/
> 
> And also check the Version History for more on what's new on this version:
> 
> https://luis-felipe.gitlab.io/texinfo-css/Version-History.html
> 
> I hope you find it useful, and thanks for your work on the Texinfo system.

This looks great, thanks for posting!

CSS can really help with making a manual look approachable, especially
with adjusting the text block width.

Could I suggest that the node navigation header would look better if
it wasn't surrounded in white space?

I found the example with a nested @def* block interesting:

https://luis-felipe.gitlab.io/texinfo-css/Elements.html#Definitions

It reminded me of this thread:

https://lists.gnu.org/archive/html/bug-texinfo/2022-02/msg0.html

Nested @def* could be a good way to define parameters, return values, and
so on.  With the new @defline facility the user could define macros like
@param that expanded to "@defline Parameter".

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

[Gavin Smith]

On Tue, Oct 19, 2021 at 05:14:28PM +, Alan Mackenzie wrote:
> Hello, Gavin.
> 
> On Mon, Oct 18, 2021 at 20:50:50 +0100, Gavin Smith wrote:
> > I will look at the documentation and other issues you raise.
> 
> Thanks!  I'll look forward to that.


Hello Alan, I am not sure if you are still interested in this issue
but I did not see any continuation of this discussion so wasn't aware
if you or others were aware of the outcome.

In Texinfo 7.0 onward, there is a new variable ASCII_PUNCTUATION
(used like 'texi2any -c ASCII_PUNCTUATION=1') which uses ASCII output
in preference to non-ASCII UTF-8 in several contexts: the output
of commands like @samp, the output of ', '', `, ``, -, -- and ---
in output files, and the output of some glpyh commands like @bullet{}.

Currently we are discussing on bug-texinfo changing some defaults
for the output and adding some configuration variables for more
fine-grained control of the output.
https://lists.gnu.org/archive/html/bug-texinfo/2023-02/msg00048.html

Currently, I expect that ASCII_PUNCTUATION will carry on doing what
it does already.

Re: Generalising @def*

[Gavin Smith]

On Sat, Feb 11, 2023 at 08:11:22PM +0100, Patrice Dumas wrote:
> On Sat, Feb 11, 2023 at 11:59:07AM +0000, 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.

OK, I know that dynamically updating command lists or handling
command macro expansion can add a lot of complexity to texi2any.
The next step now is probably to add @defblock to texi2any.

I still don't think that

@defMac{macro1, (arg1@comma{} arg2)}

is a very good syntax, though.  Maybe we could come back to this.

Re: Generalising @def*

[Gavin Smith]

On Sat, Feb 11, 2023 at 11:59:08AM +, Gavin Smith wrote:
> 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

I've committed a change to texinfo.tex for a new command @newdef.  Example
usage:

@defcodeindex bi

@newdef @defbuiltin = Builtin bi
@newdef @defdoodad = Doodad {}

@defblock
@defbuiltin yeah (ok)
@deflinex {Builtinoid} foo (bar)
hello

@defbuiltin something (else)
more

@defdoodad brick
Description of the brick

@end defblock


@heading Builtin Index

@printindex bi

{} is used to signify that the command does not produce index entries.

Note that multiple def lines can occur in a single @defblock.

I used spaces to separate the arguments to @newdef rather than commas
as this seemed easier to implement.  (We could still change this.)
The first argument should be surrounded by braces if it contains a space.

The only existing line commands that use commas are @node and
@definfoenclose (the latter of which should go away at some point).
The others (@synindex, @syncodeindex, @alias) use spaces or have
ad-hoc syntaxes.  The block command @float also takes two optional
arguments, separated by commas.

Optional arguments are not done in a straightforward manner in TeX so
they should be avoided in any new syntax.  

There should also be a @newdeftype command for defining commands that
act like @deftypefnx.  I'm unsure about the best way of doing this; if
in practice the @newdeftype command would be more used than @newdef, then
it should have a shorter name.

Re: Generalising @def*

[Gavin Smith]

On Fri, Feb 10, 2023 at 01:35:17PM +, Gavin Smith wrote:
> With the patch below, the following input outputs as you would expect.
> 
> \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.

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.

It does not cover any of the "object-oriented" commands like @defop, which
are hardly used AFAICT.  Generalising these would require feedback from
users.  (The groff manual says which package macros come from in the
index and packages and object classes are both namespaces so could be
treated together.)

There's also the "tagging" proposal:
https://lists.gnu.org/archive/html/help-texinfo/2021-12/msg9.html
https://lists.gnu.org/archive/html/bug-texinfo/2022-08/msg00106.html

This can be delayed until after Texinfo 7.1 and would also need
more discussion with potential users.

Re: Generalising @def*

[Gavin Smith]

On Fri, Feb 10, 2023 at 04:24:00PM +0100, Patrice Dumas wrote:
> 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 
> > 

The idea was that the user could define a macro to output a @deflinex
command as well as an index command.  For example,

@defcodeindex mc

@macro defMac{name, args}
@mcindex \name\
@deflinex Macroid \name\ \args\
@end macro

@defblock
@defMac{macro1, (arg1@comma{} arg2)}
@defMac{macrob, (arg4@comma{} arg5)}
Description of @code{macro1} and @code{macrob}
@end defblock

@heading Macro Index

@printindex mc

This is still not that good, though, as being able to write

@defMac macro1 (arg1, arg2)

instead would be much better.

Maybe there could be a special-purpose macro facility for defining
new definition commands that would allow the command to be invoked
without braces.

Re: Generalising @def*

[Gavin Smith]

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.

\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: @defun and @defvr in the "same" block?

[Gavin Smith]

On Mon, Nov 21, 2022 at 11:37:10AM -0800, Raymond Toy wrote:
> I'm converting some old documents written with Scribe.  The conversion is
> pretty straightforward since the syntax between Scribe and Texinfo are
> really pretty close.
> 
> 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}]
> @f[check-region-query-size] counts the lines in @i[region], and if their 
> number
> 
> 
> 
> @enddefun

For what it's worth, I downloaded the source for the manual following
the instructions at https://www.cons.org/cmucl/hemlock/index.html to
look at it.

@defun and @defhvar were not builtin Scribe commands as far as I can tell.
They are not mentioned in any of the documents about Scribe I've been
able to see.

In the Hemlock sources they are defined under src/database/hem.lib,
src/database/dbolio.lib and other files, apparently to use the same features
as Bolio.  (I believe that "Dover" in these files refers to a model of
printer.)

Scribe seems to have been a very large influence on Texinfo but the
definition commands appear to have come from Bolio.

Re: Is it possible to create named links?

[Gavin Smith]

On Sun, Feb 05, 2023 at 01:44:22PM +0100, Andreas Falkenhahn wrote:
> Hi,
> 
> I'm wondering if it's possible to create named links in Texinfo documents. I 
> want to define the text and the target node for the link. E.g. I want to 
> define a link which appears as "Click here" in the PDF and when it is 
> clicked, it jumps to a specified node. Is that possible?
> 
> The only way to create links I've found is to use the @xref directive but 
> this always generates additional pre-defined text so it's not possible to 
> specify a custom label for the link, e.g.
> 
> @xref{node,,Click here}
> 
> appears as
> 
> See Section XX [Click here], page XX, for details.
> 
> in the PDF. So it's not possible to just have "Click here" or any other 
> custom text as the link text. It'll always appear as the whole "See 
> Section" shebang in the PDF.
> 
> Is it possible to embed custom-named links without that pre-defined "See 
> Section..." in the PDF in any way?

The best I can work out is the following:

@set txiomitxrefpg
 
@ref{node,, Click here}

'txiomitxrefpg' is an undocumented flag to omit the "page XX" part,
and using @ref instead of @xref omits the leading "See".  So what you
get is

 Section XX [Click here] for details.

instead.

I'm sure you're aware this this would be no use if this part of the
manual were printed on paper.

I'm open to the idea of adding a "plain cross-reference" command as
it is a frequently-requested feature:

  "If you really want a plain link in HTML output without affecting
  other output formats, you could create a macro with conditional
  definitions for each output format."

(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Info-Format-FAQ.html)

However, it doesn't appear to be possible for PDF as you found,
and people don't like writing Texinfo @macro's (using @macro's is
not particularly recommended, either).

I imagine the new command would be something have the same syntax as @ref
and do nothing for Info output where *note markers are needed.

Some ideas for the name:
@rf   - like @ref but shorter (but looks like a font command)
@x- short for cross-reference
@plainref - self-explanatory, but name is too long
@pref - stands for "plain reference", but would be confused with @pxref
@link - purpose is immediately obvious but unlike other ref commands

I'm favouring @x or @link but think @link would be better as manual
sources strewn with @x (or some other very short command) would be
forbidding for language newcomers.

Re: Generalising @def*

[Gavin Smith]

On Thu, Feb 02, 2023 at 07:14:53PM +, Gavin Smith wrote:
> Yes, we couldn't use @deffn.  I am thinking perhaps just @def which
> would be like the \defheaderline macro that you've already discovered
> in texinfo.tex.

On second thoughts, @def clashes badly with \def in TeX, so there's no
way we could add a Texinfo command called @def...  @defline or @defheaderline
would be ok.

Re: Generalising @def*

[Gavin Smith]

On Tue, Jan 31, 2023 at 09:42:20PM +0100, Arsen Arsenović wrote:
> Consider also a language like Poke, which does not have the usual
> type-name-args syntax, instead opting for ``fun name = (args) type:
> {...}'' for functions, and similarly, ``method name = (args) type:
> {...}'' for methods.  It makes me think that this command should somehow
> (perhaps via a macro-like body) describe the format of the "definition
> line".
> 
> It is very important for language documentation, I feel, to establish
> typesetting convention that is close to what the language looks like.

Yes, I agree.

> 
> > Maybe also an argument for the font style of the indexed symbol itself?
> >
> > There could be behind the scenes commands like @def making @defbuiltin
> > equivalent to '@def defbuiltin, typed, tt, Built-in Function, fn'.
> 
> This seems reasonable to me.
> 
> > There may be other possibilities, such as using @macro in some way, e.g.
> > using a @macro definition to define a new definition command.
> >
> > The groff manual does things like
> >
> >   @macro Defstr{name, package}
> >   @deffn String @t{\\*[\name\]}
> >   @stindex \name\ @r{[}\package\@r{]}
> >   @c
> >   @end macro
> >

> > Hence, using
> > a @macro would provide more flexibility.  Maybe a macro could be
> > "blessed" into a definition command somehow?
> >
> >   @newdef defstr = Defstr
> >
> > providing @defstr, @defstrx and @end defstr.  The @Defstr would provide
> > the printing of the definition line and indexing and the new commands would
> > take care of the indented block.
> 
> Ah!  I see you've thought about that too.  This might be nicer than my
> original thought of simply attaching a body below the @newdef.  I'm
> curious, what would the definition of Defstr look like?  Especially
> considering @deffn already has some meaning, which might be
> inappropriate for some cases (like the Poke example above).

Yes, we couldn't use @deffn.  I am thinking perhaps just @def which
would be like the \defheaderline macro that you've already discovered
in texinfo.tex.  It would look like

  @macro Defstr{name, package}
  @stindex \name\ @r{[}\package\@r{]}
  @def String, @t{\\*[\name\]}
  @end macro
  
  @newdef defstr = Defstr

The first argument to @def would give the category and the second
the prototype or declaration of the symbol.

One complication is that e.g. @defstr would be a block command,
whereas @defstrx would just be a line command.  A new command @def
for printing the definition line couldn't be a block command as it
wouldn't work for @defstrx.  The same @macro would be used for
both of them.  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.

This would make the two following excerpts equivalent:

  @defstr somename, some package
  @defstrx somename2, some package2
  text here
  @end defstr

and

  @defblock
  @stindex \somename\ @r{[}\package\@r{]}
  @def String, @t{\\*[\somename\]}
  @stindex \somename2\ @r{[}\package2\@r{]}
  @def String, @t{\\*[\somename2\]}
  text here
  @end defblock


This seems to be shaping up into an actionable proposal.

I guess we should consider at the same time if there are other
contexts where users might want to define new block commands.


> I like the direction here.  I posted just a few quick remarks, and I
> haven't had proper opportunity to consider options for the syntax, or
> what would fall into the variables that need to be abstracted for the
> general case to work, though, so my thoughts are incomplete.
> 
> Thanks, have a great night.

It would be good to find manuals like the groff or gcc manuals which
do things like defining their own @def-style commands and check what
they need.

Generalising @def*

[Gavin Smith]

On Thu, Dec 15, 2022 at 09:17:43PM +, Gavin Smith wrote:
> I've commited a change for an experimental feature to allow this.  This
> is in texinfo.tex version 2022-12-15.20 (in git).
> 
> Example code:
> 
> \input texinfo
> 
> @defcodeindex xy
> 
> 
> @defun Foo (bar)@useindex{xy}
> foobar
> @end defun
> 
> @printindex xy
> 
> @bye
> 
> This puts the index entry in the 'xy' index rather than the
> 'fn' index.
> 
> This has not been implemented in texi2any at all and the syntax, name
> of the @useindex command, etc. could all change, or the feature might
> not be implemented at all if there is no use for it.  Please experiment
> and report what would be useful.

I'm still not really happy with this syntax.  @useindex should occur
at the end of the line, which is not very obvious, and it's not clear
what happens to whitespace before or after it.

The @useindex syntax above is a kind of "named argument" or HTML-style
attribute.  The only precedent for this in Texinfo may be the in-index
commands, like @sortas.  However, the index commands are pretty complicated
to implement with interactions with @subentry, so may be a special case
that shouldn't be generalised.

(@caption also provides a sort of named argument to the @float command
(in an XML-like syntax it would be like ),
but @float is a block command, whereas additional named arguments
or attributes need to be on the line, to allow them to be passed
differently to e.g. @deffn and @deffnx in a single block.)

I wonder if it would be better to make it simply a different command,
like

  @defunext xy, Foo (bar)

which takes an extra argument.  This might be more in line with existing
Texinfo syntax.  (But would double the number of @def* commands, which
are already very numerous.)

This would be fine provided we didn't need to add more
arguments in the future...  So perhaps we need new commands
which are as general as they can possibly be.

We should also resolve the question, at last, of how users should create
their own def command, which is something that several people have wanted
to do in the past.  Using @macro for this isn't really good enough, as it's
hard for the user to use properly.

We could have arguments saying whether the definition line should
be in a typewriter font (like @deftypefn) or a slanted roman font
(like @deffn) by default; and whether there is a type before the
indexed symbol (like @deftypefn).

Imaginary use case:

  @newdef defbuiltin = typed, tt, Built-in Function, fn

which would define @defbuiltin, @defbuiltinx and @end defbuiltin.

Imaginary syntax:

  @newdef COMMAND = (typed|untyped), (tt|slanted), CATEGORY, INDEX

Maybe also an argument for the font style of the indexed symbol itself?

There could be behind the scenes commands like @def making @defbuiltin
equivalent to '@def defbuiltin, typed, tt, Built-in Function, fn'.

There may be other possibilities, such as using @macro in some way, e.g.
using a @macro definition to define a new definition command.

The groff manual does things like

  @macro Defstr{name, package}
  @deffn String @t{\\*[\name\]}
  @stindex \name\ @r{[}\package\@r{]}
  @c
  @end macro

which puts the text "package" in the index, even though it doesn't
actually appear in the text of the @deffn line itself.  Hence, using
a @macro would provide more flexibility.  Maybe a macro could be
"blessed" into a definition command somehow?

  @newdef defstr = Defstr

providing @defstr, @defstrx and @end defstr.  The @Defstr would provide
the printing of the definition line and indexing and the new commands would
take care of the indented block.

Such macros could take advantage of new @def command(s) that didn't make
index entries.

Comments and ideas sought.  I hope we can come up with a good and practical
plan that will serve all relevant use cases now and in the future.

Re: texinfo 4.2 missing from ftp?

[Gavin Smith]

On Thu, Jan 19, 2023 at 09:21:59AM +0100, Vitezslav Crhonek wrote:
> Hi,
> 
> Releases of texinfo used in Fedora can be found here (texinfo-4.2
> included):
> https://src.fedoraproject.org/lookaside/pkgs/texinfo/
> 
> Given to Fedora guidelines they all should be unmodified. Later releases
> are stored also with signature file.

Thanks, this is great!

I've had a look and tried to upload to ftp.gnu.org what was missing.
However, ftp.gnu.org rejects the uploads:

file rejected: texinfo-4.0.tar.gz contains a vulnerable Makefile.in
CVE-2009-4029
Regenerate it with automake 1.11.6 / 1.12.2 or newer.

and

file rejected: texinfo-4.2.tar.bz2 contains a vulnerable Makefile.in
CVE-2009-4029
Regenerate it with automake 1.11.6 / 1.12.2 or newer.

file rejected: texinfo-4.2.tar.bz2 contains a vulnerable Makefile.in
CVE-2012-3386

Regenerate it with automake 1.11.6 / 1.12.2 or newer.

This was also the case with a few old versions I uploaded to
ftp.gnu.org in the past.  In texinfo-4.1.tar.gz on ftp.gnu.org,
uploaded 2020-11-07, I added a file in the top directory, "ORIGIN":

Makefile.in was edited to allow upload of this file, due to the
following errors:

file rejected: texinfo-4.1.tar.gz contains a vulnerable Makefile.in
CVE-2009-4029
Regenerate it with automake 1.11.6 / 1.12.2 or newer.

file rejected: texinfo-4.1.tar.gz contains a vulnerable Makefile.in
CVE-2012-3386
Regenerate it with automake 1.11.6 / 1.12.2 or newer.

The original file is identifiable with

$ md5sum texinfo-4.1.tar.gz
552a0c428eddad61bab99c56f6dbeda5  texinfo-4.1.tar.gz

as well as an extra file Makefile.in-ORIG containing the original version,
with the differences:

$ diff Makefile.in{-ORIG,}
324c324
<   -find $(distdir) -type d ! -perm -777 -exec chmod a+rwx {} \; -o \
---
>   -find $(distdir) -type d ! -perm -755 -exec chmod a+rwx {} \; -o \
339c339
< # chmod -R a-w $(distdir); chmod a+w $(distdir)
---
> # chmod -R a-w $(distdir); chmod u+w $(distdir)


~~~ Question ~~~ 

What would the thoughts be about doing something similar to get these
missing releases uploaded: mainly 4.0, 4.2 and 4.3?

For Texinfo 4.0 onwards, missing are

4.0 (on Fedora)
4.2 (on Fedora)
4.3 (on Fedora)
4.4 (not on Fedora - according to NEWS file 4.5 only has a few changes
 over 4.4 so 4.4 may not be that historically important)
4.5 we only have .tar.gz but Fedora has .tar.bz2

I have copies of old release notices, but unfortunately, not of checksums.

I have not tried to upload texinfo-4.0b.tar.bz2 as this appears to have been
a pretest release (one of several with letter suffixes) so seems less
important.

Texinfo history before 4.0 gets murkier.  I have some 3.* (and even
2.* releases) uploaded to https://ftp.gnu.org/gnu/texinfo (again,
reuploads in 2020).  In 3.*, missing are:

3.2
3.3
3.4
3.5
3.6
3.7
3.8
3.11
3.12

Diffs for some of these 3.* releases were allegedly available at
ftp.gnu.org; however, were taken down in 2003 following a security
breach; see https://ftp.gnu.org/MISSING-FILES.README

Here is the full list of missing Texinfo related files from
https://ftp.gnu.org/MISSING-FILES :

./gnu/texinfo/texinfo-3.4-3.5.diff.gz
./gnu/texinfo/texinfo-3.5-3.6.diff.gz
./gnu/texinfo/texinfo-3.6-3.7.diff.gz
./gnu/texinfo/texinfo-4.0-4.1.diff.gz
./gnu/texinfo/texinfo-4.1-4.2.diff.gz
./gnu/texinfo/texinfo-4.2-4.3.diff.bz2
./gnu/texinfo/texinfo-4.2-4.3.diff.gz
./gnu/texinfo/texinfo-4.3-4.4.diff.bz2
./gnu/texinfo/texinfo-4.3-4.4.diff.gz
./gnu/texinfo/texinfo-4.4-4.5.diff.bz2
./gnu/texinfo/texinfo-4.4-4.5.diff.gz
./gnu/texinfo/texinfo-4.5-4.6.diff.bz2
./gnu/texinfo/texinfo-4.5.tar.bz2
./gnu/texinfo/texinfo-4.5.tar.gz

It's not clear how widespead the Texinfo 2.* releases were and many of them
are described as beta releases in the NEWS file.  The oldest version I've
got, Texinfo 2.15, has the following text in the "New-features" file:

  The Texinfo 2 package is temporary; after a period of testing, the new
  documentation and software will be merged into the Emacs distribution.

Before that Texinfo-related files were all part of GNU Emacs.

Re: Defining convenience wrapper for @def... categories

[Gavin Smith]

On Fri, Jan 20, 2023 at 11:01:03PM +0100, Arsen Arsenović wrote:
> >> What's the idiomatic way to make such an alias?  Is there any currently?
> >
> > I don't know if this counts as idiomatic or recommended, just that there
> > doesn't seem to be any other better way of doing it.
> 
> This seems to work like a charm, so as long as it's not exploiting some
> bug/UB, it should be fine.

No, it is not undefined behaviour or a bug.

> BTW, I noticed that here, like with @ftable's @itemx, each "alternative"
> becomes a separate index target, at least in HTML and Info.  I'm
> thinking of implementing a transform that "bubbles" @\([-a-zA-Z]\)*x
> indices to their respective @\1, do you think these should get the same
> transform?

I don't know about the details but it would make sense for an entire
@item/@itemx block to have the same target.

Re: Defining convenience wrapper for @def... categories

[Gavin Smith]

On Fri, Jan 20, 2023 at 09:13:13PM +0100, Arsen Arsenović wrote:
> Hi,
> 
> I'm working on the GCC manual again (finally!), and I'm trying to
> harmonize it on using definition commands for built-ins et al.  For
> writing convenience, as well as consistency, I'd like to define aliases
> for commonly-used categories (for instance, I'd like to define a
> @defbuiltin = @deftypefn {Built-in Function} ...).
> 
> I tried the obvious:
> 
>   @c Convenience macro for defining builtins, in similar spirit
>   @c to @deftypefun for functions.
>   @macro defbuiltin
>   @deftypefn {Built-in Function}
>   @end macro
> 
>   @macro defbuiltinx
>   @deftypefnx {Built-in Function}
>   @end macro
> 
> The above, however, is not a drop-in replacement for the fully expanded
> form, since something like
> 
>   @defbuiltin {size_t} __builtin_object_size ...
> 
> ... breaks, where the expanded equivalent does not

Yes: unfortunately, macro expansion in texinfo.tex is not reliable
in all contexts.

You can work around it by making the macro take an argument and expand to
the whole line.  I believe this is what the groff manual does.

The following works:

  @macro defbuiltin {rest}
  @deftypefn {Built-in Function} \rest\
  @end macro
  
  @defbuiltin size_t __builtin_object_size @dots{}
  explanation
  @end deftypefn

as does

  @defbuiltin{{size_t} __builtin_object_size @dots{}}
  explanation
  @end deftypefn

This is not perfect of course, but it is the best we can do for now, short
of inventing new language features.

The following does not work because the argument to @defbuiltin is
taken as "size_t" only:

  @defbuiltin {size_t} __builtin_object_size @dots{}
  explanation
  @end deftypefn

> This also requires that the command is terminated by @end deftypefn,
> which exposes the detail of the implementation of the macro, and hence
> is a bit ugly.

You can also define a macro for the @end line:

  @macro defbuiltin {rest}
  @deftypefn {Built-in Function} \rest\
  @end macro
  
  @macro enddefbuiltin
  @end deftypefn
  @end macro
  
  @defbuiltin{{size_t} __builtin_object_size @dots{}}
  explanation
  @enddefbuiltin

> What's the idiomatic way to make such an alias?  Is there any currently?

I don't know if this counts as idiomatic or recommended, just that there
doesn't seem to be any other better way of doing it.

Re: texinfo 4.2 missing from ftp?

[Gavin Smith]

On Wed, Jan 18, 2023 at 01:30:01PM -0800, Rob Krum wrote:
> Greetings,
> I've noticed that texinfo release 4.2 is missing from gnu's ftp archives,
> but the manual still exists for it in the old-gnu archive. Texinfo 4.2 I
> believe is the latest release that can be used to make binutils 2.16.1a.
> I've found myself a copy, however I have nothing to prove it's a copy of
> the original, unmodified release. Would it be possible to add this to the
> ftp for preservation purposes? Thanks!

I would like to get all the previous Texinfo releases if possible.  Would
you email me the distribution file you have off-list and any information
you have about its provenance?

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

[Gavin Smith]

On Tue, Jan 10, 2023 at 09:39:28PM +0100, Alejandro Colomar wrote:
> I don't have that documentation available.  In which package is it?

$ dpkg -S /usr/share/info/libc.info.gz 
glibc-doc-reference: /usr/share/info/libc.info.gz

This is on Linux Mint 20.3.

It's also available on the website:
https://www.gnu.org/software/libc/manual/

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

[Gavin Smith]

On Tue, Jan 10, 2023 at 09:14:35PM +0100, Alejandro Colomar wrote:
> I'm curious about how away from man(7) pages that hypothetical GNU OS is.
> Would you use info pages for libc functions?
> 
> So far, I tried to find printf(3) with info(1), but `info printf` brings me
> to the documentation for printf(1).  How can I search for a libc function
> printf()?

Yes, I use the Info glibc manual all the time.  I would look up the
documentation of printf by running "info libc printf".  This exact
example is in the info-stnd manual, in the Invoking Info node.

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

[Gavin Smith]

On Tue, Jan 10, 2023 at 02:28:16PM +0100, Arsen Arsenović wrote:
> Also, I didn't realize this before it was mentioned here, but yes,
> ``(info)Help'' indeed comes with EMACS.  Perhaps we should include a
> copy in the Texinfo distribution too, or encourage downstreams to
> extract info.info out of EMACS, so that those installing info but not
> EMACS (which is rather common) have immediate access to the tutorial.
> Eli, Gavin, what do you think about that?

(Hopefully my last mail this evening.)

info.texi used to be distributed with Texinfo but was maintained
as part of Emacs.  There were complaints that having the same file
distributed with both Emacs and Texinfo was inconvenient:

https://lists.gnu.org/archive/html/bug-texinfo/2015-10/msg00062.html

I'm happy that info.texi is not distributed with Texinfo, anyway, as
it is a file that we cannot control and yet would appear responsible
for if it came with Texinfo.  It makes sense for info-stnd.texi to
be maintained as part of the Texinfo project because the standalone
Info browser is also maintained as part of the same project, but the
same argument does not apply to info.texi.  Discussing changes to
info.texi on a different project's mailing list could be an unedifying
experience, which is natural and unavoidable even with the best wills
in the world.

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

[Gavin Smith]

On Tue, Jan 10, 2023 at 02:46:10PM +0200, Eli Zaretskii wrote:
> > From: Dave Kemper 
> > Date: Mon, 9 Jan 2023 15:36:44 -0600
> > Cc: ar...@aarsen.me, alx.manpa...@gmail.com, g.branden.robin...@gmail.com, 
> > help-texinfo@gnu.org
> > 
> > On 1/9/23, Eli Zaretskii  wrote:
> > > It is not a coincidence that the GNU project deprecated man pages in
> > > favor of Info manuals.
> > 
> > A decision that, decades on, still does not garner universal acclaim.
> 
> There are people who weren't yet exposed to the superior power of
> Info, because no one could be bothered telling them the main points
> and punch lines.  And then there are old habits that die hard.
> 
> The GNU project has as its _policy_ to prefer Info documentation.  We
> are executing this policy because we fully agree with it, but even if
> we didn't agree, when we accept the nomination of maintainers of some
> GNU package, we promise to uphold these policies.

I'll add that our interest here on this mailing list is Info and
Texinfo, and making those systems better, and in doing so making the
GNU system better in making a complete free operating system available.

Whether manpages are better or not, is really neither here or there.
If some other effort wants to use manpages to document their system
rather than Info then that is perfectly fine and nobody will be
offended in any way.

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

[Gavin Smith]

On Mon, Jan 09, 2023 at 03:36:44PM -0600, Dave Kemper wrote:
> All I'm saying is, don't confuse YOUR (collective help-texinfo)
> worldview with THE worldview.  The main points are: (a) the info
> program can accommodate both types of users; and (b) two small
> additions to the info man page will let users see both paths available
> to them.  Some users, no doubt, will quickly conclude that using
> "less" as an Info pager is, to quote Gavin, "defective," and never use
> it again.  Others will love being able to leverage knowledge of a
> pager that is usable on a variety of unwieldy documents.

It should be noted that the info manpage is automatically generated
from the output of "info --help" and so is necessarily short and not
comprehensive.  "info --help" should only tell about the most important
options: the more that is in there, the less useful it becomes.

> Furthermore, by showing that "info" output CAN be piped, you open Info
> documents up to a world of possibilities that neither you nor I can
> even think of.  Even someone wanting a ballpark for something as
> simple as "How does the size of the emacs manual compare to that of
> the sed one?" can use it:
> 
> $ info sed | wc
> $ info emacs | wc

Yes, interesting, but not so useful that it deserves a place in the
help message.  If we document every tip or trick that somebody thought
was useful, then it would become a disorganized pile of junk.

It should be documented, which I didn't see that it was before, so
I've added the following text to info-stnd.texi:

 If Info is invoked when its standard output is not a terminal, it
  does not attempt to start an interactive session; rather, it writes the
  contents of the loaded nodes and subnodes to standard output, as if the
  ‘--output=-’ and ‘--subnodes’ options were given.  This can be used to
  pipe the contents of Info nodes to another program, such as a pager.

Hopefully that is sufficient and correct.

However, there is an example in "info --help":

 info --subnodes -o out.txt emacs
   dump entire emacs manual to out.txt

If we changed this to

 info --subnodes -o - emacsdump entire emacs manual to stdout

then the users would be close to figuring out

 info --subnodes -o - emacs | less

as a possibility for themselves.  (It would also save a line.)  I
like the idea of changing this, but maybe somebody has a comment?

> It's also a testament to the power of "less" that it's usable on huge
> man pages like bash(1).

That's not my experience.

For example, I regularly check the perlfunc(1) man page to look up
information on Perl builtins, and find I have to use search expressions
like "^ *shift" to go to the documentation of the "shift" function,
knowing from experience which search expression works for this manual,
otherwise I have to look through several extraneous matches.

If I could type "info perlfunc shift" from the command-line, this
would be much easier.

Another example: compare "info bash param" with "man bash" followed
by /param.  I can get to the documentation on the different types
of parameter expansion much quicker with info.  Even once I discover there
is a section called PARAMETERS, searching for this string (in caps) leads
to extraneous matches of other cross-references to that section.  (I
guess I should have used ^PARAMETERS instead.)  However, that section is
still not what I want.

If I had searched for "parameter" in the bash man page, I would have
missed several occurences of this word due to the word being split
across lines, as in "parame-ters".

Finally I realise I should be searching for "parameter expansion" and
I find what I am looking for.  There is a heading "Parameter Expansion",
but it's not clear if this is a subsection of a larger section - I have
to page up several times to find the EXPANSION heading.  This shows that
it is harder to understand the context of particular parts of a manual,
whereas in Info I could have just pressed "u" to see the containing section
followed by "l" to go back.

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

[Gavin Smith]

On Sat, Jan 07, 2023 at 11:40:29PM +, Gavin Smith wrote:
> > This documentation describes the stand-alone Info reader which you can
> > use to read Info documentation.
> > 
> >If you are new to the Info reader, then you can get started by typing
> > 'H' for a list of basic key bindings.  You can read through the rest of
> > this manual by typing  and  (or  and ) to
> > move forwards and backwards in it.
> > ]
> > 
> > 
> > However, help that explains how to navigate is of little help if I first
> > don't know how documentation is organized.  In a manual page, it is simple:
> > documentation for something is in a single page.  In Texinfo, there is a
> > nodes a dir, a pointer, a file, a tree, ...  and I don't know what they
> > mean.
> 
> We could try to streamline the documentation in info-stnd.info so
> that repeatedly pressing the space bar gets you the information you
> need as soon as possible, without having to read past all the command-line
> options.  We could move the "Selecting a Node" section earlier.

I've made a few changes to info-stnd.texi, mainly in reordering sections.
Hopefully this is an improvement.

I haven't added any ASCII art showing the document tree and the directions
of Up, Next and Prev, but maybe this could be added.  If there is important
missing context, that could be added too.

I have often found public discussions of documentation nonplussing.  Often
people don't convince each other, as there is no clear right answer.

I'm already feeling somewhat overwhelmed by the volume of mail on related
topics and knowing which mail to respond to.

What I'd like to avoid is making the documentation worse, which could
happen following a discussion where somebody suggests "just adding a
note" somewhere.  If this is done apparently successfully several times,
the documentation comes to be an incoherent mess crowded with detail.
Hence the global view should be taken not just the local view.

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

[Gavin Smith]

On Mon, Jan 09, 2023 at 06:52:44PM +0200, Eli Zaretskii wrote:
> It's an obscure capability that is useful in marginal situations.  A
> large manual piped like this will present a humongously long linear
> text, and I doubt that the result will be a convenient read.  It's
> again not an incident that the vast majority of man pages are quite
> short and dedicated to a single relatively small subject.

That's my feeling too, and I don't see why this usage should be advertised
in a short manpage.  If there's some way of making info easier to learn
e.g., by improving the welcome message or documentation, then we could do
that, rather than promoting this defective usage.

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

[Gavin Smith]

On Sat, Jan 07, 2023 at 11:45:32PM +0100, Arsen Arsenović wrote:
> >>  That said, that could be
> >> done, if others agree, but I believe a better experience can be created
> >> by making the info format viewers themselves more accessible for people
> >> more used to pagers, or otherwise un-adapted to EMACS.
> >
> > :)
> >
> > If you could add an alternative mode where it would behave somewhat like
> > less(1)/vim(1), that would be great.
> 
> That's there!  ``info --vi-keys''

Not exactly as it still shows only one node at once, and when you get
to the end of a node there is blank screen at the bottom.

I wrote the following in Texinfo TODO's file (years ago) and later added
the note saying it wouldn't be done:

  A running view mode in Info, to display the next node after the end of the
  last one, and be able to toggle display of a node's subnodes.  
  [Too hard to implement because of how much code assumes 
   that only one node is in a window at once.]

That seems to be a move in the "behave like less(1)" direction, but
would require someone to implement it, which may require extensive changes
throughout the Info program.  The info source code is not that easy
to work with in the first place.

> >> A suggestion I got already (and I'll see if I can implement it soon) is
> >> generating a HTML version of the ``(dir)'' node, and probably providing
> >> a link to it, or a shortcut to jump from info to a HTML view, or
> >> something like that, so that an end user can make use of the HTML view,
> >> which is potentially more alike what they'd be adjusted to.
> >
> > HTML is probably good for some.  However, others prefer the terminal (yes,
> > there are terminal HTML browsers, but for some reason I don't find them very
> > useful).
> 
> Heh, yes, I'd not certainly not want to get rid of the terminal
> accessibility - hell, I rely on it a lot ;) - but HTML seems less
> integrated than Info can get, and it might be preferred by a lot of
> folk, hence, it would be nice to have it up to par.

Please see the TODO.HTML file in the Texinfo repository for past discussion
and pointers for future work:

  This file discusses issues related to HTML being used alongside or
  instead of Info as a documentation format.  As this has been discussed
  for many years without much progress being made, it was thought helpful
  to create a file like this to collect all the issues in one place.  Then,
  we could avoid having the same discussions over and over again.  Anybody
  raising the question could be referred to this file so they could be
  aware of the current situation.

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

[Gavin Smith]

On Sat, Jan 07, 2023 at 11:37:35PM +0100, Alejandro Colomar wrote:
> Hi Arsen,
> 
> On 1/7/23 21:33, Arsen Arsenović wrote:
> > Hi Alex,
> > 
> > Alejandro Colomar  writes:
> > 
> > > Hello,
> > > 
> > > As someone with zero knowledge of how info(1) works, but considerable 
> > > knowledge
> > > of how to read a manual page (well, there's little to it; less(1) is 
> > > really
> > > simple), I'd like to recommend something for the info(1) manual page.
> > 
> > Check out ``info "(info)Help"''.
> 
> That brings me to the same as `man info`.

It is likely that info.info isn't installed on your system as this file
comes with Emacs.

> [
> Next: Stand-alone Info,  Up: (dir)
> 
> Stand-alone GNU Info
> 
> 
> This documentation describes the stand-alone Info reader which you can
> use to read Info documentation.
> 
>If you are new to the Info reader, then you can get started by typing
> 'H' for a list of basic key bindings.  You can read through the rest of
> this manual by typing  and  (or  and ) to
> move forwards and backwards in it.
> ]
> 
> 
> However, help that explains how to navigate is of little help if I first
> don't know how documentation is organized.  In a manual page, it is simple:
> documentation for something is in a single page.  In Texinfo, there is a
> nodes a dir, a pointer, a file, a tree, ...  and I don't know what they
> mean.

We could try to streamline the documentation in info-stnd.info so
that repeatedly pressing the space bar gets you the information you
need as soon as possible, without having to read past all the command-line
options.  We could move the "Selecting a Node" section earlier.

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

[Gavin Smith]

On Sat, Jan 07, 2023 at 09:33:40PM +0100, Arsen Arsenović wrote:
> Hi Alex,
> 
> Alejandro Colomar  writes:
> 
> > Hello,
> >
> > As someone with zero knowledge of how info(1) works, but considerable 
> > knowledge
> > of how to read a manual page (well, there's little to it; less(1) is really
> > simple), I'd like to recommend something for the info(1) manual page.
> 
> Check out ``info "(info)Help"''.  This page is also linked through the
> info viewer welcome message: "Welcome to Info version 7.0.1.  Type H for
> help, h for tutorial".  Pressing h at any point in the info viewer takes
> you to that page.
> 
> This message seems to often be missed by users, in my experience.  I
> don't know why - perhaps because it's on the bottom of the screen, below
> the interesting stuff.

I'm tempted to suggest emphasizing the message with the use of colour.
A patch is at the end of this mail.

This would be distracting for users who already know how to use Info,
of course.

You can also make the message blink by adding | BLINK_MASK after BOLD_MASK.

diff --git a/info/display.c b/info/display.c
index 5a30ca4747..b8e34e889c 100644
--- a/info/display.c
+++ b/info/display.c
@@ -697,10 +697,17 @@ display_update_one_window (WINDOW *win)
 
   if (win->node)
 {
+  if (win->flags & W_Emphasize)
+{
+  terminal_switch_rendition (COLOUR_YELLOW | BOLD_MASK);
+}
+
   if (!win->line_starts)
 calculate_line_starts (win);
   line_index = display_update_node_text (win);
 
+  terminal_switch_rendition (0);
+
   if (display_was_interrupted_p)
goto funexit;
 }
diff --git a/info/window.c b/info/window.c
index bef2a3bcde..f6e3806d6b 100644
--- a/info/window.c
+++ b/info/window.c
@@ -1009,10 +1009,12 @@ void
 window_message_in_echo_area (const char *format, ...)
 {
   va_list ap;
-  
+
+  the_echo_area->flags |= W_Emphasize;
   va_start (ap, format);
   vwindow_message_in_echo_area (format, ap);
   va_end (ap);
+  the_echo_area->flags &= ~W_Emphasize;
 }
 
 /* Place a temporary message in the echo area built from FORMAT, ARG1
diff --git a/info/window.h b/info/window.h
index 1f38ca84a0..11467a37f6 100644
--- a/info/window.h
+++ b/info/window.h
@@ -109,6 +109,7 @@ typedef struct window_struct
 #define W_NoWrap0x10/* Lines do not wrap in this window. */
 #define W_InputWindow   0x20/* Window accepts input. */
 #define W_TempWindow0x40/* Window is less important. */
+#define W_Emphasize 0x80/* Bright colours in window. */
 
 extern WINDOW *windows; /* List of visible Info windows. */
 extern WINDOW *active_window;   /* The currently active window. */

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

[Gavin Smith]

On Wed, Jan 04, 2023 at 05:08:09PM +0700, Nutchanon Wetchasit wrote:
> Hello,
> 
> Following is going to be an unusual question,
> concerning a very specific usage scenario and requirement
> that intentionally goes against what's so-called
> "best-practices" set by industries-that-must-not-be-named...
> 
> (See below "-" if you would like to skip right to the question)
> 
> I came from the DocBook world, and I'm just starting
> a new hardware documentation project as my first writing project
> that uses Texinfo markup format; without having any real background
> in plain TeX and derivatives. The age of machine I am doing this on
> is approaching a decade, and Texinfo toolchain version
> I am currently using is 4.3.
> 
> The HTML output it gave was more or less what I expected,
> but some corner cases of its macro interpretation [1]
> and its TeX/PDF output [2] got some bugs that affected my uses;
> so I am considering to install a newer Texinfo toolchain
> *alongside* the existing one.
> 
> But I have also noticed that the on-WWW version of GNU software manuals
> have switched to use `` header for some time now.
> This could be inferred that the latest version of Texinfo toolchain
> produces HTML-MovingGoalpost [3] either by default, or as the *only*
> SGML-like HTML format offered. This is not what I would like
> to produce my document in however...
> 
> I rather prefer my document to be converted into a markup format
> that is properly standardized (i.e. long-standing non-changing
> properly-versioned specification that people from the past, present,
> or future, could realistically write independent viewers for)
> for information longevity reasons. In SGML-style [4] WWW markups,
> this means W3C HTML 4.01 a.k.a. ISO 15445:2000. For that reason,
> I think the latest version of Texinfo might not fit for my needs.
> 
> -
> 
> 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?

This is difficult to answer as I am not aware that it does use any HTML
construct that is after HTML 4.01.  As you have seen from the NEWS the
DTD declaration was removed in Texinfo 7.0 and was present in Texinfo 6.8.

The only thing that comes to mind is the custom "data-manual" attribute
that is used in links to other HTML manuals.  This may have been introduced
in Texinfo 6.7.  In Texinfo 7.0 the NO_CUSTOM_HTML_ATTRIBUTE variable
can be used to stop this attribute being output.  I believe that custom
data attributes were not present in HTML 4, although would have been
ignored by web browsers in practice.

> And lastly, are there any caveats/gotchas to avoid when having
> more than one version of Texinfo installed on the same system?
> I plan to install it using configure option like `--prefix=/opt/texinfo`.
> (I guess there would be at least one: the installation location
> of `texinfo.tex` and how to reference a correct one when typesetting
> into TeX/PDF)

Not that I'm aware of, although I haven't done it very much.

> [1] I attempted to rig up a new inline quote macro to make Texinfo
> produce "``something''" through TeX but produce "something"
> in HTML (an analog of DocBook's `` construct);
> but its macro definition translation got some quirk
> which introduced space between the quotes and its content,
> and required a hack which somehow sat okay with TeX-based pipeline
> but blew up in HTML conversion.

Yes macro handing changed completely in Texinfo 5.0 and onwards.


> [2] `@ref{Somenode}` produced " [Somenode], page "
> in the paper output, no matter that it was `texi2pdf`, `texi2dvi --pdf`,
> or `texi2dvi` followed by `dvi2ps`. (Though that phrase in
> PDF outputs would still link to the target page properly
> when viewed under a PDF viewer software;
> it would not be very helpful in print)

That is unusual although we don't have to be concerned with reports
for such an old Texinfo version.

Re:

[Gavin Smith]

On Fri, Dec 30, 2022 at 02:47:49PM -0500, Pierce Burger wrote:
> Hello. I would like to request for gnu info to allow scrolling with the j
> and k keys, similar to how it works in vim. I am used to using those keys
> for scrolling and noticed that they dont have another purpose in info.
> 
> Thank you.

You can already configure info to use those keys to scroll up and down,
as somebody else said.

Although the j and k keys aren't otherwise used, I'm not sure if there is
much benefit in making them scroll, as then we would never be able to use
those keys for anything else in the future.

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

[Gavin Smith]

On Fri, Dec 16, 2022 at 03:01:06PM -0800, Raymond Toy wrote:
> > You can do this using @deffn and @deffnx instead, at the expense of also
> > needing to specify "Function" on the first line:
> >
> > @deffn  {Function} {check-region-query-size} {region}
> > @deffnx {@sansserif{Hemlock} Variable} @sansserif{Region Query Size} @
> > {@r{(initial value @code{30})}} @useindex{vr}
> > description
> > @end deffn
> >
> > (I used @sansserif to match the style of the original document although
> > this may not be what is desired.)
> >
> 
> Oh, that works really well. I don't mind specifying Function.  (In fact,
> that's what I was doing until I realized there was defun.)
> 
> I hadn't considered matching the original text style.  Perhaps I'll
> consider it, but the most important part was that I had a texinfo version
> that had all the information in it.
> 
> When (or if) this lands in a release, I'll update the doc to use these
> features.
> 
> Does @useindex have to be at the end of the line?  Could it be at the
> beginning of the next line?  Having it at the end makes an already long
> line even longer and harder to notice that we specified a different index
> for the item.

It has to be after the name of the symbol being indexed, inside the
arguments at the end of the line.  You can use a line continuation, as
in:

@deffn {Variable} fun (args) @
@useindex{vr}
description
@end deffn

If you did

@deffn {Function} @useindex{ix} fun (args)

then it will not work due to @useindex{ix} being in the position for
the symbol.

@deffn @useindex{ix} {Function} fun (args)

does not work either, as this will take @useindex{ix} as the category
and Function as the name of the symbol.  However, the following does
work:

@deffn {Function} fun @useindex{ix} (args)

This is not good to write though, so if we implement this in texi2any
and document it, then we should recommend or require that @useindex
be at the end of the line (or on the next one using an @ continuation).

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

[Gavin Smith]

On Fri, Dec 16, 2022 at 08:40:43AM -0800, Raymond Toy wrote:
> I tried this out with my translated Scribe document for one entry.  The
> entry looks like
> 
> @defun {check-region-query-size} {region}
> @defunx {Hemlock Variable} {Region Query Size} @val{30}@useindex{vr}
> description
> @end defun
> 
> Other than having to use defunx for a variable, this works.  Region Query
> Size shows up in the vr index as expected.  And check-region-query-size is
> still in the fn index, as expected.
> 
> It's a bit annoying that I have to use defunx for a variable, but the
> output looks nice, except that Region Query Size is marked as a Function as
> shown below.
> 
> At least for my use case, @useindex helps, but other parts don't work out
> right because the pdf output still says Function instead of Variable.

You can do this using @deffn and @deffnx instead, at the expense of also
needing to specify "Function" on the first line:

@deffn  {Function} {check-region-query-size} {region}
@deffnx {@sansserif{Hemlock} Variable} @sansserif{Region Query Size} @
{@r{(initial value @code{30})}} @useindex{vr}
description
@end deffn

(I used @sansserif to match the style of the original document although
this may not be what is desired.)

> Allowing defvarx after defun would work the best for my use case.
> 
> I wouldn't worry about this though.  I have a reasonable workaround that is
> good enough for me.  Thanks for looking into it though!  I appreciate all
> of the work put into texinfo.

Generalising @def* has long been on the to-do list for Texinfo but we have
never been sure how to proceed.  It's good to have feedback from users
about what is useful.

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

[Gavin Smith]

On Tue, Nov 22, 2022 at 09:56:42PM +, Gavin Smith wrote:
> Interesting to see the Scribe document - I don't think I've seen one
> before.
> 
> I think that @deffn and @defvrx etc. could be mixed, although
> the @def* commands have long been an area where changes could be
> made to be more general.  See the TODO file in the git repository.
> If we had some way of explicitly specifying the index that a @def*
> command would use, then this would solve this problem.

I've commited a change for an experimental feature to allow this.  This
is in texinfo.tex version 2022-12-15.20 (in git).

Example code:

\input texinfo

@defcodeindex xy


@defun Foo (bar)@useindex{xy}
foobar
@end defun

@printindex xy

@bye

This puts the index entry in the 'xy' index rather than the
'fn' index.

This has not been implemented in texi2any at all and the syntax, name
of the @useindex command, etc. could all change, or the feature might
not be implemented at all if there is no use for it.  Please experiment
and report what would be useful.

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Thu, Dec 01, 2022 at 03:29:34PM +0100, Arsen Arsenović wrote:
> Hi,
> 
> > It looks like gather_previous_items supports @itemx (at least in the
> > Non-XS parser), so I might be able to figure that out tomorrow, sadly, I
> > am out of time for the day.  Hopefully, it wouldn't be too hard to
> > recover the anchors too (people have taken to like them a lot :) ).
> 
> So, I took a crack at this.
> 
> I managed to implement a tree transform that does a similar association
> that relate_index_entries_to_table_entries_in_tree did, and enabled it
> only in the HTML backend, to produce [1] (note the presence of
> the copyable anchor) from [2].  I'm not sure the approach I took is
> correct, though, but it passes tests (I wasn't entirely sure how to add
> a test for this, so I left testing copyable anchors out for now).

This is great, it looks like you implemented it very simply.  I think
we should definitely include this patch in some form.  Can I sent you
the copyright assignment forms to fill in for the FSF?  (This is usually
a quick process that can be done online.)

I will test this patch when I have time in the next few days.

Re: Relating multiple index entries to one table item

[Gavin Smith]

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.

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.

Re: Relating multiple index entries to one table item

[Gavin Smith]

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.

Currently, the input:

@table @code
@vindex ONE
@vindex TWO
@item in item
@itemx in itemx
a

@vindex TTHREE
@item item2
a
@end table

gives the HTML output:




in item
in itemx
a



item2
a



which I think is good.

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Sat, Nov 26, 2022 at 05:19:17PM +0100, Patrice Dumas wrote:
> I just pushed a commit which removes _open_table_term_type.  Feel free
> to revert it if you need to.

LGTM, thanks.

Re: Relating multiple index entries to one table item

[Gavin Smith]

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.

Re: Relating multiple index entries to one table item

[Gavin Smith]

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

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

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.

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

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Sat, Nov 26, 2022 at 03:04:37PM +0100, Patrice Dumas wrote:
> 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 have a change that is nearly ready that includes preceding index entries
inside .

Re: Relating multiple index entries to one table item

[Gavin Smith]

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.

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.

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Tue, Nov 22, 2022 at 11:07:15PM +0100, Patrice Dumas wrote:
> On Tue, Nov 22, 2022 at 09:49:31PM +0000, 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 .

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
   

   Hello
   
   
   

(I have not sent my work-in-progress code because I doubt anybody wants to
see it.)

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.

For reference, the output before this change was


AAA
BBB



Hello




which doesn't have the copiable link (which may be a good thing, if
the document author doesn't want this), but the anchors will scroll
the page to after the  headings, leaving them not visible.

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.

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Wed, Nov 23, 2022 at 07:57:16AM +0100, Arsen Arsenović wrote:
> Hi,
> 
> Gavin Smith  writes:
> 
> > I think deciding on the right output for the existing usage and
> > implementing such is more important than devising and implementing
> > new language constructs.
> 
> I understood you to mean that a list of index entries that follows a
> list of items should get the index automatically distributed.  I'm not
> sure if that's what you mean (my apologies, I've not been following with
> full attention).
> 
> I'm not sure that's quite possible in this instance.  In the example I
> was using, there's a different number of index entries versus items,
> since there isn't an item added for -Wno-..., despite there being an
> index entry to it.

I think all the index entries should link to the first @item.  I didn't
mean that there would be one index entry per @item/@itemx.



> The @itemindex proposal also seems to assume one index per item.  Maybe
> some transformation could be added to associate N @XXindex calls with an
> @item[x] that follows it too?  I haven't seen this usage in the wild,
> but it would allow indices other than f and v to also have properly
> indexed tables.  What I mean is that maybe:
> 
>   @opindex Wpedantic
>   @opindex Wno-pedantic
>   @item -Wpedantic
>   @opindex pedantic
>   @itemx -pedantic
> 
> ... should produce:
> 
>   
> 
> 
> 
>   -Wpedantic
>¶
> 
>   
>   
> 
> 
>   -pedantic
>¶
> 
>   
> 
> (formatting added for clarity), though, this has the disadvantage of
> still needing some care to keep the indices and items in sync.  Maybe
> just adding the -Wno-... flags is worth it to get the right result here.

Yes, it may be possible to associate index commands with a following
@item, although as you say, existing manuals may not be written for
this possibility.

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

[Gavin Smith]

On Wed, Nov 23, 2022 at 07:14:53AM +, Gavin Smith wrote:
> Brian Reid's 1980 thesis (referenced on Wikipedia) is still available
> on the Internet Archive:  
> https://web.archive.org/web/20140407073459/http://reports-archive.adm.cs.cmu.edu/anon/scan/CMU-CS-81-100.pdf

Also an earlier (and typographically poorer) document from 1978:
http://www.bitsavers.org/pdf/cmu/scribe/Scribe_Introductory_Users_Manual_Jul78.pdf

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

[Gavin Smith]

On Tue, Nov 22, 2022 at 04:47:08PM -0800, Raymond Toy wrote:
> On Tue, Nov 22, 2022 at 1:56 PM Gavin Smith 
> wrote:
> 
> > On Tue, Nov 22, 2022 at 07:21:05AM -0800, Raymond Toy wrote:
> > > 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.
> >
> > Interesting to see the Scribe document - I don't think I've seen one
> > before.
> >
> 
> I've only ever seen 2 such docs.  I googled all over to find any kind of
> description of Scribe but failed.  Fortunately, there was the source doc
> along with the PS file, so I just kind of reverse-engineered what Scribe
> did to find a Texinfo equivalent.  The languages are surprisingly similar.

Brian Reid's 1980 thesis (referenced on Wikipedia) is still available
on the Internet Archive:  
https://web.archive.org/web/20140407073459/http://reports-archive.adm.cs.cmu.edu/anon/scan/CMU-CS-81-100.pdf

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

[Gavin Smith]

On Tue, Nov 22, 2022 at 07:21:05AM -0800, Raymond Toy 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
> 
> 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.

Interesting to see the Scribe document - I don't think I've seen one
before.

I think that @deffn and @defvrx etc. could be mixed, although
the @def* commands have long been an area where changes could be
made to be more general.  See the TODO file in the git repository.
If we had some way of explicitly specifying the index that a @def*
command would use, then this would solve this problem.

Re: Relating multiple index entries to one table item

[Gavin Smith]

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

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Mon, Nov 21, 2022 at 10:04:16PM +0100, Patrice Dumas wrote:
> On Mon, Nov 21, 2022 at 08:49:34PM +0000, 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'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.

I left out the code to do any reordering of index entries and @item/@itemx
lines.  This could be done in a separate transformation, if this would
be clearer.

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.

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Mon, Nov 21, 2022 at 06:43:20PM +, Gavin Smith wrote:
> Hence, I think our starting point is to make mixed @item/@itemx/@?index
> work appropriately, associating index commands that immediately follow
> @item commands with them.  I think it might be better in a case like
> 
> @table @gcctabopt
> @item -Wpedantic
> @itemx -pedantic
> @opindex pedantic
> @opindex Wpedantic
> @opindex Wno-pedantic
> 
> to find some way to make all index entries link to the top @item

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.

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

bbb



Does this seem ok?

diff --git a/tp/Texinfo/Common.pm b/tp/Texinfo/Common.pm
index 607b61d5ca..e57a0aa96c 100644
--- a/tp/Texinfo/Common.pm
+++ b/tp/Texinfo/Common.pm
@@ -2177,6 +2177,7 @@ sub move_index_entries_after_items_in_tree($)
   return modify_tree($tree, \&_move_index_entries_after_items);
 }
 
+# todo: rename
 sub _relate_index_entry_to_table_entry($)
 {
   my $current = shift; # table_entry
@@ -2204,15 +2205,27 @@ sub _relate_index_entry_to_table_entry($)
 
   return if !$table_term or !$table_item or !$item;
 
-  if ($table_item->{'contents'}
-and $table_item->{'contents'}->[0]
-and $table_item->{'contents'}->[0]->{'type'}
-and $table_item->{'contents'}->[0]->{'type'} eq 'index_entry_command') {
-  my $index_command = shift @{$table_item->{'contents'}};
-  delete $index_command->{'parent'};
-  $item->{'extra'}->{'index_entry'}
-= $index_command->{'extra'}->{'index_entry'};
-  $item->{'extra'}->{'index_entry'}->{'entry_element'} = $item;
+  my $index_command;
+  my @old_contents = @{$table_term->{'contents'}};
+  my (@index_children, @non_index_children);
+  for my $element (@old_contents) {
+if ($element->{'type'} and $element->{'type'} eq 'index_entry_command') {
+  push @index_children, $element;
+} else {
+  push @non_index_children, $element;
+}
+  }
+  if (@index_children) {
+$index_command = shift @index_children;
+  }
+
+  @{$table_term->{'contents'}} = (@index_children, @non_index_children);
+
+  if (defined($index_command)) {
+delete $index_command->{'parent'};
+$item->{'extra'}->{'index_entry'}
+  = $index_command->{'extra'}->{'index_entry'};
+$item->{'extra'}->{'index_entry'}->{'entry_element'} = $item;
   }
 }
 
diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index e05754f448..8e29992e1d 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -1567,19 +1567,26 @@ sub _gather_previous_item($$;$$)
   # remove everything that is not an @item/@itemx or before_item to
   # put it in the table_item/inter_item
   my $contents_count = scalar(@{$current->{'contents'}});
-  my $item_idx;
+  my $splice_idx;
   for (my $i = $contents_count - 1; $i >= 0; $i--) {
 if ($current->{'contents'}->[$i]->{'cmdname'}
 and ($current->{'contents'}->[$i]->{'cmdname'} eq 'item'
  or ($current->{'contents'}->[$i]->{'cmdname'} eq 'itemx'))) {
-  $item_idx = $i;
+  $splice_idx = $i;
   last;
 }
   }
-  $item_idx = -1 if !defined($item_idx);
+  $splice_idx = -1 if !defined($splice_idx);
+
+  # move forward past any index entries
+  for ($splice_idx++; $splice_idx < $contents_count; $splice_idx++) {
+my $child = $current->{'contents'}->[$splice_idx];
+last if (!$child->{'type'} or $child->{'type'} ne 'index_entry_command');
+  }
 
   my $new_contents = [];
-  @{$new_contents} = splice @{$current->{'contents'}}, $item_idx + 1;
+  @{$new_contents} = splice @{$current->{'contents'}}, $splice_idx;
+
   my $table_after_terms = {'type' => $type,
'contents' => $new_contents};
   for my $child (@{$new_contents}) {
@@ -1609,11 +1616,12 @@ sub _gather_previous_item($$;$$)
 $item_content->{'parent'} = $table_term;
 unshift @{$table_term->{'contents'}}, $item_content;
 # debug
-if (! (($item_content->{'cmdname'}
-and ($item_content->{'cmdname'} eq 'itemx'
-or $item_content->{'cmdname'} eq 'item'))
-   or ($item_content->{'type'}
-   and $item_content->{'type'} eq 'inter_item'))) {
+if (!(($item_content->{'cmdname'}
+   and ($item_content->{'cmdname'}

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Mon, Nov 21, 2022 at 03:23:58PM +0200, Eli Zaretskii wrote:
> The index entries should precede the first @item, not be after it.  Maybe
> doing so doesn't work in this case, but you should move the index entries
> before the @item/@itemx lines regardless, since otherwise the indexing
> commands will not land you where you want.

I am not sure if this is the standard usage.  For example, in a copy
of the sources for the elisp manual I have saved, in a file called
emacs-lispref-27.2/windows.texi, there is the following:

@table @code
@item pop-up-windows
@vindex pop-up-windows@r{, replacement for}
This variable is @code{t} by default.  Instead of customizing it to
@code{nil} and thus telling @code{display-buffer} what not to do, it's
much better to list in @code{display-buffer-base-action} the action
functions it should try instead as, for example:

@example
@group
(customize-set-variable
 'display-buffer-base-action
 '((display-buffer-reuse-window display-buffer-same-window
display-buffer-in-previous-window
display-buffer-use-some-window)))
@end group
@end example

@item pop-up-frames
@vindex pop-up-frames@r{, replacement for}
Instead of customizing this variable to @code{t}, customize
@code{display-buffer-base-action}, for example, as follows:

@example
@group
(customize-set-variable
 'display-buffer-base-action
 '((display-buffer-reuse-window display-buffer-pop-up-frame)
   (reusable-frames . 0)))
@end group
@end example

@item same-window-buffer-names
@itemx same-window-regexps
@vindex same-window-buffer-names@r{, replacement for}
@vindex same-window-regexps@r{, replacement for}
Instead of adding a buffer name or a regular expression to one of
these options use a @code{display-buffer-alist} entry for that buffer
specifying the action function @code{display-buffer-same-window}.

@example
@group
(customize-set-variable
 'display-buffer-alist
 (cons '("\\*foo\\*" (display-buffer-same-window))
display-buffer-alist))
@end group
@end example
@end table

You can see here that the index commands are used after the @item or @itemx.
Apparently it was the same case in the gcc manual.

In the case of ambiguous input like:

@table @asis
@item CAR
@vindex CDAR
@item DAR
@end table

current texi2any outputs:


CAR 

DAR


- associating the index entry with the preceding @item, not the succeeding
item.

Hence, I think our starting point is to make mixed @item/@itemx/@?index
work appropriately, associating index commands that immediately follow
@item commands with them.  I think it might be better in a case like

@table @gcctabopt
@item -Wpedantic
@itemx -pedantic
@opindex pedantic
@opindex Wpedantic
@opindex Wno-pedantic

to find some way to make all index entries link to the top @item, rather
than changing to interleaving like this:

@table @gcctabopt
@item -Wpedantic
@opindex Wpedantic
@opindex Wno-pedantic
@itemx -pedantic
@opindex pedantic

and making the link for "pedantic" only link to the @itemx.  When someone
uses the "pedantic" index entry they are better off seeing the whole thing.

Re: Relating multiple index entries to one table item

[Gavin Smith]

On Mon, Nov 21, 2022 at 03:29:29PM +0100, Arsen Arsenović wrote:
> 
> Eli Zaretskii  writes:
> 
> >> ... and no clickable anchors.
> >
> > Then I guess it's a separate issue.
> 
> I suppose so.  I figured that Texinfo behaved as intended here, so I
> didn't think of that anyway (since the first of the info entries behaves
> in a way I thought was correct, i.e. points to the right location and
> generates an anchor), though I suppose that it isn't correct, since the
> @itemx entries don't get their associated index entries.
> 
> The solution of using an indexing table command (like @vtable) seems to
> be the better one generally, though.  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 might be but I don't know.  @table should be fixed in any case.
A command like @vtable wouldn't work for your use case because the
index entries don't have leading hyphens, unlike the items in the table.



> Thank you for your help.
> -- 
> Arsen Arsenović