I like using org-mode in my packages' Readme files, but I also like writing instructions under the ;;; Commentary: header that goes in the source file.

Whenever I change some part of the documentation, the best way I've found to keep those in sync is to:

  1. Edit the org file first.
  2. Export to a plain text utf-8 buffer, with the body-only option (C-c e C-b t U).
  3. Add ;; at the start of each line.
  4. Copy that over to the package file.

Q: How can I best automate this?

I can write the necessary elisp for adding ;; and copying to the kill-ring, but I'm not familiar enough with the org-export machinery to know what's The Right Way to do an automated export using a specific recipe.

Bonus points if there's a command I can invoke from a .el file which automatically finds a Readme.org, does the whole export, and uses it to replace the file's ;;; Commentary:.

  • el2markdown <- Related as it syncs the readme's from .el Commentaries, but in markdown format. May be then run a batch job to convert to org? Or use that as a basis to write an "el2org" package? :) – Kaushal Modi Oct 15 '15 at 16:45
  • poporg <- Also related. Use poporg to edit comments in any major-mode in an org-mode buffer. The only extra step would be to save that "popped out org buffer" as an org readme file. – Kaushal Modi Oct 15 '15 at 16:48
  • @kaushalmodi Thanks. I'll have a look at these. Specially poporg. – Malabarba Oct 16 '15 at 22:26
  • poporg is priceless.. I must be probably using it once everyday to do stuff like this without leaving the .el files. – Kaushal Modi Oct 16 '15 at 22:29
  • @Malabarba - Would it be useful to use the literate programming features, i.e. noweb & tangle, of org-mode to keep .el and Readme.org in sync? – Melioratus Jan 4 '17 at 22:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.