Re: EDE documentation

Eric Ludlam <[email protected]> writes:

> I took a stab at completely revamping the EDE documentation organization.
>
> I'd be very interested in peoples thoughts on this organization, and if
> you think it will help.

I read thru ede.info:

In general, this is a big improvement! It's much easier to understand
what is going on with project detection.

In general, there are more `require's needed with the bundled CEDET than
with CEDET from a SourceForge checkout (accessed with
cedet/cedet-devel-load.el). It would be better if
cedet/cedet-devel-load.el mimiced the bundled environment more closely
(same set of preloads/autoloads), so this issue was clearer to the CEDET
developers.

The SourceForge code seems to be currently in transition between Emacs
24 and Emacs 25. It contains (require 'cl-generic), which is not in
Emacs 24 (there is a Gnu ELPA package for it). With Emacs 25, I get
errors like: eieio-oref: eieio-oref called on a class:
ede-generic-target-c-cpp. In Emacs 24, cedet/cedet-build.el cedet-build
gives an error: byte-code: Symbol's function definition is void:
eieio-make-class-predicate.

So in the following comments, I'm using SourceForge CEDET, compiled and
loaded in Emacs 25 (attempting to ignore the errors). But the comments
about `require' come from trying to use the bundled CEDET.

- Top node second paragraph

  Using EDE is _not_ as simple as
  '(ede-minor-mode 1)'; it also needs (require 'ede).

  Perhaps should add ;;;###autoload to ede-minor-mode? and
  global-ede-minor-mode.

- 1.1 What is a project

    suggest: "a project consists of a directory hierarchy, a set of meta
    data, command features, and a set of targets.

    This section does not mention cross-reference or find-identifier
    tools, but later it says some are supported (Gnu GLOBAL, for
    example). So that should be mentioned here.

- 2 Quick Start - wrapper

    also need (require 'ede) in ~/.emacs

    and if need emacs project type; (require 'ede/emacs)
        same for other project types? not tested with bundled CEDET
        possibly add ;;;###autoload to ede-emacs-load


    Android project worked (detector has autoload)

    For Arduino projects on Windows, need:

    (setq ede-arduino-preferences-file
      (expand-file-name (substitute-in-file-name "$APPDATA/Arduino15/preferences.txt")))

    I'm not sure where the "15" comes from; I'm using Arduino 1.6.4.
    
    In addition, there's a problem with the Arduino auto-detect on
    Windows; the sketchbook directory has \ in preferences.txt, but it
    is compared to buffer-file-name, which has /. So ede/auto.el
    ede-do-dirmatch needs an 'expand-file-name' in (setq matchstring
    ...). I didn't actually edit the code and test, because I'm not sure
    that change is ok in general.

    The list of Wrapper Projects is longer here than in the Wrapper
    Projects section; I guess there is more manual to be written.


    It would be good if there were a menu item that displayed a list of
    the project types currently auto-detected. That is simple to extract
    from ede-project-class-files.

    Then this section can say:

    "To see the list of supported generic projects, invoke the menu
    Development | Project Options | Show auto-detects"

    I don't have examples of all of the project types listed, so I
    couldn't test all of them.

- 7 quick-start - from scratch

    I didn't do any of the steps, but this looks quite thorough and
    readable.

- 8 Managed Projects

    This section needs an intro; what is a "managed project", and why
    would I choose this over the other options? How is this different
    from section 7?

    I think this section is about adding an EDE project to an existing
    source tree that does not match one of the wrapper patterns.

    ede-new prompts for a "Name: "; the info file should say how it will
    be used.

    It then adds the project directory to the custom variable
    ede-project-directories; the info section should say that.

    I tried to do these steps.

    ede-new worked

    when I tried to do ede-new-target, there was no Project Options
    submenu. M-x ede-new-target worked.

    add file: there is a Development | Target Options | Add File menu
    entry, but it complained "wrong file type"; apparently you can't mix
    file extensions? On the other hand, I have no idea what file type it
    was expecting; that should be in the error message.

    (I'll just keep writting my Makefiles by hand :).

    When I restarted Emacs (I had some edebug stuff that just broke),
    the new project was not automatically recognized. I think I know
    why, but the info did not say anything about that. So I tried
    Development | Load Project, and Emacs crashed.

    More later, after I debug that crash.

- 10 Misc

    ede-find-file does not do completion on the file name. I looked at
    the code; it looks complicated, because of the locate objects. Emacs
    has very nice file name completion now, so it would be good to
    improve this. The Emacs filename completion takes a flat list of
    directories (like load-path or compilation-search-path), so we'd
    have to construct that out of all the locate objects. I'll look into
    it more.

11 - not read, since it says it needs work. But I'll get back to it later


Thanks for your work on this!

--
-- Stephe

------------------------------------------------------------------------------