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.

7 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