Understanding file refs?

[Eccentric-J]

I’ve dived right into Zettelkatsen and simultaneously trying out a couple of tools. I’m having a bit of trouble grasping how file refs work. Based on the docs https://www.orgroam.com/manual/File-Refs.html#File-Refs it seems the expected flow is to create small, general notes that use the #+roam_key pointing to a single source. Then I can link to it from any number of Notes.

Is that how it is intended? Is that how people use it?

For instance let’s say I wanted to document this as part of learning org-roam. Say I already have a few notes about org-roam’s features, so I create a Understanding File Refs Issue note like this:

#+TITLE: Understanding file refs
#+ROAM_KEY: https://github.com/org-roam/org-roam/issues/1134
#+TAGS: "Org-Roam", "Docs", "Github Issue"', "Zettelkatsen"

I created an issue asking about how we should use file refs.

Then I create another note maybe file refs docs

#+TITLE: File refs in org-roam docs
#+ROAM_KEY: https://www.orgroam.com/manual/File-Refs.html#File-Refs
#+TAGS: "Org-Roam", "Docs", "Zettelkatsen"

Official documentation describing how file refs work.

Then I can freely link back to those references in my notes.

#+TITLE: File refs in Org-Roam
#+TAGS: "Org-Roam", "File-Refs", "Usage", "Learning", "Zettelkatsen"

* What are they?
   According to [[20200924122300-file_refs_in_org_roam_docs][the docs]] a =roam_key= argument must be unique and a note can only refer to one ref.
** How should they be used?
   I'm not entirely sure how they should be used. Created [[20200924123200-understanding_file_refs][Understanding File Refs]] to learn about the intended workflow around them.

   - If each note can only have one reference then it sounds like we want to create general reference notes that use `#+ROAM_KEY` then link to those in as many notes as desired.
   - Even pages like this may refer to multiple sources but we know a note can only have one roam_key per file.
   - Am I missing a type of link or a constraint to this?

Is that even close to the intended use case?

(Moving to here from https://github.com/org-roam/org-roam/issues/1134 as this feels more appropriate)

[nobiot]

Hi @Eccentric-J,

Allow me to describe my understanding of the original intended purposes; I will let others and project members to correct me or add to my description.

I use the backlinks with [[file:path/to/file][description]] in the same way you use. Using “file-refs” with the #+roam_key: property is an additional way of establishing backlinks.

There are two ways to use #+roam_key:. One is as you intend to use it: for a website. Perhaps an article or blog you find useful for you; you quickly capture the URL, and make a note to summarise its content (your first example with “Understanding file refs”).

Then later, you may have additional notes that refer to the same website. These additional notes should appear in “Ref Backlink” of the original note with #+roam_key.

Illustrating with a screen shot below, Area 1 is the original note for http://duckduckgo.com summarizing what it does (my sample has no summary… I appreciate the power of your imagination).

[EDIT: there was a mention of a bug, which has been fixed. The screen shot below has been updated to reflect the fix]

Area 2 shows an additional note referring to the note in Area 1.

Area 3 is the backlink for the original note. As you can see the backlink appears in the “Ref Backlink” section.

This is one of the two usages.

The other usage is more for academic writing. You may take notes for a book or journal article, and keep bibliographic information in a reference manager (such as Zotero, etc.) – like the screen shot below.

Left: PDF document shown in PDF-Tools in Emacs. Right: Notes via Org-noter in Org Mode.

This is equivalent to the “original note” for a website in the example above. #+roam_key: is used as the ID of this note with using the cite:cite-key syntax of Org-ref (sync’ed with your reference manager).

Later you can refer to this note by using cite:cite-key, like the screen shot below – it shows the original note on the left, and its backlink on the right. You can see that #+ROAM_KEY: holds the ID “cite:Ostrom2019” (defined in my reference manager), and it is used to cite the paper in my other note (shown as a backlink).

This is my understanding of the two “standard” usages of “File-ref” with the #+roam_key property. Hope this helps. Correction, comments are welcome.

[Eccentric-J]

Thanks, that really helps a lot! That’s far more automated\practical than how it originally appeared to me.

[jethro]

absolutely the kind of guide that should be more visible (in the manual, or somewhere else)!

[nobiot]

haha. Thanks. If this is useful, I will be happy to somehow contribute to the manual, or start a series of “standard / vanilla” usage of main Org-roam functions here in the Discourse forum (a la Zero to Org-roam), or perhaps both…

[Eccentric-J]

Please consider doing that! The manual is helpful but some improvements could be made for beginners such as myself. I’ve tried finding a basic run through on YouTube as well as articles but it’s difficult to find anything on vanilla usage of org-roam without it being about a lot of other plugins and their personal customized configs for it.

[nobiot]

There you go. Still uncooked. Feedback welcome.
It might be better if I tried to help with the official manual… Let me hear what you think / feel.

Unofficial user guide to Org-roam (idea / outline only at this stage)

title: Unofficial user guide to Org-roam Preambles Org-roam is designed around the Zettelkasten method of organizing thoughts. We’ve all experienced frustration sitting before a blank page forcing ourselves to come up with an outline or a first draft. By contrast, Zettelkasten provides a more organic flow. Collect your thoughts as they come as small, separate ideas then review them at a later time. Upon review, you begin to tinker by linking notes together to create new, meaningful connections …

[roerick]

I just found this through your account and this was very helpful for me!

This is how I’m using reflinks:
I’m not sure if I’m doing it correctly, but it seems to work okay and I was kind of shocked how simple it was. I’ve created a custom style of “bible:” link which gets generated through a function

When a “bible:” link is followed using a given Major Mode, it opens up the appropriate chapter file. If the chapter file does not exist, it creates the file, gives it an ID, and gives it a ROAM_REFS parameter which allows reflinks to work. Then, anything which references that chapter shows up in the reflinks page!