#+ TITLE Org mode emacs startup

Introduction

OK I caught the bug to create an org mode file to document my init files.

The reason is not for the pretty files that you see on the web or github but that I was writing a few comments and realised that org mode looks nicer for those (no comment marker ; on lines) and you can deal in text mode for documentation.

I would note that my programming style is to have lots of small functions. With org-mode I can execute code from a block and not from a tangle. Unfortunately for init files use-package wants you to pout all code into one lisp form so making comments away from code, so you have an incentive to use weaving - but then the top level code is not executable you have to tangle first.

Structure of startup files

init.org

Generates init.el and early-init.el (if emacs > 26). These .el files need to be in source code control as they need to run the startup. They include a minimal tangle method, this does not allow weaving or other controls. This minimal method is used on config.org (init.org currently could use this as well). This was needed as emacs’s provided org-mode had issues, from emacs 29 I think these have gone so could replace all by org-mode.

However I messed up config.org now uses tangle properties in the heading so the nullman export does not work 100%. The generated code doesseen=m to work but it does not have all the features Also I note nullman has now commented out his code and it had an error. So choice is as org-mode in emacs is new enough the use this. or delete the package section in config so all works again,

init.org contains the minimal amout to load other things so in essence should not need to be edited.

There is now an alternate - which is a way to try other init setups. However I found it easier to keep an emacs open and mv the emacs startup directories.

config.org nor init/all-in-one.org

Basically loads org-mode using packaging etc. Note uses the minimal tangle so no weaving etc. The last thing it does is load init/org.all

The only reason to do this rather than init.org is that you don’t need to save the .el as well. But config.org has 156 commits and init.org has 31. Also the separate allows easy choice of alt-init.

Org-mode is complex so needs a separate file to start it - actually two one for tangling etc from Grant Rekke other is all the variables. Then keys as I need mac-key-mode before the other minor modes. (I now have changed this so its key bindings are now in the global map and so could be moved). The all.org which is under full org weaving.

init

This directory includes all the files that can have the full detangle i.e. including weaving.

The files directly in init are explicitly loaded. Subdirectories are loaded by iterating over all the files in them, they contain files where the order of loading does not matter - well strictly done by length of file so can add some dependency.

init/all.org

Ideally this should just controls the order of loading things but originally did various things inline.

behaviour

This controls how emacs works. Sets up the environment for how other things work.

They are all minor modes grouped by some commonality and are loaded from init/behaviours

modes

Originally programming modes but these are all the major modes. The load order dies not need to be determined.

keys

Well this can be the last - basically sets up my key bindings. Unfortunately due to the order of keymaps I think in org-mode and mouse the keys have to be set first. The one odd case is dealing with Aquamacs/macOS differences which have to be done upfront.

Use of org mode

Tangling

After experience and a problem with org mode with Aquamacs having issues the setup is.

Original commentary

init.el checks config.org and all its sub org and if needed generate a new config.el, then loads the config.el. Possibly try to do without org mode as you won’t have the up to date one without running the init and loading a package. org seems to make changing breaks. The best would be similar to nullman’s init files where init is in the same config file as the rest but generated by itself. I have the latter but must use org mode as I also use noweb. I would have started with his file but the org mode view is not available (not certain what I mean there). So I can’t create the correct header yet.

Re tangling I am happy to end with just org files and generate elisp on the fly as I use GUIs and start emacs and leave it running - even if I use docker that would be via tramp so still the main emacs.

Commentary on process after a few months

Tangling

Well I put it all under an org file to generate but I thought about changing back to plain elisp - well with comments.

The issues ere

1. automatic generation of .el files can go wrong when you have bad code and a) it is difficult to spot b) org mode versions change the file ids so can differ.
2. If in emacs lisp there are tools for searching etc. Most of the time as this is just a config this does not matter but on complex setups (e.g. ironically, org-mode you have to write mal-formed code
3. init.el still needs to be generated.

But org mode is nice as much more readable then commented elisp. ie variable face font and wrapping to screen.

So this file will have odd random comments taken from the code.

So are you reading or debugging? Doing a course in ml would be better in org-mode

Alternative is can you edit the source buffers - means no weave but can have bad source in the org file but good in the elisp. So try that first and I think an org mode bug - need to set name and not :noweb-ref perhaps latter only works if not light. So use this correctly and stick with org mode. But to work each code block needs a separate name or at least they must be in the file next to each other - which blows up my put all hooks on one ref and all config on another and then group by topic.

Issue I think is how much do you need the IDE features.

Nullman expansion

This does not use org-mode but does not allow weaving - and just found out tangling to separate files. So need an init.org and a config.org

Others

For resilience over org version issues put as much after org as possible (makes case for using non org mode expand until org mode loaded) The important bits are init - the loader, packaging and org mode itself. The rest goes to all.org

Seems that really each tangled bit should be in a separate file that if fails can be ignored. and my init load function does the catch so this is why some bits only failed.

So use smaller files.and only call from upper level ie org-base calling org-all is bad but that is a special case, as that has to work - all othe code tends to be independant or at least the editor runs.

Debugging and weaving

Basically if you write code and can run a test and all is OK then weaving etc is good.

However if you need to debug or search in code semantically then weaving is an issue.

Also it helps to have each src block be valid code. So I would now note use use-package keywords for large code but rather weave.

Detangle

Detangle works if simple but if you start using weaving then jumping back to code does not seem to work org-babel-tangle-jump-to-org does not find - see org-all.org 19/1/2020 Debugging this is nasty as the code uses regexes

Code jumping

The code tools work on the tangled files

Include

I want separate files - so when fiddling a mode then I can see it git history easily what changed.

Methods seem to be

1. use org-mode’s include - which they have not done for babel.
2. else as Emacs starter kit. Which has a special elisp load of then org file. But this does not save .el to disk so issue with debugging
3. Just require the el file - you tangle the org file first. - but need to make them all save

There are also loaders that optionally load - but as I just have one machine just load all. With experience messing stuff up.

You need the .el to edit if crashed.

Hack

• State “DONE” from “TODO” [2023-12-09 Sat 16:16]

Eventual is probably based off nullman.net Start by tangle on save if in init dir SO answer and also do a starterkit loader that check date of el and org and regenerates if needed. Eventually the el file is not needed but let’s convert fully first (unless you need fast starts) Done years before date here.

Aquamacs

This file used to under Aquamacs, I use Aquamacs because it was the easiest distribution to set up in 2002. Nowadays with package loaders and starter kits this is not so needed.

Aquamacs does have one advantage it uses Apple’s spellchecker and that will not be rolled into GNU. - although I found a package that does use this. Aquamacs though is old Aquamacs 3.4 GNU Emacs 25.3.50.1 Emacs is now on 26 and has been for over a year but if we don’t need new packages then version is OK. Now in 2022 some packages need emacs 26.1 and so don’t use Aquamacs.

Load order

Startup files aquamacs looks in are site-start.el then init.el and in a directory order not including ~/.emacs.d/ (actually it does include this)(Aquamacs loads Preferences.el I just make that load init.el so I could use a more standard emacs note that would need to deal with customizations as Aquamacs already has set that. Also see Emacs manual on init-files

From aquamacs-get-custom-file-dotemacs-warning ;; %s ;; Warning: After loading this .emacs file, Aquamacs will also load ;; customizations from `custom-file’ (customizations.el). Any settings there ;; will override those made here. ;; Consider moving your startup settings to the Preferences.el file, which ;; is loaded after `custom-file’:

user-emacs-directory

This is the directory emacs reads and writers support files from. This is a mess as some files are under version control and others are created on the fly. The ones on the fly can have the same name as packages and so stop loading (e.g. Tramp and Calc). There are several ways round this e.g. No Littering Aquamacs does this by moving user-emacs-directory and putting the start dir on the load-path but also every possible directory so can’t find it easily and hard codes paths and no use a directory so have to have our own const.

Aquamacs does drop a lot into its directory and makes use-emacs-directory always this even if the config files are elsewhere.

Now text based things don’t like spaces (programmers are lazy) I want a structured text editor. The issue here is when tangling the references to files are encoded to remove spaces so the directory becomes ~/Library/Preferences/Aquamacs%20Emacs so round tripping fails.

On using no-littering - all it does is special case some things but not many so better either do Aquamacs way but use a new directory or deal on case by case basis. The latter might be needed for etc files. However It might act as a template - so no harm in setting it. I will still have to set many.

Types of directory

After playing more especially after moving different .emacs.d I think there are at least three sets of files not two.

Data files

Controlled and must be under version control. no-littering etc files. I have in ~~/.emacs.d/data/~

Shared files

Want to keep across machines e.g. News - I have on dropbox mwb-emacs-share-dir

Local files

Keep around but only on one machine e.g. backups as they have a file included. In ~~/.local/emacs~

Cache or other short lived.

These probably should be in ~~/.cache~ so can be deleted.

Need to move all init files into a path that has no spaces