Support #+INCLUDE and other hash keys

[spacekookie]

Hey there!

I'm very happy to see someone work on a stand-alone org implementation. I've wanted to be able to generate org-mode to HTML in CI for ages, but running emacs in CI can be a real pain.

Unfortunately this project doesn't seem to handle #+INCLUDE: directives yet (I'm not very well versed in what exactly this is called in org... I had a look at the code but couldn't really figure out an obvious place to add it.

Did you already have plans on adding this? If not, could you give me some pointers as to where you'd add this feature? I found the parser code kinda hard to navigate (I'm mostly used to nom parsers...)

Cheers!

[hydrobeam]

Hi! #+include: falls under the scope of a keyword (which is pretty much "#+ANYTHING:") there are some types of keywords that are explicitly defined by the spec so I handle them in the parser itself (in crates/org-parser/src/element/keyword.rs), like affiliated keywords.

the spec considers #+include: to probably be an "export" thing, so it doesn't address it. What I'd probably do is:

• when handling a keyword (key, value pair) in the exporter, check if the key is include, read a file, then parse + export it if it's org.
• this would end up parsing the #include'd file in a separate context (which isn't how emacs org-mode would do it, they do a separate pass, see org-export-expand-include-keyword in ox.el )

doing an initial pass and expanding the things that need to be expanded (like macros too) would be more inline with official org-mode so I'll probably look into doing that eventually. For now it'd be pretty straightforward to handle the basic include logic as defined here: https://orgmode.org/manual/Include-Files.html

I'd be happy to implement this and then look into the separate-pass approach to first expand include's, parse, then export. Maybe an optional on-by-default config option to handle includes that can be disabled if someone really doesn't want to pay the (probably small) cost of an extra pass 🤷

here's the comment in ox.el where they explain include handling, for posterity:

Expand

;; File inclusion is taken care of by
;; `org-export-expand-include-keyword' and
;; `org-export--prepare-file-contents'.  Structure wise, including
;; a whole Org file in a buffer often makes little sense.  For
;; example, if the file contains a headline and the include keyword
;; was within an item, the item should contain the headline.  That's
;; why file inclusion should be done before any structure can be
;; associated to the file, that is before parsing.

[spacekookie]

Thanks for the quick reply! That sounds good! And I'd appreciate if you could implement this, it'll probably go faster than me trying to figure out the code. And quite frankly, I'm deep enough in "recursive project tangents" that I don't need another one 😅

Let me know if you have anything that I can help testing with

[hydrobeam]

i've added support for #include in 4de31c. it should support most of the params used in the org manual, except for :minlevel and :only-contents (let me know if these are important for you 🫣)

I ran some basic tests and it seems to work as expected, but if you encounter any bugs then keep me posted. I'll keep this issue open until I get around to :minlevel and :only-contents.