texi doc: "@ref should not appear on @item line" warnings in `make doc`

[apjanke]

Once I got the make doc doco generation working again for https://github.com/apjanke/octave-tablicious/issues/108 and https://github.com/apjanke/octave-tablicious/issues/110, when I ran it, it gave me a bunch of "@ref should not appear on @item line" warnings, like this.

make all
export SOURCE_DATE_EPOCH=`cat TIMESTAMP`; \
    perl ./mktexi.pl src/tablicious.texi ../INDEX tablicious.texi tablicious.qhp ../inst
perl ./mktexi.pl --check-texinfo-version
Texinfo version 7.1 is new enough
makeinfo --no-split -o tablicious.info tablicious.texi
tablicious.texi:557: warning: @ref should not appear on @item line
tablicious.texi:561: warning: @ref should not appear on @item line
tablicious.texi:565: warning: @ref should not appear on @item line
tablicious.texi:569: warning: @ref should not appear on @item line
tablicious.texi:573: warning: @ref should not appear on @item line
[...]

But the doco build doesn't error out, and it looks like it produces valid output files for HTML, PDF, etc.

Dozens of those warnings. Looks like each of them is from where my mktexi.pl is doing an emit "\@item \@ref{$fcn|\n" for each function or similar thing to generate a table of contents. That's structured as a @table @asis in texinfo terms, inside a @subsection.

Googling for that specific warning message produced almost no hits, and in those hits no info about how to hanle this.

[apjanke]

So, I'm thinking a fix, in line with what this warning is asking for, is to change the @ref{$fcn} in the table @item lines to plain text @item $fcn, and move the reference in to the body of that table item (the lines of texi content that follow the @item and up to the next @item or table closing. Like this:

I like the formatting of the old way better. But I'm inclined to do this change anyway, because I really like warning-clean builds (I was confused by these warnings myself earlier), and because I think the warnings indicate that way may have problems in other contexts (like an info page or PDF rendering) that I'm not aware of, because I don't understand texinfo that well.

---

Here's what the results of that change look like, in terms of the current build which is kicking out those "@ref should not appear on @item line" warnings, vs. what a warning-clean version with that code change produces. This content is all in section 8, "API Reference", one of the last sections but the bulk of the manual.

HTML format

Before: In the HTML output, it looks like this. The name of each table item is itself a link to the node for that function or other thing. The links work for me, and this is about how I intended it to look.

With the change, it looks like this. The table items (which look more like definition lists in HTML terms) are plain text, and the links to the node for that thing are in a separate paragraph in the body text. (I could have put them in the same paragraph, but I think having the link there is visually distracting, and worse than spending that space on a separate, uniformly-aligned paragraph.)

Hrmmm. All the item bodies are just one line summaries; this level is intended as a skimmable index. Maybe pulling the "See $foo" @xref into the same paragraph would be better after all.

PDF format

Before:

After:

Well that one's clearly better the new way. Links work in both cases. I think combining the two paragraphs here would hurt readability, because of the visible section and page numbers and stuff in the print-ish form.

in-app doc browser (Qt Help)

Before:

After:

Less good, IMHO, but not bad.

I wouldn't mind if the categories under "API by Category" showed up as their own items/levels in that left-hand Contents navigation pane.

---

On balance, I think the new way that removes the warnings is the way to go here.

[apjanke]

I did the change, replacing @item @ref{$fcn} with plain @item $fcn and moving the ref to an @xref inside the item body.

Pushed to branch bulbasaur-24. Closing as fixed.