Hey folks! I hope everyone’s week has been going well. I’ve enjoyed the little conversations some of us have been having through the week.

Today I’d like to announce a small little project I’m working on: HashUp.

 

I’ve always been dissastisfied with the physical act of writing: with pen and paper it’s slow and requires a fair amount of concentration to write smoothly, and with computers… well, there’s What-you-see-is-what-you-get style editors like , which I dislike: I’m not trying to typeset a document to be printed, I’m trying to write! Unfortunately, most non-WYSIWYG editors and formatting languages like are similar in the same fundamental way: they exist to facilitate visual formatting, not help an author encode semantic meaning.

I pretty much never want to, when I’m writing, record that a certain word is italicized. I want to, maybe, record that it’s emphasized: modern HTML has at least come that far, letting handle the styling past that semantic.But more likely, as a writer, I want to say, “this is a foreign term,” or “this is a character’s internal monologue,” or, “this is emotional.” All of those are usually conveyed by adding emphasis through italics, that’s not guaranteed, and beside, emphasis isn’t nearly as precise.

When I was using -mode, I got in the habit of using its macros to wrap text that might otherwise be emboldened or emphasized, so that it could also be, say, if the document was being exported as , changed to link directly to my website.

But that was clunky, and by now I’ve drifted rather far from Org-mode, and I’m not even using , the only text-editor Org-mode works in, right now! HashUp is my solution to my current problem, of “I don’t know how to format the text I write in a way that makes it useful to me, later.”

It’s influenced by a lot: what I talked about above, but also using social media and other programming languages.

At its most basic, it’s simple: start using hashtags in your writing, and the HashUp processor will replace them with whatever string you’ve configured. If you want to do something special with that hashtag, throw a pair of {} after

the word, and fill them in with the arguments to the relevant processor function. (If there’s no relevant function, the text is untouched.)

It has a bunch of limitations: there’s no nesting or scope-awareness, so any opened block needs to be closed, for example. And it requires either writing your own processor functions, or me writing a standard set and publishing that.

But! It’s definitely a lot closer to what I want than Markdown, even after just an afternoon tinkering.

Has anyone else tried their hand at a custom markup format? If so, I’d love to see what you came up with!

Today I’m going to continue working on the layouts used for emsenn.net. The goal is to, by the end of the day, have the https://emsenn.net/programming/emsenn-net/ page mostly complete: listing its bulletins, logs, and source files.

I’m not entirely sure how I’m going to organize the source files. I think each file of the source should end up its own page, so that there are pages for, say /programming/emsenn-net/config/ or /programming/emsenn-net/layouts/_default/baseof/

This’ll mean writing some new Hugo types: one for hugo-config, and one for hugo-layout. Others might become evident from there.

(I feel like I should make an Org-mode capture template for adding tasks to a project… can I open a capture template from within a capture template? I’ve just tested it and yes I can, so that introduces a new workflow: begin a log, leave it as I go to add new tasks to projects. I wonder if there’s a way to link to the task from the log, like, paste a link to the entry created by the capture once it’s filed?)

Anyway, for now: work on emsenn.net’s layouts.

In the previous log I sketched out the (rather few) qualities that pieces of writing would have, as well as qualities for two types of writing: logs (like this piece) and notes – short little bits of writing that might get syndicated into a microblog.

The qualities I listed were:

– author
– version history, meaning for now:
– a creation date
– a publication date
– and a date of last modification
– keyword tags

One thing I can’t quite decide on is whether to have explicitly defined /types/ of writing, or whether the Hugo renderer should do the work to infer the type. I think the former, because while that’s more upfront coding (I think), it’s less work throughout the sequence of processing. So, that’s another quality: type of writing.

The next step is sussing out how to record each of these within an Org-mode subtree.

Ox-Hugo [[https://ox-hugo.scripter.co/doc/author/][has documentation]] on how to record an author. Since I use the subtree flow, this means that I should record the author within the =EXPORT_AUTHOR= property.

Ox-Hugo [[https://ox-hugo.scripter.co/doc/dates/#dates-subtree-based-exports][has documentation]] for dates too. It looks like I can use Org-mode’s TODO stuff for it, but I’d prefer to set explicit properties. I’m unsure if I want to use automatic updating dates, so for now I’ll handle it manually.

For keyword tags, there’s again [[https://ox-hugo.scripter.co/doc/tags-and-categories/][documentation]] – here I’m going to use a property instead of Org-mode tags, so that I can use those for Org-mode functionality, like avoiding exports. Plus, I tend to use a /lot/ of tags and so it would crowd my UI.

For recording a type, I don’t see a better solution than a [[https://ox-hugo.scripter.co/doc/custom-front-matter/][custom front-matter]] property.

So here’s a table of the qualities of a log and how to record them within an Org-mode subtree:

| Quality | Assignation |
|————————+——————————————–|
| author | Set the =EXPORT_AUTHOR= property |
| creation date | Set the =EXPORT_DATE= property |
| publish date | Set the =EXPORT_HUGO_PUBLISHDATE= property |
| last modification date | Set the =EXPORT_HUGO_LASTMOD= property[fn:3] |
| keyword tags | Set the =EXPORT_HUGO_TAGS= property |

There are details I’d like to note, about what each value expected is, but I’ll write those into the operations manual, not here.

The final step is creating a Org-mode capture template for logs and notes, which will help automatically create an entry with the appropriate information.

Related, the next step after solidifying this process will be easing the process of actually publishing the updated website, as right now that, not recording notes, seems to be my biggest hurdle.

(And in the future, a way of quickly deducing which tags a piece should have applied would be nice. Rules about what should be tagged and what shouldn’t, I guess?)

Oh – and while “notes” is a rather simple record type, one for say, “programming procedure” might not be, as it’d need to have a record of which programming language it’s for, what library, what inputs, etc., all in a way that the rendering can determine and present.

When I was using Emacs the most, I was beginning to create a series of Org-mode macros that used Elisp functions to construct text. I can’t recall the specifics, but macros like =link(transplanting-traditions)= would return the text =[[https://transplanting-traditions.org][Transplanting Traditions]=, for example.

As I’m reapproaching using Emacs and Org-mode to do relatively sophisticated things, I’m inclined to revisit that approach: writing them by hand is hard to do, and can only be maintained with careful search-and-replace.

The first task in this is to find my old macro functions, and try and reconstruct a working example from there, and then document them properly within my current Emacs client configuration.

Keeping a Personal Dictionary with Org-mode

A few days ago I wrote a letter to my parlour, where I explained how I updated my website to make better use of some of Org-mode’s more basic features, like INClUDE statements, or the index features.

Today I stumbled upon a new use – to me – for Org-mode’s INCLUDE statements. A brief explanation, first:

A file, foo.org, contains the text: /Galavant/ was a great
television show.
Another file has the text:

Here's what I think about /Galavant/:

#+INCLUDE: "./foo.org"

If I export that file, the text will show up as:

Here's what I think about /Galavant/:

/Galavant/ was a great television show.

A silly example. More pragmatically, unless I’ve changed my method since writing it, this document’s introduction contains at least one INCLUDE’d statement – the editorial and license information, and perhaps the disclaimer about literate programming, and the license in the supplements was INCLUDE’d as well. It helps me not repeat myself.

So, that’s INCLUDE statements.

Now, some background on me: because of the type of content I write, I end up being very precise in my use of some terms that might have a more casual meaning elsewhere. In software documentation, “archive” might mean something very very particular. In role-playing games, “sleeping” might not include naps, and so on.

I’ve developed the style of italicizing these key terms when I use them before defined, and using bold italics when I define them: key terms are those words that have a technical meaning within the scope of a document. I also italicize key terms if they get mentioned a decent enough distance from their definition, like in another section. If you’re curious, I’m developing my own Style Manual that explains a lot of my personal rules for this sort of stuff.

A useful thing, especially in longer documents, is being able to include a dictionary of definitions for these terms. If I use the same term with the same definition in a dozen documents, that’s the perfect use of an INClUDE statement.

So, I’ve made a new file, dict.org, and put some terms in it. They look like this:

BEGIN: key-term
- key term :: A /key term/ is a word or phrase whose definition is
              fixed and precise within the scope of a document or
              project.
END

Then, in any document where I’d have a dictionary that needs that definition, I can add in the line #+INCLUDE: "./dict.org::key-term" and the term will render in the dictionary! For the record, the document I was working on when I stumbled upon this need is my Online Communication Manual.

I’ll need to write up the rules for how to name terms – and what to do if there is more than one definition for a term (though I can’t think of any.) But, it’s certainly a better solution than copy-pasting.

Oh, I didn’t even mention: one perk of INCLUDE statements is that if I change the INCLUDEd file, I change what shows up every time the files that use it are exported – so to change the editorial and license information at the head of every document on my site, I just have to change one file, rather than re-copy/paste everything.

It’s always awkward ending essays like this that are just kind of an explanation of how I did a thing. I’m done explaining now. Have a nice day.

1 Introduction

In this piece I’ll explain how I’m maintaining an inventory of what’s in my larder (kitchen: fridge and pantry) by keeping a personal log using Org-modeTK with ledger-cliTK.

1.1 Editorial and License Information

This document was written by emsenn and is released as software under the terms included in the “License” supplement. Please direct comments to their public inbox or, if necessary, email.

2 Steps

2.1 [0/3] Set up your tech stack.

  • [ ] Install Emacs.
  • [ ] Install Org-mode.
  • [ ] Configure Org-babel.

2.2 Create a log.

2.2.1 Create a header

#+TITLE: Larder Log
#+OPTIONS: c:t d:t

2.2.2 Lay out the datetree

* 2019
** 2019-01 January
*** 2019-01-01 Tuesday

2.3 Buy groceries

**** Shopping
#+BEGIN_SRC ledger :noweb yes :tangle larder-demo.ledger
2019/01/01 * Grocery Store
  Inventory:Larder:eggs                    4         @@ $0.99
  Inventory:Larder:sausage                 2    lbs  @@ $1.99
  Inventory:Larder:coffee                 90    tbsp @@ $3.99
  Supplier:Harris Teeter
#+END_SRC

2.4 Make coffee

**** Cooking
#+BEGIN_SRC ledger :noweb yes :tangle larder-demo.ledger
2019/01/01 * Coffee
  Inventory:Larder:coffee                 -3    tbsp
  Life:Eating

2.5 Make dinner

2019/01/01 * Dinner
  Inventory:Larder:eggs                   -4
  Inventory:Larder:sausage                -2    lbs
  Life:Eating
#+END_SRC