[Bug web/107651] New: Having two different kind of indexes is very useful still

[Bug web/107651] New: Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

            Bug ID: 107651
           Summary: Having two different kind of indexes is very useful
                    still
           Product: gcc
           Version: 13.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: normal
          Priority: P3
         Component: web
          Assignee: unassigned at gcc dot gnu.org
          Reporter: pinskia at gcc dot gnu.org
  Target Milestone: ---

The texinfo generated indexes had two different kind of index.
One for options and one for Concepts.
I think for the user manual this should definitely stay around.

If we could split it the concepts even further like lists all pargmas together
and all attributes together that would even be better.

Since indexes are currently broken, PR 107643. It is hard to tell what it will
be like.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #1 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
For the install page, one index should be index of configure option and another
one will be of the env variables.

For the preprocessor has an index of env variables too.

Maybe even in the main document you have a list of env variables because of
ASAN options. Or that should be part of the library section; I don't know
fully.

[Bug web/107651] Having two different kind of indexes is very useful still

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

Martin Liška <marxin at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |RESOLVED
         Resolution|---                         |INVALID
                 CC|                            |marxin at gcc dot gnu.org

--- Comment #2 from Martin Liška <marxin at gcc dot gnu.org> ---
(In reply to Andrew Pinski from comment #0)
> The texinfo generated indexes had two different kind of index.
> One for options and one for Concepts.
> I think for the user manual this should definitely stay around.
> 
> If we could split it the concepts even further like lists all pargmas
> together and all attributes together that would even be better.

Sphinx is even better here, it builds index listing based on Directives (types
of category): https://gcc.gnu.org/onlinedocs/gcc/genindex.html

> 
> Since indexes are currently broken, PR 107643. It is hard to tell what it
> will be like.

They are all avaiable.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

Andrew Pinski <pinskia at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|INVALID                     |---
             Status|RESOLVED                    |NEW
     Ever confirmed|0                           |1
   Last reconfirmed|                            |2022-11-13

--- Comment #3 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Your index page has both options and symbols intermixed and not two different
pages. Funny how you said one thing and it is exact opposite.
Also that page is not linked anywhere from the site. 

Oh also the formatting on some of things looks off. Look at x86 and you will
see what I am talking about.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #4 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Symbols are listed separately but again not on a separate page. Plus the two
columns make it difficult to read on mobile. Again this still different from my
request too.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #5 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Oh wait I just realized that symbol here is -. That is just useless. And even
not ignoring f or m as part of the option in the index will also be useless and
just having parts in m and f.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #6 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Also search bars are not very useful if you say searching for an option and it
turns up non option related stuff.
An example of that is you search for vectorize you it turns up the extension
page.

Indexes are useful for searching and researching and having the options all in
one place.

[Bug web/107651] Having two different kind of indexes is very useful still

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #7 from Martin Liška <marxin at gcc dot gnu.org> ---
(In reply to Andrew Pinski from comment #3)
> Your index page has both options and symbols intermixed and not two
> different pages. Funny how you said one thing and it is exact opposite.

Index page contains everything: Titles, all directives and stuff that is marked
with '.. index:' directive. What did I say is exact opposite, can you explain
it, please?

> Also that page is not linked anywhere from the site. 

It is linked: https://gcc.gnu.org/onlinedocs/gcc/indices-and-tables.html#

As I showed in the screenshot. We can put it directly to
https://gcc.gnu.org/onlinedocs/gcc/indices-and-tables.html if we want.

> 
> Oh also the formatting on some of things looks off. Look at x86 and you will
> see what I am talking about.

Yes, it's the result of the conversion, where 'x86' is commonly used in '..
index:' directives.

[Bug web/107651] Having two different kind of indexes is very useful still

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #8 from Martin Liška <marxin at gcc dot gnu.org> ---
(In reply to Andrew Pinski from comment #6)
> Also search bars are not very useful if you say searching for an option and
> it turns up non option related stuff.

It's not searching only options, but also in titles and content of pages.

> An example of that is you search for vectorize you it turns up the extension
> page.
> 
> Indexes are useful for searching and researching and having the options all
> in one place.

You can quickly find 'vectorize' option in the sphinx version of the Index.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #9 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
(In reply to Martin Liška from comment #8)
> You can quickly find 'vectorize' option in the sphinx version of the Index.

But the sphinx generated index is not very useful as it lists all options under
symbols heading which is very confusing to programmers.

[Bug web/107651] Having two different kind of indexes is very useful still

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #10 from Martin Liška <marxin at gcc dot gnu.org> ---
> But the sphinx generated index is not very useful as it lists all options
> under symbols heading which is very confusing to programmers.

It's a minor limitation, one can still jump to individual listings of options:
https://gcc.gnu.org/onlinedocs/gcc/gcc-command-options.html

Plus, there's a built-in search capability that can point you to an option if
you know the name.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #11 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
(In reply to Martin Liška from comment #10)
> > But the sphinx generated index is not very useful as it lists all options
> > under symbols heading which is very confusing to programmers.
> 
> It's a minor limitation, one can still jump to individual listings of
> options:
> https://gcc.gnu.org/onlinedocs/gcc/gcc-command-options.html

That is a TOC and NOT an index.
IT IS NOT A MINOR LIMITATION.
Compare this to the texinfo generated one:
https://gcc.gnu.org/onlinedocs/gcc-12.1.0/gcc/Option-Index.html

(yes the f and m is still combined)
But the - is ignored.
Plus the layout of the index is better.
The two parrallel columns of the sphinx generated index is also bad because the
order is first column then the second which means scrolling back up for the
wrapping. IS there a way to fix that?

Plus when I saw symbol I was thinking function/variable name and not -,&,etc.
The texinfo generated index splits out the symbols even which seems like sphinx
should be able to do too which will improve the look slightly.

Searching is not just about knowing keywords but looking into similar named
things which is another reason why the two column for the generated index is
bad idea.

[Bug web/107651] Having two different kind of indexes is very useful still

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

--- Comment #12 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Created attachment 53893
  --> https://gcc.gnu.org/bugzilla/attachment.cgi?id=53893&action=edit
Screen shot of the index

When I see a row like these rows, I think __builtin_mips_any_cabs_cond_ps (C++
function) is related to _Complex keyword but they are 100% not related at all.

[Bug web/107651] Having two different kind of indexes is very useful still

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107651

Martin Liška <marxin at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |WONTFIX
             Status|NEW                         |RESOLVED

--- Comment #13 from Martin Liška <marxin at gcc dot gnu.org> ---
The Sphinx documentation has been reverted:
https://gcc.gnu.org/pipermail/gcc/2022-November/239983.html

Thus, I'm closing this as won't fix.