Org-remark introduction video (formerly, Org-marginalia)

Many of you share an interest with me in note-taking with Emacs and Org mode. I have done a quick introduction video on Org-remark, a package I have been developing and using. It lets you highlight and annotate any text file with using Org mode.

I will really appreciate it if you could give me any feedback / comment you might have on the package, and perhaps on the video as well :wink:

I would like to submit it to ELPA soon-ish.

GitHub Repository
ā€£ GitHub - nobiot/org-remark: Highlight and annotate any text file with using Org mode

User Manual
ā€£ Org-remark User Manual

I have had Org-marginalia as a prototype for about a year or so (this topic in this Discourse forum) and finally managed to give it a full update. I have also changed the name to Org-remark.

9 Likes

Very cool. It seems similar in spirit to org-noter, but with some nice added features thanks to the source documents being plain text buffers.

Thereā€™s of course some duplication with org-noter, which seems to have stagnated a bit. Do you have any plans to add support for PDF and Epub formats, or will you continue using org-noter for those? Nov.el buffers could potentially benefit from the highlight colors, for example. Iā€™m not sure if itā€™s possible to render the highlights with pdf-tools, but even if that piece is not possible it still seems like it would be beneficial to have all your notes use the same package for consistent buffer layouts, keybindings, and available extra functionality for acting on notes. Of course, org-noter is certainly still usable, so it would make sense if you preferred not to have to deal with those formats for org-remark.

Thanks for your work! Looking forward to trying it out.

@liam
Thank you for the comment. Appreciate your perspecitve.

I donā€™t think Iā€™ll add PDF and Epub formats to Org-remark. Itā€™s beyond my skill set. I believe Org-noter is fantastic and works well as is for its purpose. This way, Org-remark can focus on what it is designed to do ā€“ highlight and annotate plain texts.

Having said this though, do you think there is a way to present consistent experience to users of both packages ā€“ such as the way notes are generated or some keybindings? I donā€™t use Org-noter at all, so hard to identify where consistency can be created.

Or it may be already sufficiently consistent because both use Org files as note database? Users may switch context between a plain text file vs PDF files, thus donā€™t care about consistency that much?

That sounds reasonable.

As for a consistent experience across packages, Iā€™m not sure what the best way would be, as Iā€™m only a light user of org-noter as it is. I guess I was thinking out loud. I doubt theyā€™re that inconsistent as it is, and it would probably be pretty simple for users to configure similar keybindings and window configurations. And youā€™re probably right, minor inconsistencies wonā€™t be hard to ignore.

1 Like

Cool! :+1:

I guess there will be problems if you change the text, though, right? Like when I insert new words in front of a highlighted word, its absolute position changes so the highlight would stop to be placed correctly, right?

Besides, I wonder if it wouldnā€™t be preferable to include the source filename in the remarks filename? Otherwise, it might be problematic to have multiple annotated files in the same directory, right? Another way around this would be to store the annotations within the same file, of course. This would be closer to how one deals with footnotes then.

@wuqui
Thanks for the questions and I believe the current version covers all your points. I might include some of these in the user manual.

No worries. The highlights are overlays so inserting characters before them moves the highlights accordingly ā€“ highlights wonā€™t get dislocated from the original phrases. Try that :smiley: Maybe I should show this in a second video.

The ā€œmarginal notes fileā€ stores locations like this below; it is designed to organize highlights / notes for multiple files and multiple highlights. Consider this as a plain-text database using Org.

* File 1
** Highlight 1 in File 1
** Highlight 2 in File 1
[...]
* File 2
** Highlight 1 in File 2
[...]

You can customize the file path for the remark file (marginal notes file) with org-remark-notes-file-path in the way you like, so you can have one remark file per source file if you like. You can also include the source fileā€™s name as part of the remark file name, too.

You can do this if you like, for example: (setq org-remark-notes-file-path (buffer-file-name)). This wonā€™t work when the source file is non-Org plain text files, though. Org-remark should work on any text files.

1 Like

Thanks for your quick reply! Sorry, I didnā€™t have the time yet to try these things myself yet. I should have. Iā€™m pleasantly surprised all of that is working so Iā€™ll give it a try soon :slightly_smiling_face:

1 Like

It will appear in ELPA soon (hoping in a few hours time; it is already added ti the repo and waiting for daily sync).

EDIT: It is now available as a ā€œpublic betaā€ in ELPA-devel (see README of GitHub repo). I will need a bit more time to release it to ELPA as a ā€œstableā€ release ā€“ I have received good feedback on emacs-devel mailing list and a patch suggestion. Iā€™ll incorporate these and write documentation before releasing to ELPA as version 1. Thank you :slight_smile:

Iā€™m trying to set org-remark-notes-file-name so that each file has a corresponded notes file in a specific directory. I thought I could do that using

(setq org-remark-notes-file-name (concat "~/org-roam/highlights/" org-remark-notes-file-name-function))

But the above got me an org-remark-notes-file-name-function is void error, so Iā€™m not sure if my approach is right at all.

Your approach is fine.

EDIT: Actually, no. Sorry. (org-remark-notes-file-name-function) returns the absolute file name of a file; my previous suggestion wonā€™t work.

(Removed my previous code suggestion)

A key thing is that org-remark-notes-file-name-function is a function, so you need to surround it with a set of parentheses to call it.

As it returns an absolute file name, youā€™d need to get only a part of the name (i.e. remove the path part).

Maybe this:

  (setq org-remark-notes-file-name
      (concat "~/org-roam/highlights/" (file-relative-name (org-remark-notes-file-name-function))))

This above assumes you have no sub directories in your org-roam-directory.

If you have sub directories, an alternative might be something like this

  (setq org-remark-notes-file-name
      (concat "~/org-roam/highlights/" (file-name-base (org-remark-notes-file-name-function)) ".org"))

Thank you! I feel super foolish for not realising I wasnā€™t calling org-remark-notes-file-name-function as a function.

Iā€™ve set my org-roam-directory variable to just ~/Documents/org-roam, although I do have subdirectories in that directory.

Iā€™ve tried both versions and get the error ā€œWrong type argument: stringp, nilā€. I tried evaluating just (org-remark-notes-file-name-function) and got the same error. Tried evaluating the variable org-remark-notes-file-name and the output was ā€œmarginalia.orgā€ (which makes sense as itā€™s the default). Tried evaluating (setq org-remark-notes-file-name (org-remark-notes-file-name-function)) in scratch and still got the wrong argument type error.

I can try to progressively remove stuff from my init to figure out what could be causing the issue. Maybe some other package is interfering?

Try it in a buffer visiting a file in Org-roam, or any buffer visiting a file. Scratch buffer does not visit a file; that error is expected there.

Iā€™ll see if I can address the case when the current buffer is not visiting a file.

Edit: In additionā€¦ I just realised there is an issue with this approach:

(setq org-remark-notes-file-name
      (concat "~/org-roam/highlights/" (file-name-base (org-remark-notes-file-name-function)) ".org"))

It will fix org--remark--notes-file-name to one file name.

In order to dynamically change the file name per file, you need to set the variable to a function. Soā€¦

(setq org-remark-notes-file-name
      (lambda ()
        (concat "~/org-roam/highlights/"
                (file-name-base (org-remark-notes-file-name-function))
                ".org")))

Or create a custom function and then set it to a variable (Iā€™d prefer a named function like this):

(defun my/function ()
  (concat "~/org-roam/highlights/"
          (file-name-base (org-remark-notes-file-name-function))
          ".org"))

(setq org-remark-notes-file-name
      #'my/function)

Just tested this out and it worked perfectly. Thank you!

1 Like

Dear nobiot,

Thanks a lot delivering Org-remark behaviour.
Unfortunetly, I can not remove [red-line-pen].
But strange to say, [Highlight with yellow pen] have
No problem with hightlight color-removing.
How can I do remove red-line from my test.txt.
I look forward to hearing from you at your earliest convenience.
My circumstances : OS 10.14.6 Mojave
0.999.0@28.0.92 (spacemacs)
Yours, WAKAMATSU
spacemacs-org-remark

P.S
With org-roam capture file have the same symptoms.

I have a feeling that the underline is done by another package such as flyspell-mode. Can you check that please?

Dear nobiot,
Thanks a lot.
I have ckecked flyspell-mode, which dormant behaviour in turn I never use it. could be block out.
When I set the function off. erasing red-line pen behaviour is backed on track.

How do I configure flyspell-mode to not function normally in org-remark? What is the best way to write?
Yours, WAKAMATSU
P.S
Can I add something like this to prevent it from working?
(use-package flyspell
;; flyspellć‚’ć‚¤ćƒ³ć‚¹ćƒˆćƒ¼ćƒ«ć™ć‚‹
:ensure nill
;; org-remarkćƒ¢ćƒ¼ćƒ‰ć§flyspellć‚’åœę­¢ć™ć‚‹
:hook (org-remarkā€“mode . flyspell-mode))

P.P.S
In an environment using Japanese
Type M-x flyspell-prog-mode and press
for this mode for the current buffer.
I would like to enable and disable the setting.

The message "Error enabling Flyspell mode:
(Error: No word lists can be found for the language ā€œja_JPā€.)
is came up and the function switching cannot be executed.
Is it necessary to change the Ispell function first?
Yours,WAKAMATSU

I have no idea how to configure Spacemacs. I suggest that you ask the question in their forum.

Dear Nobiot,
I do not know why, but after trying to add 1 &2,
then comment-out for addendum everything,
with the result that I got remove-behavior, now.

  1. (add-hook 'org-remark-mode-hook (lambda () (flyspell-buffer -1)))
    With this addition, ā€œred-line penā€ remove now works.

  2. add-hook 'org-remark-mode-hook (lambda () (flyspell-region -1)))
    The ā€œred-line penā€ delate worked with the normal functioning.
    red-line pen ---------->> [delete from Menu] carry out a function

Yours, WAKAMATSU [2022/03/25 17:58:19]

P.S
Currently, I am using [ .spacemacs] , which does not add anything.
Your org-remark is all functioning.

1 Like