7 ms·
Matter of preference. As an example, I may have a lot of configuration related to package X under one Org node. I merely have to "comment" the node headline to
by BeetleB 3y ago
Matter of preference. As an example, I may have a lot of configuration related to package X under one Org node. I merely have to "comment" the node headline to ensure none of that code gets to the config.
Your comment reveals your bias - that the code is more important than the commentary. The counterpoint is:
No. You can't make the documentation as rich as you want. I want inline images. Can I put those in an .el file? Links. Tables. Bold, italics, etc. For many, this is more important than the code in the config.
- goku12 3y ago> I want inline images. Can I put those in an .el file? Links. Tables. Bold, italics, etc. For many, this is more important than the code in the config. Thanks for adding this. Literate programming with org-mode is indeed one of my favorite from Emacs.
- pxc 3y ago> Your comment reveals your bias - that the code is more important than the commentary Yep! That's the key, imo. I love using Org mode wherever I feel that documentation is primary. So right now, most of my code that lives in Org files at work is shell snippets I've used for managing and configuring software. The literate approach is all I need there: I'm keeping track of what configuration I've done, not writing a giant, complicated program. Then I get the added benefit: the Org files form a wiki that I can use to refer colleagues to whether they use or care for Emacs or not! Similarly, tangling shell snippets into scripts lets you write tests for your documentation! The examples become scripts and then the scripts can be run and verified in CI.