Index entries for "@command" & Co.

[Tim Landscheidt]

Hi,

whenever I want to look up a command in the info file, ei-
ther with Emacs or stand-alone info I instinctively type "i
@command RET" to be startled by "No index entries containing
`@command'."

  Is this a side-effect of the index sorting, a philosophi-
cal issue or a simple oversight?

Tim

[Tim Landscheidt]

karl@... (Karl Berry) wrote on bug-texinfo:

> [...]
>     Is this a side-effect of the index sorting, a philosophi-
>     cal issue or a simple oversight?

> The first.  The original principal author of the manual (Bob Chassell),
> made a separate command index precisely so that they could be sorted by
> their first letters, and not all appear under "@".  That is, there's no
> way in Texinfo to index "@foo" and have it sorted as "foo".

> One can imagine extensions to Texinfo indexing to do this, as makeindex
> et al., but it's never actually been done.  Texinfo indexing in general
> has always been pretty simplistic.  Lots of TODO entries there ...

For a moment I started to think about possible syntaxes to
port other languages' (optional) "sort-keys" or sensible
transformations (lose all non-alphanumericals).  Then it hit
me that this would not only have to be implemented in Perl
which already doesn't look very inviting, but also in TeX
which (for me at least) skews any cost-benefit ratio :-).

  Well, I usually use Emacs to view info files, so I could
always advice Info-index.

Tim

[Tim Landscheidt]

I wrote:

> [...]
>   Well, I usually use Emacs to view info files, so I could
> always advice Info-index.

Or just use the included info-lookup-symbol (C-h S).  It on-
ly works in texinfo files, not in the *info* buffer itself,
though, and one has to tweak the default pattern a bit:

| (info-lookup-add-help
|  :mode 'texinfo-mode
|  :regexp "@\\([a-zA-Z]+\\|[^a-zA-Z]\\)"
|  :doc-spec '(("(texinfo)Command and Variable Index"
|               (lambda (item)
|                 (if (string-match "^@\\([a-zA-Z]+\\|[^a-zA-Z]\\)\\( .*\\)?$" item)
|                     (match-string 1 item)))
|               "`" "[' ]")))

But it's much friendlier than TeX :-).

Tim

[Karl Berry]

    me that this would not only have to be implemented in Perl
    which already doesn't look very inviting,

I have the impression that the development makeinfo can already do
proper Unicode sorting of the index terms, if desired.  Patrice?

    but also in TeX which (for me at least) skews any cost-benefit ratio :-).

:).  No index sorting has ever been implemented in texinfo.tex.  It's
done with a separate C program, texindex, which remains essentially in
its original state as of 1987 or so, sorting ASCII.  Life goes on ...

Best,
Karl

[Patrice Dumas]

On Sun, Mar 25, 2012 at 04:42:48PM -0700, Karl Berry wrote:
>     me that this would not only have to be implemented in Perl
>     which already doesn't look very inviting,
>
> I have the impression that the development makeinfo can already do
> proper Unicode sorting of the index terms, if desired.  Patrice?

It seems to me that ascii transliteration is used, and not proper
translation to unicode and then Unicode sorting of the index terms
or of the index letters.  Translation to Unicode instead of
transliteration should be easy to do though.  As for sorting, there is
an additional issue, as sorting is locale dependent, I don't really know
how that is taken into account in perl.

I should certainly handle this after the release.

--
Pat

[Tim Landscheidt]

karl@... (Karl Berry) wrote:

> [...]
>     but also in TeX which (for me at least) skews any cost-benefit ratio :-).

> :).  No index sorting has ever been implemented in texinfo.tex.  It's
> done with a separate C program, texindex, which remains essentially in
> its original state as of 1987 or so, sorting ASCII.  Life goes on ...

Well, my user interface to texinfo is usually autotools, and
as that has been working forever, I had never bothered to
investigate the workflow :-).  I had only skimmed the code,
but to me texinfo.fn looked like it is generated by code in
texinfo.tex and the right place to start:

| \entry{command}{83}{\code {command}}

If the third argument is the displayed text and the first
item is the sort key, "all" that needs to done would be to
output:

| \entry{command}{83}{\code {@command}}

for the input "@findex @@command" or a hypothetical
"@findexwithsortkey @@command command".  (I'd prefer the
latter as it leaves more control to the user and doesn't
subject him to the mercy of collations.)

Tim

[Karl Berry]

    but to me texinfo.fn looked like it is generated by code in
    texinfo.tex

Certainly true.  I thought we were talking about Unicode sorting here,
not the indexed Texinfo commands lacking @.

Anyway, the problem in this case is not so much the implementation but
that there is no user-level way to specify a sort key.  I'm not happy at
the idea of making up a new command like @findexwithsortkey.  However, I
guess we could do a new command used within the indexing commands, as in
@findex @sortkey{command} @@command

(Patrice, wdyt?)

For now, it remains on the TODO list ...

Best,
Karl

[Patrice Dumas]

On Mon, Mar 26, 2012 at 02:55:43PM -0700, Karl Berry wrote:

>     but to me texinfo.fn looked like it is generated by code in
>     texinfo.tex
>
> Certainly true.  I thought we were talking about Unicode sorting here,
> not the indexed Texinfo commands lacking @.
>
> Anyway, the problem in this case is not so much the implementation but
> that there is no user-level way to specify a sort key.  I'm not happy at
> the idea of making up a new command like @findexwithsortkey.  However, I
> guess we could do a new command used within the indexing commands, as in
> @findex @sortkey{command} @@command
>
> (Patrice, wdyt?)

It should not be too hard to implement, I guess.  And it is not
especially weird.  There is the issue of leading and preceding spaces
for @sortkey{..}.  Do we say something explicit on those?

--
Pat

[Karl Berry]

    There is the issue of leading and preceding spaces
    for @sortkey{..}.  Do we say something explicit on those?

We'd want to ignore such spaces, I think.

And of course we would expand Texinfo commands within the ...
as we do internally to construct the sort keys now?

k

[Patrice Dumas]

On Mon, Mar 26, 2012 at 03:11:15PM -0700, Karl Berry wrote:
>     There is the issue of leading and preceding spaces
>     for @sortkey{..}.  Do we say something explicit on those?
>
> We'd want to ignore such spaces, I think.

For the space after sortkey that would be easy but to treat space before
differently would be a bit more work, and I am not sure it would be
right.  In the example it would be marked especially since it followe
@findex, though (if I am not wrong).

> And of course we would expand Texinfo commands within the ...
> as we do internally to construct the sort keys now?

Indeed.

--
Pat

[Tim Landscheidt]

karl@... (Karl Berry) wrote:

>     but to me texinfo.fn looked like it is generated by code in
>     texinfo.tex

> Certainly true.  I thought we were talking about Unicode sorting here,
> not the indexed Texinfo commands lacking @.

> Anyway, the problem in this case is not so much the implementation but
> that there is no user-level way to specify a sort key.  I'm not happy at
> the idea of making up a new command like @findexwithsortkey.  However, I
> guess we could do a new command used within the indexing commands, as in
> @findex @sortkey{command} @@command

> (Patrice, wdyt?)

> For now, it remains on the TODO list ...

@sortkey{} is fine with me.  I just remembered why I prefer
it to changing the collation: In German (and probably other
languages as well), there are different collations for lists
of words and lists of names.  In a dictionary, "Atem" is
sorted before "Ätna" as the "Ä" is sorted as "A", while in a
phonebook, "Ä" is sorted as "Ae", thus "Atem" sorting after
"Ätna".  The Austrians add some more rules to this
(cf. http://de.wikipedia.org/wiki/Alphabetische_Sortierung).

  This would not only require texinfo to allow setting the
collation for a particular index, but also that these colla-
tions are installed on the user's system.  For example -
AFAIK - glibc only supports the dictionary collation for
German which raises the bar immensely.

Tim

[Tim Landscheidt]

karl@... (Karl Berry) wrote:

>     but to me texinfo.fn looked like it is generated by code in
>     texinfo.tex

> Certainly true.  I thought we were talking about Unicode sorting here,
> not the indexed Texinfo commands lacking @.

> Anyway, the problem in this case is not so much the implementation but
> that there is no user-level way to specify a sort key.  I'm not happy at
> the idea of making up a new command like @findexwithsortkey.  However, I
> guess we could do a new command used within the indexing commands, as in
> @findex @sortkey{command} @@command

> (Patrice, wdyt?)

> For now, it remains on the TODO list ...

Another issue just came up on bison-patches: Collapsing:

| doc/bison.texinfo:@deffn {Macro} YYERROR;
| doc/bison.texinfo:@deffn {Statement} {return YYERROR;}
| doc/bison.texinfo:@deffn {Macro} YYERROR

to one YYERROR index entry
(cf. http://permalink.gmane.org/gmane.comp.parsers.bison.patches/5152
and
http://permalink.gmane.org/gmane.comp.parsers.bison.patches/5157).
So in this case, not only the sort key would have to be
changeable, but also the index entry itself.

  Do you see a consistent syntax to incorporate such a fea-
ture (or another solution to the problem)?

Tim

[Patrice Dumas]

On Tue, Apr 03, 2012 at 11:30:17AM +0000, Tim Landscheidt wrote:

>
> Another issue just came up on bison-patches: Collapsing:
>
> | doc/bison.texinfo:@deffn {Macro} YYERROR;
> | doc/bison.texinfo:@deffn {Statement} {return YYERROR;}
> | doc/bison.texinfo:@deffn {Macro} YYERROR
>
> to one YYERROR index entry
> (cf. http://permalink.gmane.org/gmane.comp.parsers.bison.patches/5152
> and
> http://permalink.gmane.org/gmane.comp.parsers.bison.patches/5157).
> So in this case, not only the sort key would have to be
> changeable, but also the index entry itself.
>
>   Do you see a consistent syntax to incorporate such a fea-
> ture (or another solution to the problem)?

The only think I can think of would be to be able not to issue an
automatic index entry with the @deff* and let the user put himself an
@*index entry.  In analogy with @table (no index entry) versus
@ftable/@vtable (with automatic index entries).

--
Pat