Can someone explain the org-roam menu items in plain language?

Troubleshooting
1

When I’m editing a note, leader + n r takes me to the org-roam menu. I cannot really tell what these items all do, how they differ, and why they are here rather than in other menus. I assume that the functions are transparent to experienced Emacs users, but hopefully someone will shed light. I also make suggestions for wording changes to make things easier for new Emacs users. I assume that some/all of these will be shot down as unnecessary as “the way Emacs does things”, but no harm in trying.

b -> switch to buffer

  • Emacs already has many methods to switch between buffers. Why is this option on a menu specifically for org-roam?
  • If it shows only a subset of existing buffers, can this subset be described?

c -> Org Roam Capture

  • Why are all words in this and the “Org Roam” items capitalized, but not all words in the other items?
  • Why does this take me to a list of existing files? I assume that “capture” means that I am going to create a new file. But if I “capture” and select an existing file, it opens it for editing. Is this just an instance of Emacs language that is strange to outsiders?

f -> Find file

  • is this action different from c -> Org Roam Capture in any way?
  • I know that in Emacs the process for creating a new file can be the same as for finding a file (is it always the case?). Can f and c just be one item, Find or create file?

g -> Show graph

  • I suggest renaming this ‘Show note graph’

i-> Insert

  • I suggest renaming this ‘Insert link to file’
  • n r c, n r f, and n r i all show the exact same interface File: despite seemingly offering different functions. This is super confusing (for me at least). Is it possible to make this action present a prompt Insert link to file: rather than just File:?

r-> Org Roam

  • This label doesn’t suggest any action. Aren’t I already using org-roam? How about Show [or Toggle] backlinks panel?

d -> +by date

  • Do what “by date”? Is the + supposed to stand for “Add new file” or for “this item will give a menu of further choices”? If the latter, maybe rename to “Add file by date”?
  • Why does the process of creating a file +by date differ from all the other ways? The others all involve a find file interface and new files are shown through in a capture window. This one creates a new file with a date title without asking you to find a file and doesn’t have the capture window items like C-c, C-c to finalize. Is there a reason for this?

Thanks for answers and comments.

2

It switches specifically to an existing org-roam buffer. It also uses the title rather than the filename like typical other buffer switchers. This action is described in the docs through C-h f org-roam-switch-to-buffer. This function name can be discovered (your key config may differ) through C-h k SPC n r b. Using C-h v/k/f is definitely the “emacs way” and is highly recommended as a way to learn emacs and its packages generally.

The description, “switch to buffer” I think has an implication that it is for org-roam specifically because it is under the org-roam menu. It would be considered redundant to specify org-roam at that point.

I’m not sure about the Org Roam Capture. It appears to let me create a new note with a duplicate title? I just use find-file, which as you say prompts with capture for non-existing notes.

The prompt for File: is the same because you are being prompted for a file in all cases. The context for the prompt is handled by how you got there (your example of Insert link to file: could also be interpreted as an action to insert a link into the selected file, rather than using that file as the link).

I have no opinion on the other renaming suggestions!

4

Can you tell me the functional difference between the org-roam-find-file command and the org-roam-capture command in this context? (please see bottom of comment before telling me to check in the documentation)

i.e. “You are supposed to know the difference without anyone explaining it” :slight_smile:
Is this written somewhere or is it supposed to be obvious to anyone with a brain (which apparently excludes me)?

Maybe we just disagree, but I don’t think “insert link to file” is easily interpreted as “insert link into file”. Certainly, it is less ambiguous than a bare File: prompt.

This comment is not aimed at @alan, who was kind enough to respond very helpfully, and I suppose that this is a bit off topic, but the fact that this is the “highly recommended” way to learn emacs completely explains why emacs is barely known in the general population. Consider: outside of emacs, there is a well-known distinction between reference materials and teaching materials. Emacs documentation is reference material, written by and for those who already know and understand the context of all of the information inside. Asking someone to learn emacs by reading the reference documentation is exactly like telling an English speaker to learn to read French by giving them an English-French translation dictionary. All of the information is there, so it is possible, but it is absurdly difficult.

5

Hi @cobblepot ,

I assume you are talking about this, when you say " leader + n r takes me to the org-roam menu". See the screen capture below.

Notice that mine looks completely different to yours. You told me that you were using Doom Emacs, so you would be able to personalise your menu as I have done mine.

Your point taken; some of the default Emacs prompts and explanations are rather terse.
I suppose this is historical. Emacs was born when computer resources were not as inexpensive and good as they are now. In the comand line, cd is change directory, and wc is word count (I think).

There are many more modern ways (like this one) to overcome that legacy. I don’t pretend that I can speak on behalf of the community at large, but there are good things about both old an new in Emacs (and many other things around computers).

image
image675×706 36.9 KB

image
image729×385 24.8 KB

6

It looks like the behavior I mentioned has been fixed since yesterday org-roam-capture inadvertendly creates new file · Issue #766 · org-roam/org-roam · GitHub

In this case the functional difference is that find-file will simply open an org-roam file if it exists, while capture allows you to capture more content to an existing file. If the file doesn’t exist, both will create it with a selected capture template. Behind the scenes, org-roam-find-file calls to org-roam-capture if the file doesn’t exist. So it’s just a question of whether you want to completely open the file, or simply capture to it.

I’ll have to let someone else speak to why you would call capture on an existing org-roam file, since I don’t use org-capture like that. Normal org-capture can do things like capture new timestamps to a single journal file. So presumably you could do something like capture under a specific headline in an org-roam file, or pre-fill template items like when you first create the file, rather than having to open the file and manually navigate, copy/paste, etc. Even without doing anything fancy though, calling org-roam-capture on an existing file would let you add content to that file without navigating away from your existing buffer – an easy way to add a one-line thought to something without a big interruption, I suppose.

Something to keep in mind is org-capture is a separate entity from org-roam, and so at a certain point your question becomes more about the behavior of org-capture itself, rather than org-roam-capture.

I suppose that’s one way to say it :smile: If you know insert will insert a link to a file, then you are prompted for the File: you want to link to. If you are opening a file, you are prompted for the File: you want to open. If you don’t know what a function is doing, then the prompt is not so helpful in figuring that out by itself. That’s when you C-h f to read the function docs :stuck_out_tongue_winking_eye: In all seriousness, the prompts are very easy to change, so if you really think a more self-explanatory prompt would be useful for beginners then you should open a github issue!

I can’t personally speak to 40+ years of emacs history. There’s a reason this graphic exists! :smile:
image

There’s also a reason people refer to emacs as an OS with an editor attached :yum: Aside from just getting Windows started, it’s a lot to ask for ‘teaching materials’ for Windows at large. Which part? For what purpose? What version? How in depth? Do you just need to open a program, or do you need to interact with the registry? There are so many users that you can find materials for pretty much anything, but its hard to have the same ask of something like emacs.

Emacs has a long history of being ‘self-documenting’. To your point, that is not so helpful to someone brand new, but as you get used to it and learn more it becomes a wonderful feature. This is especially true for new or less commonly used packages, since they may have informative docs within emacs, but almost no help from google. It’s hard to have teaching materials for a program when the scope of what you can do and what someone wants to do are much larger than something like Microsoft Word (and when everything is open-source and no one is being paid to make teaching material, let alone simply more in-depth documentation, for it). Look at Roam Research! Discovering all the ways to use that app is still fairly difficult, and they are paid professionals :wink: Using internal documentation also means you are looking at the correct docs for your versions of everything. There has been more than once that I’ve tried looking up how to do something in Google Sheets or Word and only found tutorials that worked in 2013, but not with recent versions.

There is a bit of a self-reliance that I think some users try to instill in others by learning how to read the docs, also. Emacs is generally hard, and I don’t think anyone in 40+ years has managed to make it ‘easy’ to learn and use from scratch. Learning how to navigate the docs means you might be able to answer a question by yourself when there are no google results, or god forbid no internet.

Kits like Spacemacs and Doom try to address some of these problems by taking away the need for a user to understand how to put together sophisticated configs before using some of the most popular emacs packages with some of the most popular or smartest config settings. They also have their own problems of being relatively undocumented compared to full professional apps, except now someone needs help debugging an entire kit rather than just a package! People make youtube videos and blog posts, but again it’s just hard to document for beginners from all angles.

I know a lot of us want to make tutorial videos and much more robust docs for org-roam specifically, but it takes a lot of time, especially when the package is still being very actively developed. Keep in mind this is only like 4 months old :wink: