Using Org-mode for literate Emacs configuration with use-package

Using Org-mode for literate Emacs configuration with use-package

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 1172 bytes --]

Hello,

I am using Org-mode and the elisp function `(org-babel-load-file)` to
write my Emacs configuration into an Org-mode document. It's very
useful to document my configuration and I can quickly do exports to HTML
or PDF when a friend want to know more about my configuration.

But, I have a problem.

Sometimes, I need to split a package configuration into multiple
sections of my Org-mode document. For example Org-mode, because I set a
lot of settings. By spiting my config, I can correctly document each
option and organize it in a more comprehensible way.

But with the elisp function `(use-package)`, I need to join each package
configuration into the call of `(use-package)` function. Which prevent
me from splitting my config into Org-mode sections.

I was thinking of writing Org-mode source block with different parts of
my `(use-package)` call, so I can distribute it into different section of my
Org-mode document. But in this case, I can no-longer evaluate my
`(use-package)` call directly from my Org-mode document.


Do you have any suggestion ? How do you manage this problem ?


Best regards

-------
Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Using Org-mode for literate Emacs configuration with use-package

[John Kitchin]

This sounds like a use case for noweb. Check out
https://orgmode.org/manual/Noweb-Reference-Syntax.html

John

-----------------------------------
Professor John Kitchin (he/his)
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
https://kitchingroup.cheme.cmu.edu
https://pointbreezepubs.gumroad.com/ pycse bookstore


On Sat, Jul 13, 2024 at 8:45 AM Sébastien Gendre <seb@k-7.ch> wrote:

> Hello,
>
> I am using Org-mode and the elisp function `(org-babel-load-file)` to
> write my Emacs configuration into an Org-mode document. It's very
> useful to document my configuration and I can quickly do exports to HTML
> or PDF when a friend want to know more about my configuration.
>
> But, I have a problem.
>
> Sometimes, I need to split a package configuration into multiple
> sections of my Org-mode document. For example Org-mode, because I set a
> lot of settings. By spiting my config, I can correctly document each
> option and organize it in a more comprehensible way.
>
> But with the elisp function `(use-package)`, I need to join each package
> configuration into the call of `(use-package)` function. Which prevent
> me from splitting my config into Org-mode sections.
>
> I was thinking of writing Org-mode source block with different parts of
> my `(use-package)` call, so I can distribute it into different section of
> my
> Org-mode document. But in this case, I can no-longer evaluate my
> `(use-package)` call directly from my Org-mode document.
>
>
> Do you have any suggestion ? How do you manage this problem ?
>
>
> Best regards
>
> -------
> Gendre Sébastien
>

Re: Using Org-mode for literate Emacs configuration with use-package

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> Sometimes, I need to split a package configuration into multiple
> sections of my Org-mode document. For example Org-mode, because I set a
> lot of settings. By spiting my config, I can correctly document each
> option and organize it in a more comprehensible way.
>
> But with the elisp function `(use-package)`, I need to join each package
> configuration into the call of `(use-package)` function. Which prevent
> me from splitting my config into Org-mode sections.
>
> I was thinking of writing Org-mode source block with different parts of
> my `(use-package)` call, so I can distribute it into different section of my
> Org-mode document. But in this case, I can no-longer evaluate my
> `(use-package)` call directly from my Org-mode document.
>
> Do you have any suggestion ? How do you manage this problem ?

You can make use of noweb expansion:

* Org config

#+begin_src emacs-lisp :tangle yes :noweb yes
  (use-package org
    :config
    <<org-settings>>
    )
#+end_src

** Actual config
:PROPERTIES:
:header-args: :noweb-ref org-settings :tangle no
:END:
*** Agenda files
#+begin_src emacs-lisp
(setq org-agenda-files '("/path/to/agenda/files"))
#+end_src
*** Startup
#+begin_src emacs-lisp
  (setq org-startup-indented t)
#+end_src


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Using Org-mode for literate Emacs configuration with use-package

[Dominic Martinez]

On 7/9/24 3:39 PM, Sébastien Gendre wrote:
> I was thinking of writing Org-mode source block with different parts of
> my `(use-package)` call, so I can distribute it into different section of my
> Org-mode document. But in this case, I can no-longer evaluate my
> `(use-package)` call directly from my Org-mode document.
> 
> Do you have any suggestion ? How do you manage this problem ?

Yes, you can do this with noweb.

#+begin_src elisp :noweb-ref package-custom
(my-var1 "value")
(my-var2 "another-val")
#+end_src

#+begin_src elisp :noweb-ref package-custom
(even-more-vars "multiple-blocks")
#+end_src

#+begin_src elisp :noweb no-export :results none
(use-package my-package
   :custom
   <<package-custom>>)
#+end_src

Now use babel to evaluate the use-package source block (C-c C-c) and
noweb references will be inserted during evaluation.

Some explanation:
- The <<ref>> syntax inserts anything source blocks with the same
   :noweb-ref value.
- :noweb no-export says to insert noweb blocks on tangle or eval, but
   not on export (so your exports stay organized)
- :results none stops the evaluation output from being inserted into
   your Org file

Also see 16.11 Noweb Reference Syntax in the org manual.

Re: Using Org-mode for literate Emacs configuration with use-package

[Rens Oliemans]

[-- Attachment #1: Type: text/plain, Size: 523 bytes --]

Sébastien Gendre <seb@k-7.ch> writes:

> Sometimes, I need to split a package configuration into multiple
> sections of my Org-mode document. [...] By splitting my config, I
> can correctly document each option and organize it in a more
> comprehensible way.

If I understand your usecase correctly, you would find Org's Noweb useful (See "16.11 Noweb Reference Syntax" of the Org manual).
See the attached example file. Take note of the ':noweb yes' header argument, and the NAME of the referenced code block.


[-- Attachment #2: example.org --]
[-- Type: application/vnd.lotus-organizer, Size: 946 bytes --]

[-- Attachment #3: Type: text/plain, Size: 12 bytes --]


Best,
Rens

Re: Using Org-mode for literate Emacs configuration with use-package

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 1878 bytes --]


Thank you. It's a very nice feature.

I need to look how it work with tangle.


John Kitchin <jkitchin@andrew.cmu.edu> writes:

> This sounds like a use case for noweb. Check out 
> https://orgmode.org/manual/Noweb-Reference-Syntax.html
>
> John
>
> -----------------------------------
> Professor John Kitchin (he/his)
> Doherty Hall A207F
> Department of Chemical Engineering
> Carnegie Mellon University
> Pittsburgh, PA 15213
> 412-268-7803
> https://kitchingroup.cheme.cmu.edu
> https://pointbreezepubs.gumroad.com/ pycse bookstore
>
> On Sat, Jul 13, 2024 at 8:45 AM Sébastien Gendre <seb@k-7.ch> wrote:
>
>  Hello,
>
>  I am using Org-mode and the elisp function `(org-babel-load-file)` to
>  write my Emacs configuration into an Org-mode document. It's very
>  useful to document my configuration and I can quickly do exports to HTML
>  or PDF when a friend want to know more about my configuration.
>
>  But, I have a problem.
>
>  Sometimes, I need to split a package configuration into multiple
>  sections of my Org-mode document. For example Org-mode, because I set a
>  lot of settings. By spiting my config, I can correctly document each
>  option and organize it in a more comprehensible way.
>
>  But with the elisp function `(use-package)`, I need to join each package
>  configuration into the call of `(use-package)` function. Which prevent
>  me from splitting my config into Org-mode sections.
>
>  I was thinking of writing Org-mode source block with different parts of
>  my `(use-package)` call, so I can distribute it into different section of my
>  Org-mode document. But in this case, I can no-longer evaluate my
>  `(use-package)` call directly from my Org-mode document.
>
>  Do you have any suggestion ? How do you manage this problem ?
>
>  Best regards
>
>  -------
>  Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Using Org-mode for literate Emacs configuration with use-package

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 1686 bytes --]


Thank you very much.

So, you can make a reference to a block of code who is defined below ?

It's a very nice feature. Org-mode is very amazing. :D Even after many
years of daily use, people still make me discover new features.



Ihor Radchenko <yantar92@posteo.net> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> Sometimes, I need to split a package configuration into multiple
>> sections of my Org-mode document. For example Org-mode, because I set a
>> lot of settings. By spiting my config, I can correctly document each
>> option and organize it in a more comprehensible way.
>>
>> But with the elisp function `(use-package)`, I need to join each package
>> configuration into the call of `(use-package)` function. Which prevent
>> me from splitting my config into Org-mode sections.
>>
>> I was thinking of writing Org-mode source block with different parts of
>> my `(use-package)` call, so I can distribute it into different section of my
>> Org-mode document. But in this case, I can no-longer evaluate my
>> `(use-package)` call directly from my Org-mode document.
>>
>> Do you have any suggestion ? How do you manage this problem ?
>
> You can make use of noweb expansion:
>
> * Org config
>
> #+begin_src emacs-lisp :tangle yes :noweb yes
>   (use-package org
>     :config
>     <<org-settings>>
>     )
> #+end_src
>
> ** Actual config
> :PROPERTIES:
> :header-args: :noweb-ref org-settings :tangle no
> :END:
> *** Agenda files
> #+begin_src emacs-lisp
> (setq org-agenda-files '("/path/to/agenda/files"))
> #+end_src
> *** Startup
> #+begin_src emacs-lisp
>   (setq org-startup-indented t)
> #+end_src

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Using Org-mode for literate Emacs configuration with use-package

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 1457 bytes --]

Thank you very much for you suggestion.

It's a very nice feature. I will read the manual.


Dominic Martinez <dom@dominicm.dev> writes:

> On 7/9/24 3:39 PM, Sébastien Gendre wrote:
>> I was thinking of writing Org-mode source block with different parts of
>> my `(use-package)` call, so I can distribute it into different section of my
>> Org-mode document. But in this case, I can no-longer evaluate my
>> `(use-package)` call directly from my Org-mode document.
>> Do you have any suggestion ? How do you manage this problem ?
>
> Yes, you can do this with noweb.
>
> #+begin_src elisp :noweb-ref package-custom
> (my-var1 "value")
> (my-var2 "another-val")
> #+end_src
>
> #+begin_src elisp :noweb-ref package-custom
> (even-more-vars "multiple-blocks")
> #+end_src
>
> #+begin_src elisp :noweb no-export :results none
> (use-package my-package
>   :custom
>   <<package-custom>>)
> #+end_src
>
> Now use babel to evaluate the use-package source block (C-c C-c) and
> noweb references will be inserted during evaluation.
>
> Some explanation:
> - The <<ref>> syntax inserts anything source blocks with the same
>   :noweb-ref value.
> - :noweb no-export says to insert noweb blocks on tangle or eval, but
>   not on export (so your exports stay organized)
> - :results none stops the evaluation output from being inserted into
>   your Org file
>
> Also see 16.11 Noweb Reference Syntax in the org manual.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Using Org-mode for literate Emacs configuration with use-package

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 697 bytes --]

Thank you very very much.



Rens Oliemans <hallo@rensoliemans.nl> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> Sometimes, I need to split a package configuration into multiple
>> sections of my Org-mode document. [...] By splitting my config, I
>> can correctly document each option and organize it in a more
>> comprehensible way.
>
> If I understand your usecase correctly, you would find Org's Noweb useful (See "16.11 Noweb Reference Syntax" of the Org manual).
> See the attached example file. Take note of the ':noweb yes' header argument, and the NAME of the referenced code block.
>
> [2. application/vnd.lotus-organizer; example.org]...
>
>
> Best,
> Rens

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Using Org-mode for literate Emacs configuration with use-package

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> So, you can make a reference to a block of code who is defined below ?

Yup.

       You may also include the contents of multiple blocks sharing a common
    ‘noweb-ref’ header argument, which can be set at the file, subtree, or
    code block level
    
  16.11 Noweb Reference Syntax (Org manual)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Using Org-mode for literate Emacs configuration with use-package

[Björn Bidar]

Are you shure that you configure really only one package each time you
have to split the config up in multiple sections?

Usually the package is split up in multiple subpackages. For example
Org-mode consists of org, org-babel, org-agenda and so on.

If there are no subpackages using one section per package is usually
enough.

Re: Using Org-mode for literate Emacs configuration with use-package

[Dilip via General discussions about Org-mode.]

Hi,

I also enjoy using literate org config.

I cannot think of a way to split config in org src blocks and evaluate it
easily.
Each src block needs to evaluated, although most of the time while
editing itself I do evaluate or =eval-buffer=.

There is one way I can think of, that is to use =noweb= inside one
block. That might add little noise if you do many splits, but it works.
You can do =org-babel-expand-src-block= to get the output.

Or you may just use many use-package src block for that package.

With =:custom= keyword in use-package, you can add some doc for that
variable.

  Eg: (use-package org :custom
                       (org-ellipsis ".." "Some doc"))

I'm interested in knowing others opinion, and how they use it.

I use both emacs and nixos config in org-mode.
https://github.com/idlip/d-nix/blob/gol-d/d-setup.org

Other resource that uses a method that lets you use single noweb
reference to tangle all src block name.
Eg: You can use just <<org-conf>> and have any number of src block with
same #+name:org-conf name
https://github.com/rasendubi/dotfiles

Best,
Dilip