Of chickens, eggs, and shadows thereof

Cedric Duval cedricduval at free.fr
Fri Jun 19 01:23:24 CDT 2009


We currently have a number of issues regarding the extensions and
their help screens.


First, a chicken and egg problem. Many of them sport a text telling
the user that to be used, this extension may be enabled by adding
the following couple of lines to the hgrc:

  [extensions]
  hgext.foo =

That's all nice, but the users will never see that helpful piece of
suggestion unless they have enabled the extension in the first place. :)

Likewise, we are currently trying to give more meaningful headlines for
each of them, in order to provide a good overview of what the various
extensions do. But again, the users will see them only once they have
chosen to activate the extension, by which time they presumably have
gained sufficient knowledge about the given extension that this headline
has outlived its usefulness.


I think that it would be good to have an additional help topic,
"extensions", that would:
 1/ explain how to enable an extension in a general manner
    (no need to repeat that for every extension, especially so
    in a belated way)
 2/ list the currently enabled extensions
    (like the main help already does)
 3/ list the extensions not enabled but which are available
    from the standard lookup path, along with their short headline

The third point would give the users a chance to reach the information
they need before choosing and enabling an extension (additionally, it
may also be nice to access the full help of an extension known to exist
but not yet enabled). I'm not sure how doable this listing is, all
Python files that reside in the standard paths are not necessarily
extensions (__init.py__, subdirectories, etc.). Perhaps a gettatr()
call to check for a common property inside each extension module?


A different problem is that some extensions (like bookmarks) have a nice
general help text, but it will unfortunately never be shown to the user,
because it it shadowed by the help of the command of the same name.
How do we provide access to this text? Or should we remove it altogether,
after merging it with the command's help?

(besides, I really think that the command for setting a bookmark should
have been a verb. But that is a different issue. :) )

One way of solving this might be, in the help of each command provided
by an extension, to have an indication on how to access the more general
help text (like is already done the other way around, giving the list
of commands provided by the extension). Such cross-reference would
additionally bring to the attention of someone reading eg. about the
'email' command, that the 'patchbomb' topic might also be an instructive
read.

Sorry, no patch here, just a bunch of issues for discussion and
hopefully finding solutions.
-- 
Cédric


More information about the Mercurial-devel mailing list