🔖 Back To MAIN Modular Emacs README
- 📜 The History of Harmonic Alchemy Modular Emacs
- 📅 Begin Log:
- 📋 Meta: /(Usage & Templates)/
This project has been a long time coming… Its history dates back several years to a time in my life where I had become fed up with how commercial software holds your content hostage, (especially word processors)… I wanted to be able to publish to the web, but also other formats as well… And I did NOT wish to have more than one content source for those things…
For years, as a software developer I used Emacs (for coding, software design-development, and system administration on many platforms) I never had to change tools or content for that process as long as I could have or install Emacs on the platforms needed.
On the other hand, my management of human language documents was a nightmare in contrast! I switched many different word processors, MS Office, Open Office, Evernote, etc. etc. etc… All of this switching and migration from platform to platform caused me a LOT of tedious stressful work that should have been unnecessary to begin with!
All those years I never used Emacs Org-Mode and in fact did not even know about it in the early days… I knew many Physics Professors where I worked at MIT who used Emacs/LaTeX to publish their work as professionally typeset documents… Back in those days I considered all that work to publish way OVERKILL.. but NOT Today… Not if you have worked out all the details and have Templates for all your publishing use cases… Much LESS Overkill than all the wasted time I spent migrating and learning new word processor Apps in the past!!!
I never thought that Emacs would be the way I ended up writing and publishing after many painful “restarts” over the years switching from one word processing app to another on Macintosh, MS Windows, Linux, etc…
The day finally did came however to try out Emacs (first using markdown mode, migrating from the Evernote App), but later scraping that idea, and going full HOG with org-mode…
In order to accomplish this, I needed to figure out better ways to configure my up-until-then BARE-BONES Emacs Configuration… (after having used emacs mostly a code editor for over two decades)…
My Journey started out by cloning a few Emacs repositories on Github and try different things out like that for a while. I liked some things and tried to get rid of other things later. Management became confusing after a while. I ended up with lots of questionable elisp code, much of which were things possibly no longer needed!
After a couple years of adding, removing, configuring, re-configuring, etc. it started feeling like I was painting myself into a tangled corner like getting lost in “a maze of twisty little passages all alike!” Lets face it… I was not keeping good logs and my git management skills were wanting! I was being: “oh that looks cool lets try that” (cowgirl mode)… I got into a wee bit of trouble as a result of my wild adventures! It was all my fault! But it was fun just the same.
As a result of that saga, I learned a lot about SH, BASH, and ZSH best practices… That spawned a complete re-write of my dotfiles project to become multiplatform and I now have a professional MULTIPLATFORM Authoring and Publishing System that produces Professionally Typeset Documents in pretty much any format…
In an attempt do things better and smarter, I decided to start over from scratch and make a modular system from the ground up with the primary purpose of preventing tangled messes like this from happening within current or future Emacs configurations!
Modular Emacs is more than just Emacs with configurable modules… It is also designed to be the centerpiece (command central) of a larger personalized, extensible: Dev♺Ops / Pub✎Ops workstation IDE capable of running on older but reasonably powerful laptops/desktops (that would otherwise be considered legacy by most other standards).
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” 
- Modular Emacs: designed to be easy to maintain and configure through the management of independent modules… In that sense, Emacs hopefully forms a basic sensible framework that is easy to use and flexible enough to adjust to your work-style, programming-style, and writing-style…
- Add Only What You Need: You have choices encapsulated within modules. Each module comes with its own requirements. Removing and or adding many of the extra feature modules will not disrupt the rest of your Emacs configuration. They have been designed to be encapsulated in that way… Some of the more basic modules are required for Modular Emacs basic operation however. The nice thing is everything is modular so it will be easy to find out which ones are doing what…
On the other hand, if you install Modular Emacs stripped of all external helper apps (described below in the *Requirements* section), It may not provide any advantage over many of the other simpler Emacs projects on GitHub… Therefore if all you need is vanilla Emacs (with some of the more basic options thrown in), you don’t need Modular Emacs at all.
Here is a simpler light weight “sensible” Emacs Config which claims to also be modular - I have not tried it. I only briefly read through the README. It looks like a good alternate option to try
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!
Use this Standard README (template) as a multi purpose README document as a Start Here First Document for any kind of project…
I stopped using Markdown files for this purpose a few years ago… This makes total sense as Org-Mode was designed exclusively for such things! Markdown is great for composing content intended for web pages etc. But Emacs Org Mode is Vastly Superior as a Publishing Environment, with many features and power, completely agnostic of final publishing format… Whereas markdown mode excels doing one thing only… Translating author structured plain text into beautiful web pages… (which is a good thing)
I finally bit the long curve bullet and learned Emacs Org Mode (after many many many years of using Emacs without it!) Today, looking back with current knowledge to me is like going back to a “*Dec VT220* green screen *dumb terminal*” after experiencing X Windows on a Big HP-UX Workstation!
Yeah, that’s a personal story from the past, lol… All you Mac users out there, please realize that your beautiful Apple desktop is in fact an HP-UX Motif X-Windows widget set clone! That’s what Steve Jobs believed to be the best X-Windows tool-kit of the day (when he was building the NeXT computer)… So… Yup he copied that! The Applications Doc at the bottom of your screen is a dead giveaway. Hewlet Packard was first to use such UI concepts… (back before the dawning of the web we loved those HPUX Workstations!)
The command key conventions used in the instructions below, (as well as all *Harmonic Alchemy Productions* docs), follow Standard Emacs command key naming conventions.
Official GNU Emacs documentation uses a shorthand notation to indicate the Ctrl key as an upper case C- (with minus appended). Upper case M- (with minus appended) is the shorthand notation for the Emacs META key…
On Mac OS, Modular Emacs maps your Ctrl key to the Apple Command key. Emacs META is mapped to both Alt and Ctrl keys… Outside of Emacs all those keys function normally.
Therefore, for Mac users, anytime you either see C- or Ctrl below, use your Apple Command key for that when using Modular Emacs. Anytime you see either M- or META below, use Alt or Ctrl keys for that when using Modular Emacs.
Anytime you are using Modular Emacs following instructions from standard vanilla Emacs docs, keep in mind your Ctrl and META keys are not “standard” anymore and you must make a mental translation. Beyond that, you will be fine following other emacs tutorials etc. Hey… you Mac enthusiasts are used to that kind of “being different” stuff anyway, right? Being one of “the rest of us” that is… What the heck does that mean anyway? LOL
The above key assignments were done to get the Emacs C- key closer to the space bar where it can be activated with your left thumb instead of contorting to get at it with your pinkie finger. This makes using Xah Fly Keys even easier to use and less stressful on your fingers…
In the Official Emacs documentation you will commonly find key command notations such as C-x or M-x… This means: Hold the Ctrl (or *META*) key down while typing the x key.
Any time you see this notation, regardless of what key may be connected to it with a dash (e.g., *C-c*, *M-5*, etc.), this means to hold the Ctrl-or-*META* key down while you press the other key connected to it with the dash… If you have a command that includes many C-key or M-key commands in succession simply hold the Ctrl-or-*META* key down the entire time you type the other keys and then let go…
If you see other keys alone separated by a space after the C-x or M-x (e.g., C-x *d*, M-x *b*, etc.) this means to type that key AFTER letting go of the Ctrl-or-*META* key…
Got that? That’s the key notation system we use here… It is all standard Emacs… The above paragraphs are mostly for the benefit of new Emacs users! And there is more to learn below. If you are an Emacs/Org-Mode veteran please bear with us…
\newpage
This Template utilizes the default Org-Mode: ”C-c .” command (i.e., That’s Ctrl-c and then type a dot. This Enters a timestamp range at the cursor position). The command employs org-evaluate-time-range to compute time on task. This is useful for timesheets etc.
In addition, the Log Entry (template) stores and tracks Org-Mode :CLOCKING: entries and displays results in a Time Card Table with total time computed…
Common time clocking commands are defined within the Log Entry (template) itself. Any time you need to look up clocking commands, open the :README: drawer under the Log Entry (template) heading by placing your cursor over it and hitting TAB.
Additional commands for using Org-Mode with Modular Emacs will be explained here if needed, as well as other Harmonic Alchemy Modular Emacs Templates that get produced in the future…
\newpage
- [ ]
Clone:NEW 🗓 Generic Log Entry (from: ⎘ Templates: binder) - [ ]
Select the Heading(named above) from the ⎘ Templates: binder, using normal Emacs selection methods. i.e., Typetkey to set the mark for selection, (xah-fly-keys Command Mode) or useC-SPACE(normal Emacs), and move the point to get the entire heading, and all of its contents, but NOTHING else… and copy it…Note:Before Copying Selected Text, ensure your cursor is at the end of it BUT not be part of any items after it… Placing your cursor on the first column of the next line will include the invisible new-line character which is what you want, but any text directly under the cursor on the next line will not be copied… Later, after pasting this text somewhere else, your cursor will end up sitting on the first column of a blank line under the pasted text. (exactly as intended) - [ ]
Complete the Copy OperationTypec(xah-fly-keys Command Mode). This will save the selection for pasting later, (the highlighted text will go back to normal)… You should have gotten only the Single LOG Entry with ALL its contents, BUT nothing else below it…Note:If you type: ”spacebar t” (xah-fly-keys leader key command) it will show you the contents of your paste buffer… You can see the LAST item you copied in there AT THE TOP… To get out of the paste buffer view, type: ”spacebar u” and it will return you to where you were before… - [ ]
Paste Cloned LOG Entry:[0/2]- [ ]
Advance cursorto a blank line just below the LAST Most Recent LOG entry under heading 📅 2022 within the 📒 Begin Log: section, and press ENTER a couple times to get your cursor on a fresh clean line with some extra space above and below it… (Below any previously time stamped entries you may already have placed)… - [ ]
Press:v(xah-fly-keys Command Mode) to paste your cloned Log Entry template… If you find out that what you copied also included some unwanted text directly below it, no problems… Just delete that part now…Note:If you accidentally copied one or more previously invisible bullets to column one on a blank line they will create an invisible “ghost” heading that you will now need to delete…You will know this if you see an org-ellipsis “⤵” symbol on a line by itself indicating a heading but no text… Simply delete that whole line and it will go away… Now you are ready to compose your new log entry…
- [ ]
Note: If this is your first time using this log, don’t bother cloning a
NEW log entry as there is a dummy boilerplate placeholder Log
Entry ALREADY in place for you to use…
(initially there as an example)
The instructions below for modifying the Boilerplate Log Entry, or Editing a new Cloned Log Entry Template are pretty much the same… (differences will be noted in instructions below)
- [ ]
Place cursor directly on the existing timestampof the NEW Log Entry, and enter the key binding:C-c .(i.e., pressCtrlkey while holdingcand then type a dot ~.~ /) A date chooser panel will pop up… - [ ]
Type one more dot:.to force the calendar selection to the current time and date and then, PressENTERto accept your choice… This will update the existing older timestamp with the current date/time… Check to make sure the timestamp was properly updated and then move on to the next step… This timestamp will not be updated after that. It records the initial time of your new log entry to the Day and time you first created it… - [ ]
You are now ready to startmaking entries within your New Log Entry… Your timestamp indicates the present, -and- you are all set to begin recording timef… - [ ]
Follow the:README:directions within the Time Card section contained within your fresh new log entry to learn how to “clock in” and “clock out” of your log entry as you work on the tasks…
Two sub headings have been provided for your use (if you need them). However, you may structure your log entries any way you wish. The two provided headings: Summary and Details are simply suggestions to help make your log entries a bit more organized…
The Summary heading could be used to log the main executive summary points, (which you would include in the exported PDF as a report to give to your boss or clients).
Conversely, the Details heading could contain a complete, thorough log of your work, which would be excluded from the final PDF report. Everything under Details heading would be extra information that you don’t want to bother your clients or boss with (unless they ask for more detail of course). In that case, you will have it all recorded and organized for easy access later if needed…
Place the :noexport: tag at the end of any org outline heading to exclude it and all its children from the PDF upon export… You can add as much detail as you need within these excluded sections without cluttering up your final PDF. The entire main heading: How to Use this Template: is already excluded from the final PDF, so it can be left in and your PDF will only include the Begin Log: section…
<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… %^)