future of org-brain: headline entries vs file entries

[knyfe]

I've been hesitating to put a lot of effort into developing my brain(s) as I can't decide whether to create a structure restricted to headline entries and ignore file entries entirely or to freely combine the two. On the one hand, "most of org-mode is tailored towards working with headlines, and because of this org-brain has some limitations regarding what’s possible with file entries." This would suggest a brain restricted to headline entries is a prudent path to take. On the other hand, @Whil notes (#187) that org-mode may soon implement a property drawer for file-level properties, which (as I understand it) would help ameliorate the functional limitations of file-level entries and possibly lead to a restructuring of org-brain code. Is there any way of knowing at this point whether org-brain is more likely to move toward an emphasis on headline or file entries? How might I best future-proof/optimize my current brains for the changes to come?

[Kungsgeten]

Hi! I think it depends on what works best for you personally. I think though that only using headline entries make org-brain work better with other packages, and that its a bit more stable. So if you don't have a preference, then go for headlines only. You can set use (setq org-brain-include-file-entries nil).

[benjaminwd]

If I'm not mistaken, you can still use headline entries in multiple files without issue, the only question is using files themselves as entries in the brain.

[Kungsgeten]

If I'm not mistaken, you can still use headline entries in multiple files without issue, the only question is using files themselves as entries in the brain.

Absolutely, I think the most common case is to use both. However many think its confusing to have both, which I understand.

[Whil-]

Hi!

Regarding the document level property drawer; that's unfortunately not going to be included in org 9.3. I tried but voices in the Org mode community said no. The version after that should include it though. The functionality exist in a separate branch called 'next' in the Org mode repository for now. (Please chime in on the mailing list if you support this feature.. :) )

To the topic at hand then (sorry for the digression above...); After having worked with the document level property drawer for some time on my personal computers I think the most natural thing for the future of this headline vs file discussion is to 100% consolidate functionality around the ID-attribute. That will work for files when you can assign an ID in the document property drawer! (Well... I suppose some code changes in org brain will be needed to support that as well ofc...) Conceptually that would make very much sense to me. A org-brain node would have a single definition across both "types" of entries.

So to future-proof I think what Kungsgeten suggest sounds good! 👍 Personally I still use both entry-types though, and if I get the time for it I might look into adding support for the document level property drawer for a future-proofed (ID-based) version of file entries as well...!

[Kungsgeten]

@Whil- Great news that it is planned to be inclulded in org-mode 9.4! When that is released I'll try to rewrite the org-brain code base to make use of this.

[knyfe]

I agree that the file-level ID-attribute in org makes a lot of sense. As far as I can tell, linking to files in org requires retaining a strict linear hierarchy of files/directories, which I too often end up breaking. The ability to move files around at will and still retain link integrity (as with headline IDs) would be great! For my org-brain use, I find it more natural and aesthetically pleasing to use both file and headline entries, as I often like to have the document title as the main subject of the document with headlines as outline points beneath, rather than having to use a top level headline as the title/subject of the document.

So I wonder: if I continue to build out my brain using both file and headline entries, do you suppose there will be a relatively easy means of adding document level IDs (once the feature arrives in org) and migrating my existing brain from the current file level scheme to the new one based on ID-attributes for both file and headline entries?

[Whil-]

Just a small update on document level property drawer - The feature now exist in Org mode master. So if interest strikes, the curious could take a look and try it out. Haven't found any time to look at integrating that into Org brain though.

[MarioRicalde]

@Kungsgeten just to make sure you notice the message above from @Whil- ;)

[Kungsgeten]

@MarioRicalde @Whil- I tried finding information about this new feature, but I couldn't find it in the changelog (I checked 9.3.1). From what I understand it will not be available until 9.4. I probably won't look into it until its available in org-plus-contrib in the Org ELPA.

[Whil-]

I've tried to push this forward but the response back from the maintainers is 9.4. The code is available in Org mode master and the news can be found here: https://code.orgmode.org/bzg/org-mode/src/master/etc/ORG-NEWS

Documentation is updated as well: https://code.orgmode.org/bzg/org-mode/src/master/doc/org-manual.org

And the main commit for all this is here: https://code.orgmode.org/bzg/org-mode/commit/1bdff9f73dc1e7ff625a90e3e61350bdea99f29c

Just for the curious! But 9.4 is probably when it's going to get into ELPA... So what we can do is push for 9.4 to be released... Probably will be tough to push for it only for this feature though.

But I think the benefit for looking into it for Org brain file entries is quite bit as it could (hopefully) mean that functionality between headline and file entries can be merged.

Regards Gustav

[MarioRicalde]

I've spent a couple of nights playing around with org-brain and creating some experimental brains to test the features and get a feel for the existing UX. And org-brain has several problems that make the UX not great.

A lot of this is centered around these to types. I understand and I see benefit in having the two types, files and titles are useful, but they're useful in different situations, and a major problem is that, there's no pointers as to how to work with the current implementation.

I would also argue there's a 'third' type, which is nesting files into directories when creating children.

So in one of my test brains I have these three types all mixed, and once I have my brain setup I can't tell which one is what with org-brain-visualize, so I don't know what I can move easily at a glance.

I solved this by coming up with my own little org-brain naming convention, which is UGLY. But worked as a way to test my problematic:

I have three types of entries:

1. Simple 1 file entries. They're usually used as connections or category nodes. They're always at the root of the brain, and start with lowercase.
2. Title entries, which are always in a Simple 1 file entry file. Useful for scaffolding, and drafting brain nodes before splitting it into more permanent structures. The titles are always surrounded by == to make it obvious they're title headers.
3. Directory file entries. These are for bigger subjects. Org-brain has a major issue with name spacing currently, and it just makes sense to me to group bigger subjects into directories. They're always capitalized on the first letter. For example, python and ruby have their directory, so you could have Python/Variable.org and Ruby/Variable.org.

For index files ( first file that creates the directory ), I repeat the name. So Python/Python not beautiful, but it works for me for the most part.

This process works well for the most part and solves some of the name spacing issues I have with org-brain. Now the question is, what do you think of the above @Kungsgeten is that how you imagined your software being used? Is there something we can improve to make this UX simpler?

[Kungsgeten]

@MarioRicalde I didn't have a specific workflow in mind. The main intention was to create something similar to The Brain in Emacs, and to do so while at the same time take advantage of the powerful org-mode. I myself haven't had problems with the types you describe (though I agree that Python/Python is a bit ugly).

If you have a look at Customizing the look of entry titles in the README it should be possible to add visual indications about the types you describe. It requires some elisp code though, and you probably need to have a basic understanding of the org-brain codebase. org-brain is pretty flexible, which is both good and bad. I think every user probably has their own workflow that makes sense for them.

A thing you do not mention is that it is possible to have several different brains, using org-brain-switch-brain.

[knyfe]

For what it's worth, I've decided to go with headline entries only. Aesthetically I find the file entries model more pleasing--with the file itself as the top node of the file outline, a file title indicating the overall topic, and any headlines representing subsections. But I tend to change brain relationships and move entries between files frequently. The headlines-only approach seems to make that easier, as the ID of each entry is not dependent on the file or the directory structure.

[michaelsjackson]

Of course I want to link files in relation to each other as well, plus your files can be kept smaller, around a certain topic, for lecture scenarios, create a pdf, give to students. But still having all the other topics around it, in the brain at least, as separate files.

[dustinlacewell]

I want to put my two cents in here.

I essentially agree with @knyfe that the most natural org-brain model (for me!) is to just use file-entries. Each entry is a file, and it's content is the whole file. I want all the file content to show up in org-brain-visualize as the entry's text.

However, I do not have their problem with reorganization as I find it mostly a workflow of moving headings to files, and very rarely the reverse. I do not think moving headlines to files is much overhead at all -- and so I remain wanting better support for a file-only workflow.

Currently, only the text to the first headline of a file is considered as context/text of the file entry. This hides most of the information inside of a file entry from the org-brain-visualize view dramatically crippling UX for me.

Is there a way to make org-brain completely ignore headings as entries and to show the full content of a file-entry as the text in org-brain-visualize?

I have to say, I also love the idea of storing children in folders with the same name as the parent (minus the .org extension of course).

[tumashu]

org-roam v2 seem to use "the document level property drawer" .