Add comment facilities to TeXmacs

[mgubi]

[cloned from the mailing list texmacs-users]

Discussing with some friends I became aware of some advantage of unstructured editing for which we should provide some alternative. This is the possibility (common in programming, but also in some research workflow) to add comments on a document which will not appear in the final version (i.e. in the PDF, on in the HTML or LaTeX export – In some sense, the dual of literate programming, maybe we can call it co-literate editing :)).

These comments can be parts of the document one do not want to make to the final version, or just reminders to explore some directions, or parts one has to cut because of editorial constraints or referees comments, but anyway one wants to keep in place and not just delete them (because maybe the paper has a short and long versions). These comments can also be simply discussion between various co-authors, so it would be nice if they carry tags, like the name of the author. And then have a macro facility to view only certain subclasses of comments and make them invisible (i.e. just leave a flag or some other indicator which do not modify the typesetting) if the user wants. This should not be difficult to code, is something similar to the versioning markup we already have, but I think it would be a useful addition to everyday workflows.
It could also be a way to edit the metadata in the document.

Of course one has (at least) two options to design such a facility: make the additional content editable as part of the document (as in the proposal above), or keep it in the document as always invisible and make it editable only via some separate GUI element, i.e. a dialog with an embedded editor (like we have now for search and replace, for example, or for the macro editor). I think I would prefer the first approach, though.

Thoughts, ideas, comments, on such a facility?

ps: on a similar direction a document can have a “draft” mode where markups like \todo or these comments are visible and a “final” mode, where they are invisible.

[mgubi]

Note that this topic is connected with “Tricks for drafts”:

Tricks for drafts

I don’t really know how to prevent marginal notes from showing up in a pdf. Another option you could try is to use a flag, with the <flag|content|colour> syntax, e.g. <flag|todo|red>. These are hidden in the pdf, but can be shown on screen by going to “Document->Informative flags” and selecting “Detailed”. They can’t really hold much text, though.

[mgubi]

Joris already implemented some comment support I’ve looked at it and wrote a description of the implementation here:

https://texmacs.github.io/notes/docs/comments-in-texmacs.html

[JoyYang]

My current solution for comments is just to have a separate TeXmacs document, which works fine. This works just as the latter method. In this regards, the first approach sounds more interesting.

I wonder how the collaborative experience is like on the current TeXmacs implementation. It works great as an independent contributor to a publication, but I have a hard time imaging how it works when there more than 1 people are editing on the same document.

[mgubi]

I’ve tried the new comment facilities added for the next version (1.99.17) and they seems good, Joris made a great work there. Also there is some collaborative features in the workings for the (near) future.

[JoyYang]

Awesome. Can’t wait for those! What’s left is for me to convince (force) my collaborators to adopt TeXmacs .

[fbob]

I’m looking for a way to hide some contents inside a document.

The comment facilities look to be good candidates for that.
It works (contents are hidden) but the counters (figure number, equation, …) are incremented as if they appear in the document.

Is there a workaround for this, or can I use another tool to hide some contents in a document ?

Thanks for your feedback.
Have a nice day.

François

[jeroen]

You could disable certain counters temporarily with something like

<with|next-equation||...>

but then you’d have to do that for equations, figure, tables, etc.

Depending on your use case, you could also ignore it while editing and redefine the comment macros to do nothing when you’re done?

[fbob]

Thanks @jeroen for your feedback and advice.
My needs are pretty simple in fact: I just want to hide or reveal some exercises from a document (which contains a bunch of exercises) without the need to have different files for the different versions.
The comment macro is perhaps not the most appropriate tool for that.

[re4zuaFe]

This should be doable via foldings, although I did not try it. You could see that, there is a functionality of hiding exercises and solutions in the education document styles. If I understand correctly, this is implemented by Scheme, so it should be possible to mimick that code.