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

[Robert Dodier]

Hi Pat, you mentioned it's not clear what I'm trying to do.

The category stuff I made up is essentially the same as tags which are
applied to bug reports in, e.g. Stackoverflow or Sourceforge, e.g.
https://sourceforge.net/p/maxima/bugs/3892/ (I see the tags are called
"Labels" there). An item can have multiple tags / labels / categories
/ whatever it's called, and clicking on a tag navigates to a page
which shows all the items which are tagged with that.

Here's an example of Texinfo documentation (HTML) which has been
annotated with categories (in the sense I've imposed).

https://maxima.sourceforge.io/docs/manual/maxima_54.htm

You can click on a link in the Categories: box and it will take you to
another page where all the items which are marked with a given
category are collected.

The Texinfo for such items looks like

@deffn foo (x, y, z)

Yadda yadda yadda, foo bar baz quux mumble blurf.

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

@end deffn

The easy part is to define @category{Foobar} as a macro which
substitutes @ref{Category: Foobar, Foobar}. Also easy to define
@opencatbox / @closecatbox as <div> / </div> .

The hard part, for which I've concocted some scripts, is to extract
the set of terms named as categories, and create the list of items
which are tagged with each category. This is the operation for which I
would like to inspect a parse tree of the Texinfo document.

The output of this second part is a bunch of stuff that looks like

@anchor{Foobar}
@opencatbox
@b{Category: Random blurfage}
@ref{Item: foo, foo}
@ref{Item: bar, bar}
@ref{Item: baz, baz}
@closecatbox

where foo, bar, and baz are @deffn's or @defvr's which contain
@category{Foobar}.

So, in my world of dreams, I would get a parse tree for the document
containing @deffn foo, etc., look for all the @category doodads, and
build a lookup table to map categories to items. Then loop over all
the categories, and emit the @anchor{whatever} and @ref{foo},
@ref{bar}, etc., for each item claiming to be in category whatever.

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

Hope that helps clarify what I'm trying to do, thanks for your interest.

Robert Dodier

PS. The scripts for this stuff can be found at:
https://sourceforge.net/p/maxima/code/ci/master/tree/doc/info/
namely build_html.sh.in, extract_categories1.sed, and extract_categories1.awk.
However, I expect that stuff is all pretty much incomprehensible.