Task: Automatic and on-line documentation

The purpose of this task is to add documentation to the interface and internals in a programmatic way using Scheme: this means documenting keyboard shortcuts, menu items and Scheme code. The documentation should be both compiled dynamically and extracted from reference guides. You can contact Miguel de Benito Delgado with ideas, praise or hate for the bugs in his code. Any offer for help will be especially welcome.

Note 1. As of TeXmacs 1.99.1 some of the features described here are implemented in a rather alpha state. However, code browsing, tab completion and contextual help (gathered on the fly and cached from the manual) inside any Scheme tag (i.e. scm, scm-code, Scheme sessions) should be more or less usable. If it doesn't work for you, please contact

Here are some notes taken in 2012 while thinking about the problems related to this task. Please note that they might not be up to date. In particular some of these ideas might have already been implemented or dropped.

1.Keyboard Shortcuts

In a first approximation, a list of the available shortcuts should be compiled depending on the current mode and presented in a new buffer. Besides each shortcut, the corresponding menu entry (see below for some comments on the menu tag) should be displayed along with a little explanation and link to relevant documentation. Although highly desirable, this feature is far from optimal: it would be best to allow configuration of the shortcuts at the same place where they are displayed. Maybe implement a shortcut editor?

2.Menu items

Every action the user can take using the interface should be documented. Besides the obvious tooltip, one mechanism to achieve it is a “What's this?” feature. Here are some requirements and ideas related to it.

1. Popups should be full texmacs-output widgets (to allow for markup and math) and include links to more extensive documentation.

2. All menu items should be documented in a standard location for documentation: "doc/some/module/maindoc.tm#funcname", for instance. The documentation should be command dependent: relocating the commands in new menus or widgets should have no effect.

3. The documentation of a particular item should reflect the places where this item is accesible. For instance, the documentation for “Update all” should include the fact that the command is accessible via Document→Update→All. Ideally, clicking on this very tag menu would popup the menu and display the item.

4. A new “What's this?” mode should be added to the editor:

   • S+F1 should pop up the “What's this?” balloon for the widget under the pointer or at least enter the mode and let the user click on anything he wants explained. Then ESC or some key to exit it.

   • Better: just pressing some modifier key activates this mode: any click over a widget should tell it to display its “What's this” information. This can be sent up the chain of widgets until someone catches it.

   • The mouse pointer should change to an arrow with a question mark or something similar.

5. Support for the feature must be added to abstract widgets, WidKit and the Qt port. This is needed to better document dialogs, since items in dialogs have no meaning isolated from the others or aren't even linked to commands, as is the case for forms.

   • There is already a balloon widget which provides a tooltip for buttons. Like this:

     Scheme]

     (tm-widget (tooltip) (balloon "Some nice text" "Some nice tooltip"))

     ((guile-user) (guile-user))

     Scheme]

     (show tooltip)

     But what we'd like is balloon to provide a tooltip for the widget it encloses

   • We want a SLOT_WHATSTHIS (do we?). How do we implement it, exactly? Keep in mind that the popup must support full texmacs trees.

   • Maybe new properties for widgets: string whatsthis; url docs;

   • Problem: things will inevitably go out of sync. A possibility is to add a timestamp check on the module definition file and the documentation file, then warn the user in the help page or even in the popup that the docs might be outdated (ugly).

3.Scheme code

Some steps have been taken with the items in the menu Developer, but its quite lacking. Ideally we want:

1. Detailed documentation of each exported function and each module in TeXmacs. This should include functions in the glue. In progress, but this is a huge task.

2. Contextual help inside scheme tags and sessions and open scheme files. Either using right click and a menu, or some modifer + click to jump directly to the docs (use the same as in the “what's this?” feature). See link-navigate.scm. A side panel could be showing them constantly. (Done, but the list of symbols is not complete. Needs a real parser.)

3. This includes seeing the documentation as well as being able to edit it, for example adding a menu item to help buffers: "Save documentation". This would really help to improve the docs.

4. Add some "Search in public functions…" which does not grep. It has to be fast. (Done with the widget in Developer→Open symbol browser..., but again the list is incomplete)

5. Tab completion inside scheme sessions and open scheme files. This includes a list with the arguments of functions and their type (extra markup needed in the docs to tag this). (In progress: the list is incomplete (no glued functions, no builtin functions) and no parameters. Needs a real parser.)

6. Make everything inside scm, scm-code tags clickable using something like ⌥+Click to navigate. Done.

Problems

• Things will go out of sync. Some time-stamping or checksum is necessary to check whether the docs might be outdated. Alternatively, developers should be very careful of updating their documentation.

• The list of available modules and exported functions is huge. Keeping the documentation in conventional files organized in directories can become a mess. But a central database can be bad for version control.

3.1.

Modules documentation

This is an example of the format the module documentation has (we make extensive use of folds and links which won't display on the web). To see it in TeXmacs use the Developer or Help→Scheme extensions menus.

Exported symbols

(with bla (absolute-function some arg)
  (do this and that))

(tm-define (absolute-function some arg)
  (perform-ultimate-computation)
  42)

Fixmes and To-dos

FIXME: why does this not work?

(line 111 of some-module.scm)

Click the link to jump to that line in the file. Here you have lines of context:

           (list ,@(map (lambda (m)
                         `(list ,@(compile-interface-spec m)))
                       modules))))
      ;; FIXME: why does this not work?
      ;; (define-macro (import-from . modules)
      ;;   (define (import-from-body module)
      ;;     `(module-use! (current-module) (resolve-module ',module)))

FIXME: why can't we use procedure->macro

(line 59 of some-module.scm)

Click the link to jump to that line in the file. Here you have lines of context:

(if (guile-a?)
    (define-macro (define-public-macro head . body)
      `(define-public ,(car head)
         ;; FIXME: why can't we use procedure->macro
         ;; for a non-memoizing variant?
         (procedure->memoizing-macro
          (lambda (cmd env)
            (apply (lambda ,(cdr head) ,@body) (cdr cmd)))))))

4.Other ideas

Help for writing documentation

1. Add a menu entry with the "documentation tree". Clicking on an item should add a link to that section in the current document. Maybe a tree representation in the side panel would be better.

   1. The link shouldn't be a simple hlink tag. Use a specific tag which substitutes either the title of the section (while browsing the manual online) or the chapter/section number (if in book mode).

   2. Problem: the current help menu is built manually in help-menu.scm, no tree is available, so we'd have to traverse the docs first and build it (maybe check the manual generation routines).

TeXmacs as an IDE to itself

Some of the things considered above are first steps to TeXmacs as an IDE to itself, with other desirable features being:

• Jump to code when clicking on an item in the GUI.

• Setting breakpoints inside open scheme files.

• Having a scheme session in a split window. This is already achievable with the new widgets, but having a REPL acting on the “main” buffer would be cool.

• Reliable mechanism to reload modules.

• Jump to the definition of any symbol clicking on it. Done, but needs a real parser. Yes, yes…