search

Kungsgeten / org-brain

Org-mode wiki + concept-mapping
MIT License
1.72k stars 103 forks source link

Org-brain API documentation? How do the org-brain functions are called from elisp? What to know before messing with the metadata? #164

Open techapu opened 5 years ago

techapu commented 5 years ago

In the Issue #161 we have been talking about the org-brain "API", and the need to document the use of the org-brain functions from elisp with the needed arguments, parameters, etc. I want to work with you in what you need related to the more complex linking workflow possible.

All about the issue #163 is a good example of a coding, reference and documentation need for me. How do I handle an entry ID of an org-brain entry from elisp? Or is there any? How can I read the metadata of the org-brain entry? When we were trying the initial code of helm-brain a bug broke an important entry and I couldn't repair it, not even with the correct heading format, the properties in their place, the friends and parents links all in the correct format,. And I don't know how to debug the metadata of the heading, because it's clear for me that the data I can see, have a correlated "org-brain" data id map in some other place but I don't know where to inform me about how to handle it, or reset that data from the real heading and relationships.
Naturally I've tried to update the brain id locations, and refresh, but it doesn't repair this entry.

Kungsgeten commented 5 years ago

Well, all of the functions and variables in org-brain have a docstring, so you could read the "documentation" in the org-brain.el file, or from Emacs itself. The documentation could probably be updated and more clear though, and it may be hard to understand the point of some functions.

A "hacking guide" could be nice, if people want to understand the insides and get a kickstart.

techapu commented 5 years ago

Thanks for the feedback on this! I've read the code, in a superficial way, before asking, but some essential functions are so briefly documented that I couldn't figure out the inner mechanics of the org-brain entries identification and how to pass arguments and parameters to the actual functions. Or how the data is structured and stored. I only understood the pinned entries storage. Maybe I missed something, but the main functions are all meant to be called with the "current entry" in mind, and not with any entry or reference that the user wants to give as data (naturally with the correct syntax). So it's not extensible, and it is a package ideal for extensibility.

Kungsgeten commented 5 years ago

I've added arguments to some of the interactive elisp functions. What they do can be accomplished by other functions in org-brain when run from elisp, but I guess its nice to be able to use these more concise functions (like org-brain-add-child instead of org-brain-add-relationship).

shlevy commented 4 years ago

A "hacking guide" could be nice, if people want to understand the insides and get a kickstart.

This would be great! I'm digging into the source code now but having a good high level overview if I want to programmatically explore/manipulate my brain would be awesome.