stddoclet: Add @index doc-comment tag for generating an index from common words

It would be useful to add a doc-comment tag that translates into the appropriate
target code an entry for an alphabetic index.
The syntax might be something like:

@index entry[:sub-entry]...

For example:

@index database:creating
@index database:modifying
@index user interface:layout

would generate index output such as:

       database
            creating . . . . . . . . . . . . . 7
            modifying . . . . . . . . . . . . 12
       user interface
            layout . . . . . . . . . . . . . . 9

The page numbers would appear only on printed documentation (PDF),
as generated by the MIF doclet.

Note that ":" is the argument separator. To allow index entries to contain a literal ":" character, there must be a means for escaping or overriding the argument separator.

Unless a sensible translation can be determined, the @index tag probably should just be ignored when generating straight HTML output.

----------------------------------
When trying to comprehend any new API, it is difficult to locate classes,
etc. except by scrolling through package trees, etc. It would be nice if
the JavaDoc HTML output contained an Index frame with plain English entries
that would help those unfamiliar with various APIs and packages find their
way around. I suggest that some sort of tag be developed that uses the
same conventions as in the FrameMaker marker dialogue, including either
HTML or FrameMaker format builders and directives, that is

     @ix main level1entry:<i>level2entry</>:level3entry[main
leveloneentry:leveltwoentry:levelthreeentry];another entry
     @ix cats:feeding of;<$nopage>canines. <EmphasisItalic>See<Default Para
Font> dogs

So instead of trying to wallow through pages of class/package lists looking
for the my.packg.nested.deeply.BusCust class, I could just look up
"business customer class" in the Index and go to the (printed) page or
click to go to the (html) page.

Studies have repeatedly shown that a reader confronted with an unfamiliar
document will go to the table of Contents to learn about the general scope
of the content, but thereafter always goes to the Index.

----------------------
NOTE: 4100717 was closed as a duplicate
###@###.### 10/20/04 17:04 GMT