3 ms·

I've always seen this as an anti-pattern. You can make the documentation in an .el file as rich as you want without losing all the niceties that Emacs offers fo

I've always seen this as an anti-pattern. You can make the documentation in an .el file as rich as you want without losing all the niceties that Emacs offers for interactively working with source code (e.g. find-{function,variable} will jump to the ephemeral dynamically generated .el file, not the actual origin of the code which is in the .org file). Why settle for an extra layer of indirection that makes interactively working with source code more time consuming?

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.
goku12 3y ago
> Why settle for an extra layer of indirection that makes interactively working with source code more time consuming? I understand what you mean. But it never seemed to be a problem for me. Anyway, the real reason why I ended up with org-mode is that I heavily customize Emacs. The only way to be able to handle that much configuration was to split it up into a dozen or so elisp files. Org-mode's biggest advantage (for me) is that it can manage complexity very well. The org-mode configuration file is neatly divided into topics along with their documentation. The topics are also folded up - so it's very easy to find certain configuration segment.

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.

goku12 3y ago

> Why settle for an extra layer of indirection that makes interactively working with source code more time consuming? I understand what you mean. But it never seemed to be a problem for me. Anyway, the real reason why I ended up with org-mode is that I heavily customize Emacs. The only way to be able to handle that much configuration was to split it up into a dozen or so elisp files. Org-mode's biggest advantage (for me) is that it can manage complexity very well. The org-mode configuration file is neatly divided into topics along with their documentation. The topics are also folded up - so it's very easy to find certain configuration segment.