Comment dois-je fournir de l'aide pour un ensemble de fonctions connexes?

Question

J'ai construit tfs.el pour permettre aux développeurs de faire des choses TFS (checkout, checkin, etc) à partir d'emacs.

Il y a 13 commandes interactives dans le paquet de TFS, comme tfs/checkout, tfs/rename, tfs/diff, et ainsi de suite, et je voudrais être en mesure de fournir une aide sur chacun d'eux en un seul endroit. Un aperçu de toutes les fonctions disponibles.

Quelle est la "façon emacs" de le faire? J'ai pensé à définir une fonction supplémentaire, comme tfs/help, qui invoquerait describe-function-1 sur chacune des fonctions tfs, puis présenterait tout cela dans un tampon d'aide TFS.

Y a-t-il un meilleur moyen?

Answer 1

Vous pouvez utiliser

(describe-bindings "\C-xv") 

Answer 2

Eh bien, il y a beaucoup de "Voies Emacs".

Le plus poli serait d'écrire un information page, consultez la page "Info for Experts", qui dit essentiellement à utiliser Texinfo et convertir en une page info . Vous pouvez être aussi bavard que vous le souhaitez, et l'utilisateur peut rechercher, utiliser des hyperliens, etc. L'utilisateur peut facilement y accéder via C-h F tfs/checkout.

Une autre façon certaines personnes semblent le faire est d'écrire de courtes chaînes de documentation pour chacune des commandes, se terminant par « voir la documentation tfs-mode pour plus de détails » et de mettre toute la documentation commune dans le docstring pour TFS mode.

Une autre façon dont certains paquets documentent les choses est avec un gros commentaire en haut du fichier tfs.el. Faites votre choix, ils ont tous des compromis.

Answer 3

Vous avez plusieurs, les commandes connexes. Jusqu'à présent, je suppose, ils ne sont liés que par leurs noms.

Deux possibilités viennent à l'esprit:

• Créer un mode pour ce genre de choses. Documentez tout dans la chaîne doc de la commande qui active/désactive le mode. Ce pourrait être un mode majeur ou un mode mineur. S'il s'agit d'un mode mineur, il peut s'agir d'un tampon local ou global.

• Créez un groupe (defgroup) pour ce genre de choses et documentez tout dans sa chaîne doc.

L'idée de base est d'une certaine façon en fait concernent ces commandes: les regrouper en quelque sorte, afin que vous puissiez les documenter ensemble comme la doc pour le faisceau.

En passant, sans en savoir plus, je suppose que vous pourriez vouloir créer un mode mineur global.