Re: CEDET discoverability

[David Kastrup <dak@gnu.org>]

Chong Yidong <cyd@stupidchicken.com> writes:

> David Kastrup <dak@gnu.org> writes:
>
>>>> semantic documentation consists of a lot of buzzwords, and some
>>>> descriptions of its organization (not matching what is installed in
>>>> Emacs), but describes pretty much _nothing_ you could actually call or
>>>> use in Emacs.
>>>
>>> See the chapter "Using Semantic" in the manual, which, appropriately
>>> enough, explains how to use Semantic.
>>
>> It tells you how to turn it on and off.  It does not tell you how to
>> call or use its functions for supporting further modes.
>
> That's what the subnodes are for.  See "Semantic mode user commands" for
> a list of commands enabled by Semantic mode.  As explained in the node
> "Semantic mode", many additional features can be enabled, and these are
> explained in their own subnodes (SemanticDB, Idle Scheduler, Analyzer,
> Speedbar, ...).

Apart from the Speedbar, those are mostly not user interfaces, but
rather explanations of how to deal with sideeffects, and a list of
command names which you might or might not want to bind to keys for a
given user experience.

A user is not interested in command names.  She is interested in key
names, mouse menus, menu entries.  Also she is not interested in reading
a lot of generic buzzphrases, but rather actual examples of what a
command does.

Let us take an example:

    File: semantic,  Node: Smart Jump,  Next: Analyzer Debug,  Prev: Smart Summary,  Up: Analyzer

    2.4.3 Smart Jump
    ----------------

    The Semantic Analyzer can be used to jump directly to the definition
    for a code symbol.

     -- Command: semantic-ia-fast-jump pos
         Jump to the definition for the symbol at POS.  Called
         interactively, POS defaults to point.

     -- Function: semantic-ia-fast-mouse-jump event
         Jump to the definition for the symbol at the position of the mouse
         event EVENT.  This command is meant to be bound to a mouse
         command, like this:

              (global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump)

       These commands are often more accurate than than the `find-tag'
    command (*note Tags: (emacs)Tags.), because the Semantic Analyzer is
    context-sensitive.

       You can also use `C-c , j' (`semantic-complete-jump-local') and `C-c
    , J' (`semantic-complete-jump') to navigate tags.  *Note Semantic mode
    user commands::.  Those commands do not make use of the Semantic
    Analyzer.

So the only actually _existing_ keybindings we find in the
Analyzer/Smart Jump subnode tells us about keybindings that don't
actually use the analyzer.

> Do you have something specific in mind about what is missing?

There is so much in there that does not seem applicable without
reverting to Elisp programming that the few things that would likely
_be_ relevant are hard to find among the rest.

The manual needs to funnel out everything that is not at user interface
level.

-- 
David Kastrup