Documentation and discoverability of packages

Hello again, another beginner’s question: where should I look for information about TeXmacs packages? I am writing some notes and wanted to leave a margin (or collapsible) todo note. In the end I discovered the \todo macro. In the packages menu I saw some other packages e.g. chat-rooms. I thought it implemented a “chat” functionality in the document that I could use to “chat with myself” (that was a stretch, I know). However, when I enabled the plugin I could not at all figure out what it did. I even opened the source of the plugin but there was nothing. Is the documentation absent or am I looking for it in the wrong place.

This post is mainly meant to confirm that I am not missing something.

Here comes a possible suggestion that may be freely ignored: maybe, there should be a default place for package documentation and if is missing one should have an empty section with “TODO” rather than it now being there. Coming from emacs, it was very discoverable because an introduction to anything is supposed to be available as the docstring to the function whatever-mode that enables a mode. If it was missing from there then I knew that it was incomplete.

Thanks!

2 Likes

The current todo seems convenient for me because I also use it to make comments on what I wrote.

It is now also possible to use the comment package.

As far as I know packages do not have a standard documentation, unlike plugins that have it. I agree that it would be nice. I am interested and I will look into it, but I do not promise that I will be quick and that I will succeed :slight_smile:
By the way for user-written plugins I was expecting that TeXmacs would recognize the help files (abstract and demo) and it did not happen, I wonder if anyone knows anything about this.

Giovanni

Some of the packages have a (very) short description that appears when you hover the mouse cursor above the menu item (TeXmacs/progs/generic/document-style.scm). This list is quite incomplete and could use some love.

Some of the packages that are not described in this way have a description in the source file as a src-purpose tag. However, some of these could be improved as well. For example, chat-room.ts only has “Chat rooms” as description.

We have a documentation system. When you are in a macro you can press the icon “?” and have an help page on the macro, showing its definition and (if present) a description. I do not know exactly how it works, I would have to research it. Descriptions of macros cannot be in the source file since you want them localisable, so they have to be put in a different file, for example for the “\quotation” tag the english description is in the file $TEXMACS_PATH/doc/main/styles/std/std-markup-dtd.en.tm. I’m not sure how TeXmacs looks for these files but it seems possible to extend the help for other macros which do not have now. Probably these files are also used to generate automatically an index of all the macros and their description.

The chat style file is used by the chat system. We have a server (in Bonn) where people can connect and have a chat or work on shared documents. You can have your own server by launching TeXmacs with --server. All this is not (yet) documented of course :slight_smile: