Skip to Content

Looking at How I Organize a Document

Overview

In this document I’m going to explain how I’m organizing my documents these days. By documents, I mean written texts - stories, essays, posts like this one, but also, software. Software might not seem like a document, but I use the literate programming paradigm when I work with a computer, so I write my software as snippets of code inside longer essays.

I’ll use my Brutstrap project as an example in this document. It’s a relatively simple CSS theme I made, so should be an opportunity to demonstrate a lot of things without its content getting in the way.

Document Project Layout

Each document exists in its own directory on my computer, under the ~/org/projects/ directory. It’s called projects because within Org-mode, the name for collections of files published together is a “project,” so each document exists as a “document project.” Brutstrap’s “identifier” is brutstrap-css - that means it’s at ~/org/projects/brutstrap-css/.

The root of that directory contains the document in various formats (HTML, plain-text, Markdown, and others), as well as a README.md and a media-package.json.

There’s also a subdirectory, src/, which contains an index.org and subsubdirectory, build/ which has in it an index.html and brutstrap.css.

The only file I edit by hand is src/index.org, which is an Org-mode text file. All the other files are created by using Org-mode features on that file.

The Source File

Here’s a walkthrough of what’s in that file. I’ll break it up into the front-matter, introduction, document contents, and supplements.

Front Matter

#+TITLE: Brutstrap
#+AUTHOR: emsenn
#+EXPORT_FILE_NAME: ../brutstrap
#+MACRO: document-type CSS theme
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="./src/build/brutstrap.css">
{{{document-brief}}}
#+TOC: headlines local 4

Let’s look at this line by line:

Past here, the document is divided into three sections: an “Introduction,” the document contents itself (here, “Brutstrap,”) and “Supplements.”

Introduction Section

Here’s the Introduction:

* Introduction
  :PROPERTIES:
  :CUSTOM_ID: introduction
  :END:
{{{document-is-draft}}}

In this document I explain...

{{{document-eli}}}

Again, line by line:

Document Contents

That’s it for the “Introduction”. The “Brutstrap” section contains the Brutstrap theme itself - explaining how I literately program CSS is beyond the scope of this document. In short, using Babel, I’m able to write short blocks of CSS, and extract them out to ./src/build/brutstrap.css.

Supplements Section

The “Supplements” section contains four subsections:

This section contains a JSON source block which implements a specification I’m developing for what I’m calling a media package, which is a manifest of information about a piece of media content.

Explaining that is beyond the scope of this document, in part because it’s in development, so I’ll just show the JSON here:

"brutstrap-css": {
    name: "Brutstrap",
    creator: "emsenn",
    license: "CC0",
    languages: ["en_US","CSS","HTML"],
    versions: {
	"current": {
	    "sourcehut": {
		"location": "https://git.sr.ht/~emsenn/brutstrap-css/blob/master/",
		"formats": ["html","md","pdf","tex","txt"]
	    }
	}
    }
}

Conclusion

And so that’s it, how I manage a document as a project, exporting it to various different formats, maintaining a README, and so on, by just editing one file for each document, one at ./src/index.org.

Editorial and License Information

My name is emsenn and I wrote this essay for the benefit of the commons. To the extent possible under law, I have waived all copyright and related or neighboring rights to it. If you're viewing it on a remote server, you're encouraged to download your own copy. Essays like this are made possible with financial support from readers like you. Thank you. To read more of my work and to learn more about me, visit https://emsenn.net