I'm creating a simple bash tool that uses various flags/arguments from the user, and I'm using an org file for the documentation. I have several examples and I'd like to include some explanation of each. Instead of copying the code from each example into the file, I'd like to create a link to the file and display the contents in the org file. Something like

This example does such and such...

my-tool -f "user-input" # these are the contents of ex-file-1.sh

While this example does this and that...

my-tool -r "user-input # these are the contents of ex-file-2.sh

This way, I don't have to modify the README.org if I modify the individual example files. I'd also like to do the same thing with the contents of the tool's help (which is activated with the -h flag). Basically I want modifying the documentation to be less tedious.

I know that images can be embedded into org files (and are even visible within the file before exporting), so I would assume the same is possible with text? What do I need to use for this? Or I am I just being too lazy with my documentation?

  • 2
    Maybe you are looking for the include keyword.
    – Juancho
    Commented Mar 29, 2017 at 15:39
  • 1
    ... and maybe export README.org to a (different) org file: that should pick up the inclusions explicitly.
    – NickD
    Commented Mar 29, 2017 at 15:45
  • @Nick @Juancho Yep. Good call guys. I'm now calling this file README so when using org-org-export-to-org it automatically creates README.org. When I type C-c C-e I don't see an option to export to org, so I just put a comment at the bottom of the document with (org-org-export-to-org) and run this when I want to generate the org-file.
    – haff
    Commented Mar 29, 2017 at 16:24
  • 1
    I thought org is always available as an export option, but I guess you need to customize org-export-backends to get it in the menu.
    – NickD
    Commented Mar 29, 2017 at 16:30
  • I'm using Spacemacs, so who knows.. Also, feel free to type up an answer, and I'll mark it as correct (I can edit your answer as needed to provide more details.. for noobs.. like me)
    – haff
    Commented Mar 29, 2017 at 23:46


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Browse other questions tagged or ask your own question.