NOTE: Skip to: ☞ TL;DR - Start Here: if you are ready to install Modular Emacs NOW Skipping over Introduction, History, Purpose, etc… i.e., You just need to get all this going asap!
Welcome to Harmonic Alchemy Modular Emacs V3.6.2 (point release) [Q2 2024]
Modular Emacs provides a simple method of dispatching your emacs configuration in steps based on initial choice of modules starting with essentials loading first, and then loading optional user chosen modules…
There are module configurations for: Dev♺Ops other configurations for Pub✎Ops and yet others for 🎥 MultiMedia workstation IDE tasks. Or ALL the Above completely capable of running on older but reasonably powerful laptops/desktops (that would otherwise be considered legacy by most other standards).
In Addition org-mode based Document Templates are being designed, (still in beta design mode) which when exported via LaTeX, produce the fineset quality typeset PDF or eBook docs which can be printed as hard copy books, or used with eBook readers for a quality reading experience… See: 📸 Screenshots: below to see examples… (images to be added later)
Publishing via org-mode/LaTeX is being made as simple as possible, starting with these templates, allowing individual writers to immediately dive into professional publishing and independent book selling without depending on outside typesetting or publishing firms…
Emacs Org-Mode also makes it possible to do Literate programming… Many of the templates being designed here show examples of this and other nice tricks to empower you as an individual writer, programmer, musician, whatever!
I am a systems architect, dev♺Ops engineer, computer scientist, composer/musician, sound designer, writer/publisher. I wear a lot of hats! My Emacs needs to wear a lot of hats as well! The central focus of Modular Emacs is to build empowering features into Emacs utilizing a modular framework that facilitates all the above without becoming an over complicated mess to manage! ”Good Luck With That” 
We are still in V3 BETA (point release) as many changes are still being made to the LaTeX export configurations… So far the Fiction Book Template is Exporting fairly nicely with few or no errors (depending on added content within clones - the bare bones template renders nicely without errors now knock-on-wood!)
When these org-mode export design changes are done, AND all existing Document Templates in PubOps folder are producing nice looking PDF docs, the V3 beta period (point release) will end and that COMMIT will be tagged as the NEW Official *V4.0 Release
Also, These README files are being converted from markdown to .org files which
IMHO is a more professional way to document… Github renders .org files to html
nicely, and you can add a TOC that renders nicely as well… So far only this README file and a few others have been converted… The old README.md file can be found in the ./Docs directory…
All the rest of the markdown files within the Docs directory are being updated one at a time… TBD…
Note: Current Status & Release Notes of this project are documented HERE (WHICH NEEDS AN UPDATE NOW - TBD)
- 💡 Introduction:
- 📜 History & Purpose:
- ☞ Try Harmonic Alchemy Modular Emacs:
- ⚙ Microsoft Windows Support Needed:
- 🙏 My Commitment
- 📸 Screenshots:
- ☞ TL;DR - Start Here:
- ⚛ Get Ready to Start up Modular Emacs for the first time!
- 📢 Ready Set Go! Start Up Modular Emacs:
- 🎨 Usage:
- ✅ Default Package Features: /(built in)/
- 🎁 Optional Packages & Customization:
- 📅 Begin Log:
- 📋 Meta: /(Usage & Templates)/
The history of Harmonic Alchemy Modular Emacs is like a confusing Adventure through many little twisty passages, all alike… (or all different) Everything is Documented Here Now Read it at your leasure. It provides some perspective, insight, and purpose behind how and why things are done here in the present time.
For those of you who feel Harmonic Alchemy Modular Emacs may be exactly what you were looking for, By all means… Lets Dive in!
There are some external requirements… It may take a while… If that’s OK with you, Great!… Lets go… Eventually I will script this up so you can just enter this at the command prompt: ./install.sh and be done with it… Keep your fingers crossed on that but don’t get your hopes up… I am a busy girl!!! That script will have to install a lot of things! It will have to check a lot of system states! I have to work all that out as a non-interactive process. It should install everything (transparently non-interactively) from that single running shell script… If you have to answer questions and make decisions… Better that you execute manually instead, and read the docs first… Right?
Hello MS Windows Veterans…
I admit to having no experience at getting a nice Emacs GUI environment running nicely on MS Windows, as I am a Hard Core Mac user and have not used a MS Windows box since Win-XP days… LOL and I never upgraded to that VISTA crap either… Thank Goddess!
I am sure the newest latest greatest MS Windows (10 now?) is Awesome!!! I just don’t use it… sorry…
Harmonic Alchemy Modular Emacs expects to be installed on a Linux or BSD machine, or unix friendly machine contaning standard unix apps and utilities or proper hooks into such things… Many of these may not be implemented within the canonical Windows OS model and I have no experience sorting that out…
It is hard enough to get Mac OS to behave along side GNU Linux or other free software and open source standards!
I do not wish to abandon MS Windows users however. So I dedicated a document within Harmonic Alchemy Modular Emacs to record any information needed to help get Modular Emacs running on MS Windows.
Please consult: Note for MS Windows Users for more information…
I am looking for a good MS Windows Sys Admin type to jump in here and help… Where are you??? Please open an issue with intro to yourself for me to review… Thanks!
For the rest of us… For now… Let’s learn this together… Please provide any feedback about your experience attempting to install this on a MS Windows box, Please open issues, ask questions! We will get this part done some how… Thanks ;-)
“Always do what is right. It will gratify half of mankind and astound the other.” - Mark Twain
One of the main purposes of this project is to empower lots of creative folks out there who have more brains than money. This project is 100% free software, Free to download, install, and use independently, (both as in “Free Beer” and also as in having “Freedom of Choice and Control” over your Computing Infrastructures)
I have been testing this project to see if it can successfully run on older legacy hardware as well. My aim is to make it possible for anyone, no matter what their economic or social status is, to be empowered to use this…
To GIVE YOU a VOICE, to GIVE YOU MORE CONTROL over your digital life operations and creations. To provide you with a future proof portable/inexpensive way to publish your ideas, stories, projects for the rest of the world to see…
Harmonic Alchemy Productions - Modular Emacs is NOT some cheap publishing tool, but an entire arsenal of professional publishing and project management tools, ALL “free or open-source”, ALL under your independent and private control (No Middle Men Dictating Rules, no “share cropping”)..
I am committed to making this process/journey as painless as possible for you as I have found many other Emacs setups to be way to complicated to make it easy for adoption into my workflow, and you are probably experiencing the same!
On the other end of the spectrum… Installing basic Emacs alone is not enough to get you started (IMHO)… I made a few tweaks to the Emacs Basic Operation to get you up and running with a simple setup that works well out of the box…
You will quickly outgrow that initial setup however, and will certainly want to enable some extra features you are learning about! WARNING! This is where Danger can lurk if you are lulled into installing something that is pure CRAP! Trust me on that… Don’t fall for the hype… Check it out thoroughly before using. Are there a LOT of Stack Exchange posts about that package? That’s a red 🚩 flag…
I hope to make this process of discovery reasonably easy to do for you! The whole purpose of this project is to be able to easily grow and shrink features as needed in any combination thereof… Without getting lost in a tangled mess of twisty little passages all alike! (or different)
If you end up liking Harmonic Alchemy Modular Emacs, please drop me a note to let me know! Please do ask questions, open issues, etc. Thanks! I have been using Emacs since around 1986/87 (OMG that long! off-and-on with gaps in between ;-) but I never shared any of that Emacs knowledge with anyone before now… 💟
Therefore: Here is Modular Emacs! I hope my long years of devOps experience will turn out a nice jewel for new comers to try out and succeed with! Good Luck and God Speed!
Add Screenshots displaying HAP Modular Emacs main Features HERE
Follow the steps below (in a top down fashion beginning with “Requirements:”) to install: Harmonic Alchemy Productions - Modular Emacs for the first time…
Do not skip to the (optional) install guides until you have the basic default configuration of Modular Emacs installed and running (without errors) in your home directory…
Note: It is entirely possible that Modular Emacs will run reasonably without enabling many of the basic modules listed below. Starting bare bones like that may be a good way to get your feet wet without running into initial problems or having to install many required externals, all at once… Later, when you have a better handle on this, try installing some of the extra requirements, (like a FULL LaTeX Package) and then enabling some of the more advanced modules…
Clone this repository into your $HOME directory as: me.init.d. The me. prefix (for Modular Emacs) is put there so that it will not overwrite your existing $HOME/.emacs.d directory (if you already use Emacs, which you will still need operational). We will rename this folder later after all other requirements are complete…
Issue the following command within your default terminal application:
git clone https://github.com/harmonicalchemy/modular-emacs.git ~/me.emacs.dAfter the above is done, leave things here as they are and go do the rest of the steps below… We will come back to this later when we are just about ready to launch Harmonic Alchemy - Modular Emacs for the first time…
Many of the default packages installed with this project will not work with older versions of Emacs. Also the security older Emacs packages is horrendous! Recently, some of the older packages were removed from the updated MELPA and moved to other less-secure repositories. The entire MELPA site is TLS enabled now but these other repos are not very secure… Updated features (acquired securely) are vital for being reasonably safe going forward from 2020 onward… Therefore, I decided not to support versions of Emacs prior to V26 and prefer to only support Emacs V26.1 and up…
Warning! If you have a really old version of Emacs currently installed,
it may break after you update Emacs below… Therefore before
installing a brand new version of Emacs it may be a wise idea
to save your current emacs environment, e.g., .emacs,
$HOME/.emacs.d, etc… as well as a copy of your old Emacs
Application…
This is for a safety net, Do NOT delete your existing setup… You still need your existing Emacs working wile you are getting all the requirements below together for Modular Emacs…
- [ ] Copy/Clone your entire:
$HOME/.emacs.ddirectory and/or$HOME/.emacs file, as well as a copy of your old Emacs application into a temporary directory of your choice before upgrading below… (or compress and make a.zipor.gzarchive file)This will be your safety net for coming back later if you decide you are not ready to upgrade. If anything goes wrong, you will be able to reverse everythig back no problem!
- [ ] Once your house is in order as above: Click this Link to Build or Install Emacs 26+ on Your Platform
Previous versions of Harmonic Alchemy Modular Emacs required installing NODE Version Manager NVM, and Node Package Manager NPM, so that we could use the Visual MarkDown application VMD as a WYSIWIM (what you see is what I mean) editing environment for Markdown files within Emacs…
I have decided to abandon VMD due to a critical security volunerability which has been discovered. I am actually late to getting around to mitigating this problem… Since Harmonic Alchemy Modular Emacs only needed that single NODE JS applicition, I have decided to remove the entire NODE JS elephant so that it is no longer required… You should NOT install NODE JS unless you are a dedicated JavaScript developer, and then you need to be extra careful about what apps from other devs you may wish to install… “It’s a jungle out there, makes me wonder how I keep from going under!” - GMF
I recommend installing Ocular on Linux, and use Mac OS built in Preview to see your markdown files rendered for reading normally etc. I am no longer writing docs in Markdown as you can see this README file is now written in Org-Mode… Github displays .org files great and you can even have a Table of Contents!
So going forward with Harmonic Alchemy Modular Emacs we will be doing ALL our docs from now on in org-mode and taking advantage of the nice org-mode features I have tweaked and beautified for Writers, Authors, Coders, i.e., anyone tired of plain jane org-mode appearances…
Multimarkdown and mmd-mode are NO longer required or configured for use by Harmonic Alchemy Modular Emacs…
As above for NODE JS and VMD, I have decided to remove this old ancient emacs mode which I had to clone and modify to get it working in newer versions of emacs… I removed external multimarkdown requirements as well…
I am no longer using Markdown as my go-to doc format for anything except WebSites which require content to be delivered that way, and therefore don’t need this extra Markdown stuff that was only needed for Github… Normal emacs Markdown mode works great by itself… Pandoc (optional package below) is a much better universal swiss army knife for converting from one format to another than multimarkdown as well…
Harmonic Alchemy Modular Emacs will run fine without Pandoc installed on your machine, and in fact is not even used internally… Pandoc exists as an external tool you may need from time to time to convert from one format to another when Emacs or Org-Mode cannot perform the same thing internally…
Therefore, instructions for getting Pandoc installed on your platform are included here but it is not required for operation… It is “Extra for Experts
Read the docs for Pandoc to decide how to use them. More instructions for installing and using Pandoc can be found on the Pandoc Official Website…
The Pandoc.org website has most everything you will need all in one place!
FOLLOW THIS LINK to Harmonic Alchemy Modular Emacs’ Pandoc Install Guide (All Platforms)
Harmonic Alchemy Modular Emacs recommends a few fonts to be installed on your system to get Fancy Org-Mode, Fountain Screenplay, and coding frames/windows/mode-lines, etc. looking as good and “readable” as they possibly can.
HOWEVER THIS IS NOT A REQUIREMENT for PROPER OPERATION
You may or may not be fine with the fallback default fonts if the fonts below have NOT been installed on your machine… I have not tried defaults so your mileage may vary…
Other fonts will be required by LaTeX (for exporting to external document types). That process will be covered in a seporate doc and as well is also not entirely “required” for proper operation of Harmonic Alchemy Modular Emacs.
For Instructions on how to install modular emacs recommended fonts on All Platforms, FOLLOW THIS LINK… Afterwards, you will see some nice looking “writers” fonts in Org-Mode as well as while editing Fountain drama scripts!
Some of the newer (OPTIONAL) modules to be enabled within Harmonic Alchemy Modular Emacs will require Python packages to be installed… This is especially true of Emacs MultiMedia System EMMS which is enabled within optional module: 11-games-pkg-conf.el]
FOLLOW THIS GUIDE to get Python & PIP set up within your local environment so you will be ready when python packages are needed to be installed now, or later…
No I did not forget LaTeX… This is a powerful monster! It needs its own monster doc to install and configure as well… You need it to work with Pandoc as well as org-mode to take atvantage of advanced export options of included example Org-mode Doc Templates within the PubOps Section…
LaTeX provides extended features to produce PDFs, and eBook formats… Emacs can be integrated, (especially org-mode) to be able to export to these fancy formats using LaTeX…
This is Great News if you would like to make Emacs work as well as (or better than) Scrivener… So get on it already OK?
- [ ]
Install Optional LaTeX Publishing Environment:FOLLOW THIS GUIDE…
Harmonic Alchemy Modular Emacs is OPTIONALLY configured to use the popular Graphviz utility, allowing the creation of nice graphs, flowcharts, data diagrams, etc. using a powerful scripting language called dot… The Emacs mode for Graphviz is: graphviz-dot-mode
Modular Emacs invokes: graphviz-dot-mode (independent of whether graphviz is actually installed on your system) when you visit files ending in either: **`.dot`** or **`.gv`** Emacs will format these files nicely for you… But you cannot execute them unless you have Graphviz installed externally…
If you DO have Graphvix installed… When you visit a .dot file, you can compile it with: C-c C-c which will produce an .svg file along side… By default, Modular Emacs is configured to produce SVG vector files instead of .png files which is my preference because if you export and then view it as a PDF you can expand the resulting rendered chart or graph full screen and it will still look very sharp! Not to mention you can edit the resulting SVG file within inkscape to add things to it that Graphviz cannot… Don’t underestimate the power of Graphviz though! READ THE GRAPHVIZ DOCS!
- [ ]
To Install Graphviz - All Platforms:FOLLOW THIS LINK
- [ ] Create an empty file:
custom.elThis file keeps Emacs Internal “Customize” saved settings separate from Modular Emacs constructs and outside of your
.init.elfile! (so you won’t have to worry about tiptoeing over it) Emacs will use this file (initially empty) behind the scenes to save your Emacs internal “customizations”… Git ignores this file. (Which is why we have to create it here now) You will not need to mess with this file after creating it, (unless you want to empty it out and start over when Emacs “customized” things get out of hand)…Create Empty Custom.el File:
touch ~/me.emacs.d/custom.el - [ ] Clone:
me.init.elto:init.elme.init.elis a template for reference only… I did it this way, adding:init.elto:.gitignorefor the purpose of providing more flexible ways to manage your local install of Modular Emacs…me.init.elwill stay in sync with the remote origin while your local clone:init.elruns the show (with any changes you might add) without triggering git to complain about new un-tracked files etc…cp ~/me.emacs.d/me.init.el ~/me.emacs.d/init.el
Later… You may want to edit your fresh new
init.dand change the Banner Message to be more specific to your installation… Also, later we will discuss different strategies of management that will hopefully allow you to build your own setup concurrently and in harmony with Modular Emacs, and be able to easily share any extra features/modules of your own that you may wish to bring to the rest of the Modular Emacs user community! - [ ] FINAL STEP - Make Modular Emacs Folder the DEFAULT ~$HOME/.emacs.d~ Folder:
At the very beginning of this guide, you were advised to copy your existing Emacs setup first. I hope you did that because now you are going to over-write your old installed Emacs configuration with Harmonic Alchemy Modular Emacs!
Therefore if you did not backup, FIRST make sure to rename (save) your existing:
$HOME/.emacs.dto:$HOME/save.emacs.d(if you did not do this in the beginning) You may also have a.emacsinit file outside of the.emacs.dfolder that also needs to be renamed!This is very important!Becase the next steps will overwrite them if you did not change their names!!!Now you are ready to rename:
$HOME/me.emacs.dto:$HOME/.emacs.dmv ~/me.emacs.d ~/.emacs.d
$HOME/.emacs.dis now your new Modular Emacs Local Repository which is also now your default emacs home directory!One last sanity check… Make sure you no longer have a$HOME/.emacsfile still in your home directory… You should now only have a:$HOME/.emacs.d/directory and that’s the only “emacs” in your$HOMEOK? Great!
- [ ] Start up GNU Emacs:
Envoke Emacs either from the menu or command line and hold your breath! After a lot of super computing lisp number crunching flashing away in your mini buffer (wait wait wait… for a BUNCH of packages to download and compile the first time, which can take up to a minute or more!) After that startup should take no more than 5 or 6 seconds at most unless you have some huge new package that needs to be installed…
After your long wait… Bam! You should see your new emacs screen pop up with Welcome to Harmonic Alchemy Modular Emacs! heading your scratch buffer in a frame with a pre-determined row/column initial size!
NO?It’s Broken? Oh My! 🤦♀️What a freaking let down!I feel your pain! OK… Don’t worry if all you see are only numerous compiler warnings… (those are hard to avoid upon first startup with all the new packages compiling etc. Not much you can do about that… The developers who made the packages need to clean that up, you could help them though. You can safely kill that message buffer and move on.)…Yes?It worked?Yay!☕ What a fantastic feeling the first time eh?Note1:I am still chasing an OLD issue with some functions, (not mine) calling the old depreciatedcl(common lisp library)… These will be replaced with calls to the newcl-libreplacement… When that happens you will no longer see the warning: “cl lib is depreciated” at startup… There are several other warnings like this I will eventually chase down as well…It is hard to keep Emacs Lean and Mean with all these * seat-of-the-pants developers building packages that pull in gigabytes of FLUF just to provide some stupid silly function that you can do in three lines by yourself! FLUF = “Fluf is Lousy Unnessary F**ks**t!” (R-rated Recursive Acronym inspired by: Xah Lee & Having to live with F**king GNU)
If you got an error that halted completion part way thorugh, and you have an incomplete emacs startup init screen, try to retrace your steps or try running emacs with
--debug-initturned on… It’s probably something dumb and easy to fix…(This happens to us all the first few times, and comes back again later as well most of the time. Other errors only come up in a blue moon, and then mysterously go away and hide before you can catch them! DOH! Compiler Logs are a hacker’s best friend)
Note2:Fetching/pulling new changes from the mastermodular-emacsGitHub repository to your local `~/.emacs.d/` directory will automatically be reflected within your emacs configurations… No need to copy any more files… But you may be surprised to see some new feature or something working differently. If that bothers you, you may wish to keep your changes separate from the remote master branch. Therefore create your own localtestbranch (or call it what you like) and maintain your local changes in parallel… Change your local branch’s .gitignore to accommodate your needs…Note3:The remotemodular-emacsGithub repository also maintains adevelopbranch where new ideas and features are tried out before folding them into the master branch which maintains the Modular Emacs stable release. You could also create a local branch that tracks origin:develop if you would like to participate in any new things I am trying out before final release… Earlier point versions of Modular Emacs were first staged and tested within the develop branch. Version 3.x is tested on the develop branch currengly. (if not already merged into master by now)… Any time a final release of new features is ready, the develop branch will be merged back into master branch, tagged as a new point release (or major release when a lot of new features have been added to warrant it)… maybe not this time eh? LOLNote4:I have created a new branch called:xah-fly-keyswhere the optional module:12-Xah-Fly-Keys.elhas been enabled by default. You don’t have to make any modifications in order to try this otherwize optional feature when you are on this branch. Try it out! It’s easy to switch back and forth now…
The Harmonic Alchemy Productions - Modular Emacs git repository is configured to ignore your local $HOME/.emacs.d/init.el file… The file: $HOME/.emacs.d/me.init.el is kept in revision and you do not use or touch this file directly… Instead, your standard emacs config file: $HOME/.emacs.d/init.el starts out as a clone of $HOME/.emacs.d/me.init.el allowing you to try out new things on the fly without upsetting the state of the git repo…
HAP - Modular Emacs is configured this way for some good reasons…
- First, it allows you to return to the default setup easily in
case you mess up your
.init.elfile somewhere along the way… - Secondly, this file is intentionally kept very simple…
There are NO implementations there… Instad
.init.elcalls a Module Dispatcherdispatcher.eland that file is responsible for dispatching (loading) the entire emacs configuration (modules) for HAP - Modular Emacs… - Thirdly, It makes it
SUPER EASYfor you to disable your current HAP Modular Emacs in order to try some OTHER Emacs Configuration you may have wanted to try out. (without too much trouble) right in place without hurting your current HAP Modular Emacs Setup… Going back simply involves renaming the associatedinit.elfile, and replacing it with the original, or visa-versa…
Feel free to use your $HOME/.emacs.d/init.el (clone) to try out experimental customizations or tests. HOWEVER… There are BETTER Ways to customize HAP Modular Emacs leaving your .init.el as is… (other than changing the
boilerplate heading that gets displayed to suit your fancy) This is the
purpose of dispatcher.el and the my-modules directory…
You can also use the Emacs *scratch* buffer to paste experimental lisp code to try out before making it permanent as a stand alone .el emacs lisp file, (as the welcome banner suggests ;-). Evaluate the entire *scratch* buffer without needing to remove the banner message at the top as that message is one huge lisp comment… If something horrible happens, no worries… Simply restart emacs… Your mess-up will be gone and you will be back to where you were before you or that elisp test code goofed up…
If your customization proves stable, and you like it, you could then save your scratch buffer (as is) to a new file, for example:
$HOME/.emacs.d/lisp/my-modules/xx-my-new-module.el
In all cases you would also be wise to also create and checkout your own private local test branch (call it what you wish) and keep all your custom changes in there separate from the master or origin:develop branch…
The directory: $HOME/.emacs.d/lisp/my-modules/. is NOT tracked by git… So you can put anything in there without upsetting your local or remote tracking branches…
ALSO if you copy any of the files from: $HOME/.emacs.d/lisp/modules/. to $HOME/.emacs.d/lisp/my-modules/. They will OVERRIDE the ones in modules and will NOT be tracked, SO you can try out mods within my-modules without messing up your current git status… If something goes wrong, simply delete or rename your clone within my-modules and you will be back to where you were before…
Easy Peasy.. (this all works in a similar way to how the oh-my-zsh repository behaves for local ZSH configurations)
You can even clone OTHER git repos wihtin my-modules without messing anything up! This is better than using lousy sub repos or what ever that is called… I tried using git sub-repositories once and then ran for my life scared as shit after that initial crappy experiece! LOL “What were you guys smoking when you created that mess?” Alisha is very opinionated about some things eh? RIGHT!
HAP Modular Emacs comes with my new customized version of the Blackboard color theme (patterned after the famous Textmate Blackboard Theme) which I like for the pedagogic essence it inspires… I have also tweaked it to look good under my Fancy Org Mode colors and faces. If you would like to add more custom themes or a different theme than blackboard.el, you can replace it or add additional themes into your local branch’s: $HOME/.emacs.d/lisp/themes directory and they will also will work with this setup by choosing M-x load-theme or changing the last line within $HOME/.emacs.d/lisp/modules/06-interface.el to:
(load-theme 'your-chosen-theme-name t)
Note: Obviously if you add more themes to your Modular Emacs themes
directory you will be adding new un-tracked files to your
cloned git repository! (this one does not have an untracked
my-themes directory option like my-modules is set up - but
I may add this later if needed)…
Make sure you have checked out your own local branch before
adding new themes or doing any customization outside the
init.el file or the my-modules directory, OTHERWISE you will
get out of sync with remote tracking branches!!!
Checking out a LOCAL untracked branch is the proper way to do code management of your own local custom changes tracked seporately under your own code revision schemes in place ready to merge any NEW changes from the remote Modular Emacs branches any time you feel that may be necessary… (merging conflicts along the way as needed)
The default Emacs Welcome Message is replaced with a custom greeting banner that shows the current emacs configuration, and date… With a famous Mark Twain quote (My Favorite author)… This quote may change from time to time with new updates…
Use Scratch buffer to evaluate snippets of lisp without having to remove
the welcome text… (which are lisp comments)
- powerline - Decorate
mode-line& make it More Informative. You can customize options and use themes etc…THIS PACKAGE IS DISABLED BY DEFAULT… I am back to the Emacs default mode line and I customize that instead. I did not remove the code to enable powerline though. If you like powerline, the code for enabling it is located within02-package-conf.el… Read the comments in that file to find it… - auto-complete Easy Text Editing with suggested word completion.
THIS PACKAGE IS DISABLED BY DEFAULT…I am NO LONGER USING THIS FLUF!With AC enabled… When entering code, if you enter a function name and completion pops up, you are
TRAPPED! OUCH!!!I don’t like that! If I want to keep typing (not accepting the default or maybe what I want is different than what it thinks?)… It fights me… I have to fool it by typing some junk and then pull off a text switch game.... LOL!The code that activates auto-complete has not been removed yet but it is commented out to disable ALL of it…
If you LIKE AC, (you are an odd one if you like being trapped) you can still go in and un-comment the related code within
02-package-conf.eland enable that mess if you so choose!I may soon delete all that FLUF code out later however…
- exec-path-from-shell Get environment variables such as
$PATHfrom the shell. btw, this can be a tricky thing to do in emacs! I have struggled with this on Mac OS for a while! You may find you have to start Emacs from the terminal to get all your environment vars into Emacs! More about that later.. A continuing saga!Update 2020:This has been working fine on my iMac since completely replacing Homebrew with MacPorts. IMHO (biased by a host of irritant issues using Homebrew over the years) MacPorts is a much better package manager all around… But not the popular one… Oh Well… %^) Also, since building my own Emacs from GNU source tree on my iMac, configured just how I like it, I have had no more nagging MacOS related issues… And I can have the latest Emacs the second it is released (one build cycle away, or choose to go back to my archived app if they introduce some bug or someting!
- helm Helm is an Emacs incremental and narrowing framework that
helps speed up operations on commands with structured command
completions and more. It is a programmable interface (API) as
well. To see how HELM can speed things up try a prefix key
like:
C-xorC-corM-xand just wait before typing any more keys… You will see all the possible key-combos currently associated with that prefix key pop up in the HELM mini-buffer! Fantastic! No more guessing! (Oops! What did I just do? OMG!) - helm-core Development files for Helm (API) dependency.
- popup Popup is also a dependency package used by helm.
- which-key Another Dependency package used with helm…
This package pops up suggestions for what can follow after
pressing
C-xkey… (this is what I was talking about above in the intro paragraph for HELM)Note:xah-fly-keysalso uses helm to pop up leader key choices and extended menu… Hit theSPACEBAR(LEADER KEY) and wait a second for helm to pop up the list of options… (with help feature and pagination! Vital for learning all those keys!)
- ztree An efficient directory tree comparison utility. Invaluable for visually oriented thinkers! Integrates directly with ediff files!
- To invoke Ztree Diff type:
C-c z(normal Emacs edit mode) or symply type"z"from Xah-Fly-Keys Command Mode, and then choose directory"A"&"B"(as prompted) to compare all files within both directories. - Make your screen wide to see both directories listed side by side. The file names are color coded, indicating status/differences within in two side by side buffer lists of all the files within both directories.
- This list of files can be navigated in a similar way you navigate a dired buffer… Putting cursor on any filename and hitting RET key will open the two files within an eDiff session…
- I used to use external diff/merge tools like kdiff-3 but I
find Emacs to be superior (if not quite as slick GUI looking)
but that does not bother me in the slightest… The powerful
user configurable functions made available within Emacs are
(to my eyes) the Beauty of Form and Function in action!
The prase “Form follows function has been misunderstood…
“Form and function should be one, joined in a spiritual union. - Frank Lloyd Wright…
- To invoke Ztree Diff type:
- imenu-list Right panel Menu and Variable list
CURRENTLY DISABLED UNTIL FURTHER NOTICEYou can toggle an imenu list right panel window to view variables, functions, headings, etc. iMenu List uses iMenu and displays the listing in a narrow window on the left side…
Note:For some reasonimenu-listis not working currently. There seems to be a problem with:window-display-bufferreturning nil with the classic:wrong number of argumentserror… I am currently troubleshooting this… For now simply use imenu by typingC-c ', or by typing the single quote character:'by itself (when you are in Xah-Fly-Keys command mode)…When I have iMenu-list working again those keybindings will call it instead… It provides a nice side bar that you can navigate. The side bar stays there for you to use over and over again until you toggle it back off again… This is much better than using iMenu alone which pops up in HELM but goes away as soon as you use it…
- dired-launch Open files directly within dired using default
applications. Great for quick viewing PDF or Image files
with your OS default viewer app! You can use
dired-launch-extensions-mapto specify, for a given file extension, one or more preferred applications by simply specifying the application as a string.example:(setf dired-launch-extensions-map '(;; specify LibreOffice as the preferred application for ;; a Microsoft Excel file with the xslx extension ("xlsx" ("libreofficedev5.3")) ;; specify LibreOffice and Abiword as preferred applications for ;; an OpenDocument text file with the odt extension ("odt" ("libreofficedev5.3" "abiword"))))
Note:The above is for launching apps (inline your emacs buffer) but there are many ways to skin this external app launch business… the following commands will launch a file in an external application whilst your cursor is positioned on a file in a dired buffer:W, orSPC i win Xah Fly Keys command mode… (Xah Fly Keys must be enabled for this leader key sequence in Commnd Mode) but simply typing upper case W is easier IMHO.
- neotree Spawn a directory tree relative your current working
directory location. You can toggle a
neotreeleft side panel window from any open buffer window using a single key… Type:C-c d(normal Emacs mode)Note:I have been using bookmarks pretty nicely for a while now and not using this neotree feature all that much… but it is a quick way to navigate from your current buffer/location when you are NOT within dired… Your mileage may vary…
- ztree - Ztree is a project dedicated to implementation of several
text-tree applications inside GNU Emacs. It consists of 2
subprojects:
ztree-diffandztree-dir(the basis of ztree-diff)…The ztree-diff utility configured to work nicely within HAP Modular Emacs and clean up afterwards… (still workng on the clean up part ;-)
- smart-tabs-mode - Intelligent tabs to end the f***ing tabs vs
spaces war already
OK?Click the Link & Read the docs… :-)THIS PACKAGE HAS BEEN DISABLEDOver the years I have found smart-tabs to be quite dyslexic and problematic.. For a while now, I simply disable TABs normally in Emacs and set indent space to 3 chars for the default… Other modes/packages have their own automatic ways to prettify the code… So I believe I am all set NOT using smart-tabs-mode going forward Q4 2022…IF YOU WOULD LIKEto enable smart-tabs-modeTHEN:Edit:$HOME/.emacs.d/lisp/modules/04-devOps-pkg-conf.eland remove the coment from the line below:
(defvar me--req-devops-packages '(ztree ; smart-tabs-mode ;; DISABLED while exploring other options... ssh-config-mode yaml-mode nginx-mode php-mode ;; SOON to be REPLACED indent-tools logview))
(also un-comment any smart-tabs related configs further down the page. Search for Heading Comments)
- ssh-config-mode - A mode to edit SSH config files. If you edit those files you will see nice colors of keywords etc.
- php-mode - Major mode for editing PHP code. This just works on PHP files alone… I am using xah-lee configs for all other web, JS, Yaml, etc… Xah is working on a php-mode… When that is finished I will most likely adopt it to match all the other web modes…
- yaml-mode -
- nginx-mode -
- indent-tools -
- logview -
- markdown-mode Markdown Capability Within Emacs. If you write for the web You cannot live without this… Although I use Emacs org-mode for most things, even publishing to web pages… Some Web engines require content to be submitted as raw markdown… (this makes that process work well)
- markdown-toc Generate a TOC in a markdown file
This is a simple but powerful mode to create a TOC in a
well-formed markdown file. In other words: The generated
TOC will be well-formed if your markdown file is also
well formed. ;-)
Note:I like to place my toc at the bottom, and provide a simple link named: `table-of-contents` or `index` and put that link at the top, as well as strategic places down within the body of the markdown file… It reminds me of the way we used to do a similar thing in HTML before Javascript enabled fancy CSS menus started popping up… Now we have mobile menus to contend with. Oh My! - deft Major mode for quickly browsing, filtering, and editing
directories of plain text notes. Created by Jason Blevins
(the same statistics economics professor at Ohio State who
also created Emacs Markdown Mode) This guy is wicked clever!
Looks like he has some nice algorithms for studying the
cryptocurrency and smart contracts world as well! Invoke Deft
Mode with custom Xah Fly Keys Command Mode key:
0Note:Deft is a powerful search/filtering tool and as such sometimes it takes a while to get results… After typing a few keys if you wait too long (before quickly finishing your query) it may appear that your screen is frozen. (and in fact it is) while DEFT cranks away using lots of system resources to get your juicy results!No Pain... No Gain... - pandoc-mode pandoc-mode is an Emacs mode for interacting with
Pandoc. Pandoc is a program (plus libraries) created by John
MacFarlane that can convert a text written in one markup
language into another markup language.
pandoc-mode IS CURRENTLY DISABLED(commented out) and not used by HA Modular Emacs I am evaluating whether pandoc-mode is useful for Emacs… Also, Pandoc Installations ARE a BEAR to install on machines which already have HUGE LaTeX packages installed!!! I am not currently using Pandoc (yet) so I have decided to comment out the code for now… It can easily be re-enabled… - fountain-mode For writers, screenwriters, etc. A markdown mode
for dramatic arts! Fantastic!!! Fountain together with pandoc,
allows you to do many conversions for screenplays to industry
formats like Final Draft etc. but the best part is the text
highlighting and colors make it very easy to read/rehearse dialog
and cues right from an Emacs buffer! Writing scripts in this
mode is as natural as typing
INT/(your line instantly turns into a scene heading!)_ Try it! Just start typing your script and find out what happens! Modular Emacs Fountain Mode has been customized to use a nice looking Typewriter style mono font! It also opens up in olivetti mode (next item below) automatically setting the line width to 100 chars…Update 2020:I am writing docs for using fountain-mode within Emacs, as well as providing some example drama scripts and instructions on how to publish them to PDF using a tool called Afterwriting… Stay tuned for that… - olivetti Olivetti Adjusts Margins With Word Wrap (great to use with
fountain mode!) Perfect for distraction free writing! I also enable
this within
rmoo(if you have the games module enabled). Toggle it on and off within Xah Fly Keys Command Mode by hitting the backtick character:(`)key… Adjust the margin width within Xah Fly Keys Command Mode by hitting:SPACEBAR [or:SPACEBAR ]to shrink or grow respectively. - vmd-mode Fast Github-flavored Markdown previews synchronized with
changes to an emacs buffer (no need to save).
THIS PACKAGE HAS BEEN REMOVED - VMD NOT SECURE!After discovering the big security volunability of the NODE JS App VMD (Visual MarkDown) I decided to stop using it, remove it from all platforms, and since I don’t use it, I removed vmd-mode from HAP Modular Emacs configuration as well. I am using org-mode now for ALL writing operations… I only needed it to update previous markdown docs… (this README Doc was the first to get converted ;-) If I need to update any of those they get immediately converted to .org files as well… (all of these HAP Modular Emacs Docs are getting an org-mode facelift while they also get updated)
Since I only use NODE JS to install LTS versions of JS apps and the only one I use now is VMD, I decided to remove ALL NODE JS related software from my operation.
JS is DANGEROUS
- flyspell-correct This package provides functionality for correcting
words via custom interfaces. There are several functions for this:
flyspell-correct-wrapperflyspell-correct-at-pointflyspell-correct-previousflyspell-correct-next - helm-flyspell Helm extension for correcting words with flyspell.
- flyspell-correct-helm Nice helm interface for flyspell…
Place your cursor after any misspelled word and type:
C-;to see a list of suggestions…
NOTE1:Key Bindings are ALL defined within:12-Xah-Fly-Keys.elAND13-key-bindings.elI have not listd them here yet, as many of them have changed, or need to be removed etc. They will most definately be listed here nicely for HAP Modular Emacs V4.0 (soon to be released)Note2:If you type a prefix key: (e.g., ~C-x~ /,C-c, orM-x, etc.) and wait a second,You Will See a HELM Pop Upshowing all the key commands available to choose from!!! EURICA BABY! This ALSO works forSPACEBARin Xah-Fly-Keys command mode. No guessing needed…The Helm Popup has a menu tonavigate the whole list as well… Try it!!You will be using this to learn keys more than taking the time to look them up in these docs or code because it’s all there at your fingertips, thanks to HELM…
Now it’s time to forget boring defaults and really tune this baby up to be the best DevOps , PubOPs , Lisp IDE that it can be!
The following doc with guide you through that process:
- Modular Emacs Customization - Optional Packages & Customization
Note: These Extra Features are constantly “a work in progress” as new
options come up that work better, and other options turn out to
be more trouble than worth… etc. etc. etc… At the same time
I have to document all of this stuff and then revise, revise,
revise… Many of you know this delima… %^) Org-Mode helps
tremendously! I will be updating these extra docs after weeding
out the dead-wood… (which is my current task to get ready for
The major release of: HAP Modular Emacs V4.0 on the horizon…
No Logs So far… This feature is under evaluation and may end up not being used…
Not Here Yet but keep logging… The New Year will be here soon enough!
<2021-03-29 Mon>
This Log Entry is about: Yadda… Yadda… Yadda…
- Link to Project: [[][] ] (comment)
Yadda… Yadda… Yadda…
- [X] New Item 1: (this represents a completed item)
- [-] New Item 2: (this represents a currently “radio active” item)
- [ ] New Item 3: (this represents a new item not worked on yet)
- [ ] New Item: (copy/clone more of these as needed)
New Item Details… Yadda… Yadda… Yadda…
Re-Purpose these as needed and Delete anything you don’t need…
Add sub headings as needed…
Don’t forget to clock-in to HEADINGS while you work on them… AND… Don’t forget to Clock OUT when you are DONE… %^)
New Item Details… Yadda… Yadda… Yadda…
Re-Purpose these as needed and Delete anything you don’t need…
Add sub headings as needed…
Don’t forget to clock-in to HEADINGS while you work on them… AND… Don’t forget to Clock OUT when you are DONE… %^)
New Item Details… Yadda… Yadda… Yadda…
Re-Purpose these as needed and Delete anything you don’t need…
Add sub headings as needed…
Don’t forget to clock-in to HEADINGS while you work on them… AND… Don’t forget to Clock OUT when you are DONE… %^)