content overhaul for first post

[kengrimes.com/content.git] / content.org

#+hugo_base_dir: .
#+hugo_level_offset: 0
#+seq_todo: TODO DRAFT DONE
#+startup: indent showall

* Home
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:END:
** Computers are the Devil
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/blog.png
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main" :weight -1 :title Blog
:END:

** DONE Using ox-hugo To Build Websites with Emacs :org:emacs:hugo:@tutorial:
CLOSED: [2018-04-11 Wed 21:56]
:PROPERTIES:
:EXPORT_FILE_NAME: ox-hugo-tutorial
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
:END:
This article explains in detail the process of setting up a bare-bones website
using Hugo and org-mode. My goal in writing this is to provide readers with a
superior understanding of the fundamentals of this workflow. It is by no means
an exhaustive explanation of org-mode or Emacs, but should give readers of any
skill level a strong foundation to apply their own knowledge and techniques to
the Emacs-Hugo toolchain.

I assume only beginner-level knowledge of Emacs.

*** Intro & Setup
[[https://github.com/kaushalmodi][Kaushal Modi]] made ox-hugo by extending org's ox-blackfriday package, providing
an impressive amount of features for organizing blog text and linked data with
Hugo. He maintains [[https://ox-hugo.scripter.co/][great documentation]] and ample [[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content-org][examples]] for using the
package. I will explain my own workflow here, but for an exhaustive (though
terse) reference, I highly recommend Modi's [[https://ox-hugo.scripter.co/test/][test site]] and [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org][post source]] org file,
which contain demonstrations and tests for all of ox-hugo's features.

After issuing the Emacs command ~M-x package-install RET ox-hugo RET~, you'll
need to ~require~ it. You can do this by running ~M-: (require 'ox-hugo)~, but
you'll want to add it to your configuration as explained [[https://ox-hugo.scripter.co/doc/usage/][here]]. Once this is
done, using ox-hugo is just a matter of making an org file and writing
content. Org's format is very straightforward, and is designed to make sense to
the reader even if they're unfamiliar with the formal syntax. For instance,
#+begin_src org
,* My food
| Where's My Food? | Fridge | Counter | Mouth | Total          |
| Oranges          |      1 |       3 |     0 | :=vsum($2..$4) |
| Marshmallows     |      0 |     100 |    20 | :=vsum($2..$4) |
| Brussel Sprouts  |     32 |       4 |     0 | :=vsum($2..$4) |
#+end_src
Produces a dynamic spreadsheet table in org-mode that exports to HTML like this:
**** My food
| Where's My Food? | Fridge | Counter | Mouth | Total |
| Oranges          |      1 |       3 |     0 |     4 |
| Marshmallows     |      0 |     100 |    20 |   120 |
| Brussel Sprouts  |     32 |       4 |     0 |    36 |
#+TBLFM: @2$5=vsum($2..$4)::@3$5=vsum($2..$4)::@4$5=vsum($2..$4)

If you're already familiar with org-mode, the benefits are obvious and creating
content is fairly trivial. Org-mode is, however, a complex and expansive program
with many features, and its learning curve can appear daunting at first glance.
Using ox-hugo is a great way to learn the format, since it gives the author a
command-center view of their entire content hierarchy, much like a traditional
database, but in a flat format that's much easier to read and understand. Org
features present themselves naturally, and the author can easily visualize the
correspondence between the org format and the output on their webpage.

Just take a look at the [[https://www.kengrimes.com/gitweb/?p=kengrimes.com/content.git;a=blob_plain;f=content.org;hb=HEAD][org file]] for this webpage. Search for "ox-hugo is super
cool!" and you should find this very paragraph.

Eventually you'll want to [[https://orgmode.org/manual/][read the manual]], though. You may access it in Emacs
with ~M-x org-info~.

*** Making a New Blog
Compared to a generic org file, the only important "extra" data that ox-hugo
needs to properly export data is a ~:PROPERTIES: ... :END:~ block with
definitions used for Hugo's [[https://gohugo.io/content-management/front-matter/][front matter]] (used for associating a title, header,
or other custom data with the page it generates). ~:PROPERTIES:~ blocks are
common in org for defining arbitrary metadata about sections, and can be used in
many such ways. Providing an ~:EXPORT_FILE_NAME:~ definition signals to ox-hugo
that this heading is available for export, and that it should be exported to a
markdown file with the name provided.  For example, the ~:PROPERTIES:~ block of
the page you're currently reading looks like this:
#+begin_src org
:PROPERTIES:
:EXPORT_FILE_NAME: ox-hugo
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
:END:
#+end_src
The ~:caption~ and ~:header~ variables are optional definitions allowed by the
Speedy theme of this website, but the filename is the only required property for
ox-hugo. So, as a minimal example, here's what a new blog might look like in its
entirety:
#+begin_src org -n
#+hugo_base_dir: .
,* Home
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:END:
This is the home of my blog!
,** I have herpes
:PROPERTIES:
:EXPORT_FILE_NAME: herpes
:END:
Someone gave me herpes! Oh no!
#+end_src
The org file can be placed in any directory so long as ~HUGO_BASE_DIR~ correctly
identifies the Hugo project's root directory. This path definition is required
for any valid ox-hugo file, and in the example above uses ~.~ as the base
directory, which assumes that the file will be placed in the hugo project's base
directory. If you saved this file as hugotest.org, exported it with org's
exporter ~C-c C-e~ and selected the Hugo output ~H~ and the All Subtrees To
Files option ~A~, you'd wind up with the following files in your directory:
#+begin_src
.
├── content
│   ├── _index.md
│   └── herpes.md
└── hugotest.org
#+end_src
Most sites will be more than a blog, though, and will want multiple sections. In
fact, many sites are made up of nothing but a slew of sections that users
navigate between with some built-in menu. So a more functional minimal example
would be the following:
#+begin_src org -n
#+hugo_base_dir: .
,* My Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
,* My Blog
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
,** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
,** I have herpes
:PROPERTIES:
:EXPORT_FILE_NAME: herpes
:END:
Someone gave me herpes! Oh no!
#+end_src
Which yields the following:
#+begin_src
.
├── content
│   ├── _index.md
│   └── posts
│       ├── herpes.md
│       └── _index.md
└── hugotest.org
#+end_src
As you might expect, this structure adheres to the Hugo [[https://gohugo.io/content-management/organization/][content management]]
scheme. Additionally, the index files have been marked with menu metadata, which
allows Hugo themes to automatically generate navigation menus from the markdown
files. Hereafter, making new blog posts is as simple as adding new sub-headings
under the "My Blog" heading, and exporting. As you can see, this is suitable for
defining the hierarchical structure of any general website, not just
blogs. Org-mode and Hugo just make creating new pages so simple and
well-structured that providing content is all that's required for a new page,
blog entry, or entirely new site section. If you can blog with ox-hugo, you can
deftly deploy any manner of web content, or even develop entire websites as
naturally as you make blog posts. Any tool that can turn blogging and web
development into the same task is quite an achievement!

Of course, themes to style this content are another can of worms entirely, but
it is sufficient for now to mention that Hugo makes [[https://gohugo.io/themes/installing-and-using-themes/][using themes]] as easy as
downloading one and specifying it in Hugo's config file.

One question you may ask is why the blog's homepage is not defined in the *My
Blog* heading. This is a fair question! Property blocks are inherited by
sub-headings, and as of the current version of ox-hugo even ~:EXPORT_HUGO_MENU:~
properties are inherited. This might be intended by the content creator, but
most likely you don't want every single post you make to be in the main menu. So
it makes sense to define all your pages, including the index, as a sub-heading
of the section definition (which specifies which sub-directory content will
output to).

To illustrate, let's assume you want to extend the previous site definition with
a section about fishsticks.
#+begin_src org -n 24
,* Fishsticks
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
:EXPORT_FILE_NAME: _index
:END:
This section devoted to Orson Wells, R.I.P.
,** Van De Camps
:PROPERTIES:
:EXPORT_FILE_NAME: van-de-camps
:END:
If this is fish, I'll be a monkey's uncle.
,** Gortons
:PROPERTIES:
:EXPORT_FILE_NAME: gortons
:END:
I think these gave me the herpes.
#+end_src
In this example, we've defined the main homepage of the section inside the
tier-1 heading for Fishsticks. This is valid, and produces the expected file output:
#+begin_src
.
├── content
│   ├── fishsticks
│   │   ├── gortons.md
│   │   ├── _index.md
│   │   └── van-de-camps.md
│   ├── _index.md
│   └── posts
│       ├── herpes.md
│       └── _index.md
└── hugotest.org
#+end_src
But on inspection of the gortons.md file, we find the anomoly mentioned above:
#+begin_src markdown -n
---
title: "Gortons"
author: ["Ken Grimes"]
draft: false
menu:
  main:
    weight: 2002
    identifier: "gortons"
---

I think these gave me the herpes.
#+end_src
Uh oh! Not only did these fishsticks give us herpes, they are now part of the
main menu. Tisk tisk. So if you use this workflow, be sure to put your index
pages in subheadings so that the tier-1 heading can be used for "global"
definitions that affect all of the pages.

Another question might be why the index pages are named *_index*. You can use
*index* instead of *_index*, the only difference is whether Hugo treats the
index page as a leaf, or a branch, when [[https://gohugo.io/content-management/page-bundles/][bundling resources]] for Hugo to query
during site generation. This is a relatively new addition to Hugo as of version
0.39, and isn't fully functional or integrated well into ox-hugo, so I simply
don't use it at the moment. I define all indexes as *_index* to make them
branches because, in future versions, packaging files within bundles like this
will provide a more stable way for Hugo themes to reference page- and
section-specific files that accompany the content. Currently, I store all such
files in the static folder, which is copied verbatim to the output directory by
Hugo when the site is built.

*** Hugo Setup
At this point, setting up Hugo and publishing is simple. [[https://gohugo.io/getting-started/installing/][Installing]] Hugo is
pretty straightforward on any Unix-like system with a package manager; it is
available on most distributions at this point. Windows installation is a bigger
pain in the ass, but you should be used to that if you're still in the
stone-age.

Using ~hugo new site .~ on the command-line will create a new hugo site in the
current directory, but ~hugo~ expects to be creating a new directory with this
command and will complain if it already exists. It also provides the ~--force~
option to allow creating a new site in an extant directory, but this too will
fail if the *content* subdirectory already exists (which ox-hugo will create
when you export).

So you have three choices: 
1. run ~hugo new site /path/to/some-new-dir~ and move your org file to it
2. simply ~rm -Rf content/~ to remove the content directory ox-hugo created,
   then run ~hugo new site --force .~
3. don't even bother with the ~hugo new site~ command, and make a *config.toml*
   file manually.

It's convenient to do this through the ~hugo~ command because it will create
Hugo-specific subdirectories like archetypes, layouts, themes, etcetera, in
addition to populating a basic *config.toml* file. The subdirectories it creates
aren't necessary, but help illustrate Hugo's structure. In any case, you'll want
to wind up with a directory structure something like this (created with option 2
above, extending from previous examples):
#+begin_src
.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── hugotest.org
├── layouts
├── static
└── themes
#+end_src
Exporting with ox-hugo using ~C-c C-e H A~ again will, as expected, fill the
content directory with our content.
#+begin_src
.
├── archetypes
│   └── default.md
├── config.toml
├── content
│   ├── fishsticks
│   │   ├── gortons.md
│   │   ├── _index.md
│   │   └── van-de-camps.md
│   ├── _index.md
│   └── posts
│       ├── herpes.md
│       └── _index.md
├── data
├── hugotest.org
├── layouts
├── static
└── themes
#+end_src
Now, running the command ~hugo~ with no subcommands will invoke the Hugo
generator on the current directory, and output finalized content in the
*public/* directory.
#+begin_src
.
├── archetypes
│   └── default.md
├── config.toml
├── content
│   ├── fishsticks
│   │   ├── gortons.md
│   │   ├── _index.md
│   │   └── van-de-camps.md
│   ├── _index.md
│   └── posts
│       ├── herpes.md
│       └── _index.md
├── data
├── hugotest.org
├── layouts
├── public
│   ├── categories
│   │   └── index.xml
│   ├── fishsticks
│   │   └── index.xml
│   ├── index.xml
│   ├── posts
│   │   └── index.xml
│   ├── sitemap.xml
│   └── tags
│       └── index.xml
├── static
└── themes
#+end_src
Hugo, by default, generates xml files that are suitable for RSS feeds. With a
theme installed, Hugo will produce more suitable web content (usually
HTML). You'll notice from this default output however that Hugo creates a
sitemap, and two directories for [[https://gohugo.io/content-management/taxonomies/][taxonomies]] that let you "tag" and "categorize"
content. The taxonomy index pages allow users to browse content by category or
tag. These taxonomies correspond to org-mode tags, and ox-hugo will
automatically associated tagged headings with the tags taxonomy, or the
categories taxonomy if prefixed with an @ symbol. You are free to define your
own taxonomies, and even disable the default "tags" and "categories" taxonomies,
but since org-mode tags directly translate to the default Hugo taxonomies, it
makes sense to just use the default taxonomies for now.

*** Example Hugo Site
As an example, let's add some tags and categories to our *hugotest.org* file:
#+begin_src org -n
#+hugo_base_dir: .
,* My Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
,* My Blog
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
,** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
,** I have herpes   :@inanity:herpes:fear:
:PROPERTIES:
:EXPORT_FILE_NAME: herpes
:END:
Someone gave me herpes! Oh no!
,* Fishsticks
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
:EXPORT_FILE_NAME: _index
:END:
This section devoted to Orson Wells, R.I.P.
,** Van De Camps   :@inanity:
:PROPERTIES:
:EXPORT_FILE_NAME: van-de-camps
:END:
If this is fish, I'll be a monkey's uncle.
,** Gortons        :@inanity:herpes:
:PROPERTIES:
:EXPORT_FILE_NAME: gortons
:END:
I think these gave me the herpes.
#+end_src
Exporting *hugotest.org* with ~C-c C-e H A~ and generate with ~hugo~ will yield
the same file structure as before, but this time we'll see that the categories
and tags directories have sections for our newly added tags.
#+begin_src
.
├── archetypes
│   └── default.md
├── config.toml
├── content
│   ├── fishsticks
│   │   ├── gortons.md
│   │   ├── _index.md
│   │   └── van-de-camps.md
│   └── posts
│       └── herpes.md
├── data
├── hugotest.org
├── layouts
├── public
│   ├── categories
│   │   ├── inanity
│   │   │   └── index.xml
│   │   └── index.xml
│   ├── fishsticks
│   │   └── index.xml
│   ├── index.xml
│   ├── posts
│   │   └── index.xml
│   ├── sitemap.xml
│   └── tags
│       ├── fear
│       │   └── index.xml
│       ├── herpes
│       │   └── index.xml
│       └── index.xml
├── static
└── themes
#+end_src
The index pages of taxonomies provide a list of all available taxonomies of that
type, with links to lists that show content associated with that taxonomy. For
instance, public/tags/index.xml looks like this:
#+begin_src xml -n
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Tags on My New Hugo Site</title>
    <link>http://example.org/tags/</link>
    <description>Recent content in Tags on My New Hugo Site</description>
    <generator>Hugo -- gohugo.io</generator>
    <language>en-us</language>
    
        <atom:link href="http://example.org/tags/index.xml" rel="self" type="application/rss+xml" />
    
    
    <item>
      <title>Fear</title>
      <link>http://example.org/tags/fear/</link>
      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
      
      <guid>http://example.org/tags/fear/</guid>
      <description></description>
    </item>
    
    <item>
      <title>Herpes</title>
      <link>http://example.org/tags/herpes/</link>
      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
      
      <guid>http://example.org/tags/herpes/</guid>
      <description></description>
    </item>
    
  </channel>
</rss>
#+end_src
And public/tags/fear/index.xml looks like this:
#+begin_src xml -n
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Fear on My New Hugo Site</title>
    <link>http://example.org/tags/fear/</link>
    <description>Recent content in Fear on My New Hugo Site</description>
    <generator>Hugo -- gohugo.io</generator>
    <language>en-us</language>
    
        <atom:link href="http://example.org/tags/fear/index.xml" rel="self" type="application/rss+xml" />
    
    
    <item>
      <title>I have herpes</title>
      <link>http://example.org/posts/herpes/</link>
      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
      
      <guid>http://example.org/posts/herpes/</guid>
      <description>Someone gave me herpes! Oh no!</description>
    </item>
    
    <item>
      <title>Van De Camps</title>
      <link>http://example.org/fishsticks/van-de-camps/</link>
      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
      
      <guid>http://example.org/fishsticks/van-de-camps/</guid>
      <description>If this is fish, I&amp;rsquo;ll be a monkey&amp;rsquo;s uncle.</description>
    </item>
    
  </channel>
</rss>
#+end_src
This allows themes to easily build navigation pages for browsing or querying
taxonomies. Files like these are often useful to output as JSON (done by the
theme) to allow Javascript-driven dynamic search features, but a simpler scheme
can output HTML pages to browse taxonomies just as you would posts in a section
(i.e. org-mode heading).

**** Theming
The last thing to do here is to download or create a theme for Hugo. As
mentioned before, installing a theme is very simple. This blog uses a custom
theme named Speedy that I have been developing to help myself learn Hugo's
internals, but for this example I'll be using Kaushal Modi's [[https://github.com/kaushalmodi/hugo-bare-min-theme][bare-min theme]]. The
bare-min theme is the best starting place out there for making new themes, and
outputs basic HTML pages without any need to mess with CSS or JS. It also
provides easy debugging facilities and search features.

We'll just install it and generate the site again. You can download the theme
from its github page and extract it to the themes folder, or much more easily
use git to clone it to your themes directory.
~git clone https://github.com/kaushalmodi/hugo-bare-min-theme.git themes/bare-min~
Then open up your *config.toml* file, and add the theme.
#+begin_src toml -n
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
# Adding a theme:
theme = "bare-min"
#+end_src
Be sure that the theme's name matches the theme directory's name in the themes/
directory of your project base directory. (e.g. themes/bare-min here).

That's it for installing the theme. Just run ~hugo~ again, and behold your output:
#+begin_src
.
└── public
    ├── categories
    │   ├── inanity
    │   │   ├── index.html
    │   │   └── index.xml
    │   ├── index.html
    │   └── index.xml
    ├── css
    │   └── github_chroma.css
    ├── fishsticks
    │   ├── gortons
    │   │   └── index.html
    │   ├── index.html
    │   ├── index.xml
    │   └── van-de-camps
    │       └── index.html
    ├── index.html
    ├── index.xml
    ├── js
    │   └── search.js
    ├── page
    │   └── 1
    │       └── index.html
    ├── posts
    │   ├── herpes
    │   │   └── index.html
    │   ├── index.html
    │   └── index.xml
    ├── sitemap.xml
    └── tags
        ├── fear
        │   ├── index.html
        │   └── index.xml
        ├── herpes
        │   ├── index.html
        │   └── index.xml
        ├── index.html
        └── index.xml
#+end_src
The bare-min theme outputs HTML, provides CSS for doing chroma-based syntax
highlighting (in case you include code blocks), and inline styles for basic
page formatting. Generated pages also have a lot of useful debugging information.

You can now serve the *public/* directory over an HTTP server. Hugo is packaged
with an internal [[https://gohugo.io/commands/hugo_server/][HTTP server]] to help with testing, which is quite convenient
because it can automatically refresh whenever content in its content directory
is updated (so when you export from ox-hugo, you don't have to run ~hugo~
again). To use it, simply run ~hugo server~ and point your browser at
http://localhost:1313 (1313 is the default ~--port~ argument for ~hugo server~).

Eventually you'll want to move on to other themes, or develop your own, but at
this point you've got a fully functional blog publishing workflow from start to
finish.

*** Attaching Files, Capturing Information & Automation
Once you have a basic site structured in your org file, you're ready to start
throwing information in it. It is of course sufficient to open the org file and
edit it, but most org-mode users prefer to automate /everything/, and being able
to use org's capture feature to instantly populate new blog posts is extremely
convenient.

The [[https://ox-hugo.scripter.co/][ox-hugo documentation]] provides succinct explanations on how to do this,
including elisp snippets for [[https://ox-hugo.scripter.co/doc/org-capture-setup/][capture setup]], [[https://ox-hugo.scripter.co/doc/images-in-content/][image linking]], and [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][automating
exports]] when you save your org file (so no more need to ~C-c C-e H A~ every
time, just save the file as usual with ~C-x C-s~).
** DONE I did a blog                                   :blog:org:emacs:hugo:
CLOSED: [2018-04-06 Fri 18:29]
:PROPERTIES:
:EXPORT_FILE_NAME: ox-hugo
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
:END:
ox-hugo is an [[http://en.wikipedia.org/wiki/Emacs][Emacs]] package for [[http://en.wikipedia.org/wiki/org-mode][org-mode]] that produces input for the static
content generator [[https://gohugo.io/][Hugo]], which I use for this website. Today I integrated its
expectations about file structure into the Speedy theme for this blog, allowing
me to keep all blog contents in a single org-mode file and export [[http://en.wikipedia.org/wiki/markdown][markdown]]
content for Hugo's excellent [[https://github.com/russross/blackfriday][blackfriday markdown parser]] (a markdown format with
many added features). Hugo does support limited parsing of org files internally,
but org-mode features like inline spreadsheets and system communication are
beyond the scope of most external tools, so org-mode is best used as an
exporter. As an Emacs user, this allows me to instantly capture interesting
information I come across and publish it within seconds. Now I have no excuses!

** DONE Another topic
CLOSED: [2018-04-01 Sun 18:29]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-1
:END:
This is just another topic, don't worry about it.

** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-2
:END:
This is just another topic, don't worry about it.

** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-3
:END:
This is just another topic, don't worry about it.

** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-4
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-5
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-6
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-7
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-8
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-9
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-10
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-11
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-12
:END:
This is just another topic, don't worry about it.
** DONE Another topic :@test:test:
CLOSED: [2018-04-01 Sun 18:30]
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
:EXPORT_FILE_NAME: another-topic-13
:END:
This is just another topic, don't worry about it.
* Forth
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: forth
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading "Highly Factored Code"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/forth.png
:END:
This is where I post my watForth programs.

* Code Repositories
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main" :title Git
:EXPORT_HUGO_SECTION: git
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/git.png
:END:
<iframe height="600px" width="100%" frameborder="0" scrolling="no" src="/gitweb" onload="resizeIFrame(this)">
  <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
  <a href="https://git.kengrimes.com">https://git.kengrimes.com</a>
</iframe>

* About
:PROPERTIES:
:EXPORT_HUGO_SECTION: about
:EXPORT_HUGO_MENU: :menu "main" :title About
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading '("Ken Grimes" "Computer Scientist" "At Large")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/home.png
:EXPORT_FILE_NAME: _index
:END:
Hi! I'm Ken, a 34-year-old computer scientist currently living in Irvine,
California. This is a website I've constructed for the purpose of developing
web-facing software. I will probably blog with it once development is
complete. In the mean time, if you're curious, this is my [[file:static/cv.pdf][curriculum vitae]]

* COMMENT
** Why Emacs/Org
#+attr_html: :class center
[[file:static/img/emacs-logo.png]]

Org-mode is sometimes seen as an esoteric tool for an already esoteric IDE
(Emacs), but to me it is the natural evolution of decades of careful work to do
things the right way. When a software developer, after much study and
deliberation, finally comes to the realization that we are all fundamentally
programming one enormous system, it suddenly becomes important to understand the
fundamentals of computing and peel away the abstractions we live in like layers
of an onion. At the core, computer scientists will find that Names and Naming
are the universal "API" with which we all work. As such, being able to work with
raw words is invaluable to any serious student of computing. This is why the
much ignored medium of plain text is, somewhat paradoxically, the most powerful
of all tools for us. Indeed, Names and Naming have a long history of association
with power, and it seems most sciences that recognize this relationship are
themselves deemed "esoteric".

It's easy to get washed away in the torrent of new-age development tools that
add layer after layer of abstraction and "boilerplate" automation. These days,
it's trivial with tools like [[http://en.wikipedia.org/wiki/Webstorm][Webstorm]], [[http://en.wikipedia.org/wiki/Xcode][Xcode]], or [[http://en.wikipedia.org/wiki/Visual_Studio][Visual Studio]] to start
producing working code in minutes, regardless of experience or knowledge. It is
much harder, and in many environments impossible, to really understand what you
are doing. Most new programming languages, freed from developing sophisticated
compiler backends by new tools like [[http://en.wikipedia.org/wiki/llvm][llvm]], have instead focused on providing
tooling for automatically formatting, linting, bootstrapping, and even building
code to make this process even easier. These tools enforce an opinionated
workflow that, although good, are generally not portable to other languages or
toolchains. Tools like these are medicine for remedying the enormous time sink
and productivity loss suffered during configuration and setup. But like many
medicines, they can lead to addiction, and dependency on the vendor who provided
it. Eventually, being constrained to a single environment will cause essential
skills to atrophy, or never develop in the first place, making the victim a
slave to both their vendor and the drug.

I'm no tea-totaller, though. These tools are part of my regular workflow, and I
advocate using them when it is appropriate. The primary goal in developing
skills is to unapolagetically empower yourself by /any/ means necessary. It's a
balancing act, in the end, whether the drugs are hurting or hindering. Just be
conscious of the debilitating effects of what the buzz-slingers call "vendor
lock-in" these days. Study the topic, read the documentation, and understand
everything that is going to happen when you invoke any command. This applies to
tooling as well as library functions and even language statements - even
english. Admittedly, that's a steep mountain to climb for most people, and
crippling when wading through spaghetti-code, but you'll come to understand that
the most powerful words are the ones you /didn't have to say/ in the first
place.

Emacs and Org-mode take these philosophies to heart in different, and incomplete
ways. Org-mode is a plain text formatting system, not so dissimilar to markdown,
bbcode, or even twitter's automatic recognition of hashtags and @s. It's a
formatting engine that recognizes certain plain-text patterns as having special
meanings, geared eponymously towards organization of data. For instance, 



Emacs and Org-mode take these philosophies to heart. Partly because Emacs has
been around in some form since the early 70s, While I extend this philosophy to
my coding style, it's also integral

** Blackfriday Markdown: Syntax
#+begin_export md
<ul id="ProjectSubmenu">
    <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
    <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
    <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
    <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
    <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
</ul>


 *   [Overview](#overview)
    *   [Philosophy](#philosophy)
    *   [Inline HTML](#html)
    *   [Automatic Escaping for Special Characters](#autoescape)
 *   [Block Elements](#block)
    *   [Paragraphs and Line Breaks](#p)
    *   [Headers](#header)
    *   [Blockquotes](#blockquote)
    *   [Lists](#list)
    *   [Code Blocks](#precode)
    *   [Horizontal Rules](#hr)
 *   [Span Elements](#span)
    *   [Links](#link)
    *   [Emphasis](#em)
    *   [Code](#code)
    *   [Images](#img)
 *   [Miscellaneous](#misc)
    *   [Backslash Escapes](#backslash)
    *   [Automatic Links](#autolink)


**Note:** This document is itself written using Markdown; you
can [see the source for it by adding '.text' to the URL][src].

  [src]: https://raw.githubusercontent.com/russross/blackfriday/master/testdata/Markdown%20Documentation%20-%20Syntax.text

 * * *

<h2 id="overview">Overview</h2>

<h3 id="philosophy">Philosophy</h3>

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted
document should be publishable as-is, as plain text, without looking
like it's been marked up with tags or formatting instructions. While
Markdown's syntax has been influenced by several existing text-to-HTML
filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
[Grutatext] [5], and [EtText] [6] -- the single biggest source of
inspiration for Markdown's syntax is the format of plain text email.

  [1]: http://docutils.sourceforge.net/mirror/setext.html
  [2]: http://www.aaronsw.com/2002/atx/
  [3]: http://textism.com/tools/textile/
  [4]: http://docutils.sourceforge.net/rst.html
  [5]: http://www.triptico.com/software/grutatxt.html
  [6]: http://ettext.taint.org/doc/

To this end, Markdown's syntax is comprised entirely of punctuation
characters, which punctuation characters have been carefully chosen so
as to look like what they mean. E.g., asterisks around a word actually
look like \*emphasis\*. Markdown lists look like, well, lists. Even
blockquotes look like quoted passages of text, assuming you've ever
used email.



<h3 id="html">Inline HTML</h3>

Markdown's syntax is intended for one purpose: to be used as a
format for *writing* for the web.

Markdown is not a replacement for HTML, or even close to it. Its
syntax is very small, corresponding only to a very small subset of
HTML tags. The idea is *not* to create a syntax that makes it easier
to insert HTML tags. In my opinion, HTML tags are already easy to
insert. The idea for Markdown is to make it easy to read, write, and
edit prose. HTML is a *publishing* format; Markdown is a *writing*
format. Thus, Markdown's formatting syntax only addresses issues that
can be conveyed in plain text.

For any markup that is not covered by Markdown's syntax, you simply
use HTML itself. There's no need to preface it or delimit it to
indicate that you're switching from Markdown to HTML; you just use
the tags.

The only restrictions are that block-level HTML elements -- e.g. `<div>`,
`<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
content by blank lines, and the start and end tags of the block should
not be indented with tabs or spaces. Markdown is smart enough not
to add extra (unwanted) `<p>` tags around HTML block-level tags.

For example, to add an HTML table to a Markdown article:

    This is a regular paragraph.

    <table>
        <tr>
            <td>Foo</td>
        </tr>
    </table>

    This is another regular paragraph.

Note that Markdown formatting syntax is not processed within block-level
HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
HTML block.

Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
used anywhere in a Markdown paragraph, list item, or header. If you
want, you can even use HTML tags instead of Markdown formatting; e.g. if
you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
link or image syntax, go right ahead.

Unlike block-level HTML tags, Markdown syntax *is* processed within
span-level tags.


<h3 id="autoescape">Automatic Escaping for Special Characters</h3>

In HTML, there are two characters that demand special treatment: `<`
and `&`. Left angle brackets are used to start tags; ampersands are
used to denote HTML entities. If you want to use them as literal
characters, you must escape them as entities, e.g. `&lt;`, and
`&amp;`.

Ampersands in particular are bedeviling for web writers. If you want to
write about 'AT&T', you need to write '`AT&amp;T`'. You even need to
escape ampersands within URLs. Thus, if you want to link to:

    http://images.google.com/images?num=30&q=larry+bird

you need to encode the URL as:

    http://images.google.com/images?num=30&amp;q=larry+bird

in your anchor tag `href` attribute. Needless to say, this is easy to
forget, and is probably the single most common source of HTML validation
errors in otherwise well-marked-up web sites.

Markdown allows you to use these characters naturally, taking care of
all the necessary escaping for you. If you use an ampersand as part of
an HTML entity, it remains unchanged; otherwise it will be translated
into `&amp;`.

So, if you want to include a copyright symbol in your article, you can write:

    &copy;

and Markdown will leave it alone. But if you write:

    AT&T

Markdown will translate it to:

    AT&amp;T

Similarly, because Markdown supports [inline HTML](#html), if you use
angle brackets as delimiters for HTML tags, Markdown will treat them as
such. But if you write:

    4 < 5

Markdown will translate it to:

    4 &lt; 5

However, inside Markdown code spans and blocks, angle brackets and
ampersands are *always* encoded automatically. This makes it easy to use
Markdown to write about HTML code. (As opposed to raw HTML, which is a
terrible format for writing about HTML syntax, because every single `<`
and `&` in your example code needs to be escaped.)


 * * *


<h2 id="block">Block Elements</h2>


<h3 id="p">Paragraphs and Line Breaks</h3>

A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like a
blank line -- a line containing nothing but spaces or tabs is considered
blank.) Normal paragraphs should not be intended with spaces or tabs.

The implication of the "one or more consecutive lines of text" rule is
that Markdown supports "hard-wrapped" text paragraphs. This differs
significantly from most other text-to-HTML formatters (including Movable
Type's "Convert Line Breaks" option) which translate every line break
character in a paragraph into a `<br />` tag.

When you *do* want to insert a `<br />` break tag using Markdown, you
end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a `<br />`, but a simplistic
"every line break is a `<br />`" rule wouldn't work for Markdown.
Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
work best -- and look better -- when you format them with hard breaks.

  [bq]: #blockquote
  [l]:  #list



<h3 id="header">Headers</h3>

Markdown supports two styles of headers, [Setext] [1] and [atx] [2].

Setext-style headers are "underlined" using equal signs (for first-level
headers) and dashes (for second-level headers). For example:

    This is an H1
    =============

    This is an H2
    -------------

Any number of underlining `=`'s or `-`'s will work.

Atx-style headers use 1-6 hash characters at the start of the line,
corresponding to header levels 1-6. For example:

    # This is an H1

    ## This is an H2

    ###### This is an H6

Optionally, you may "close" atx-style headers. This is purely
cosmetic -- you can use this if you think it looks better. The
closing hashes don't even need to match the number of hashes
used to open the header. (The number of opening hashes
determines the header level.) :

    # This is an H1 #

    ## This is an H2 ##

    ### This is an H3 ######


<h3 id="blockquote">Blockquotes</h3>

Markdown uses email-style `>` characters for blockquoting. If you're
familiar with quoting passages of text in an email message, then you
know how to create a blockquote in Markdown. It looks best if you hard
wrap the text and put a `>` before every line:

    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
    > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
    > 
    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
    > id sem consectetuer libero luctus adipiscing.

Markdown allows you to be lazy and only put the `>` before the first
line of a hard-wrapped paragraph:

    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
    consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
    id sem consectetuer libero luctus adipiscing.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
adding additional levels of `>`:

    > This is the first level of quoting.
    >
    > > This is nested blockquote.
    >
    > Back to the first level.

Blockquotes can contain other Markdown elements, including headers, lists,
and code blocks:

        > ## This is a header.
        > 
        > 1.   This is the first list item.
        > 2.   This is the second list item.
        > 
        > Here's some example code:
        > 
        >     return shell_exec("echo $input | $markdown_script");

Any decent text editor should make email-style quoting easy. For
example, with BBEdit, you can make a selection and choose Increase
Quote Level from the Text menu.


<h3 id="list">Lists</h3>

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and hyphens -- interchangably
-- as list markers:

    *   Red
    *   Green
    *   Blue

is equivalent to:

    +   Red
    +   Green
    +   Blue

and:

    -   Red
    -   Green
    -   Blue

Ordered lists use numbers followed by periods:

    1.  Bird
    2.  McHale
    3.  Parish

It's important to note that the actual numbers you use to mark the
list have no effect on the HTML output Markdown produces. The HTML
Markdown produces from the above list is:

    <ol>
    <li>Bird</li>
    <li>McHale</li>
    <li>Parish</li>
    </ol>

If you instead wrote the list in Markdown like this:

    1.  Bird
    1.  McHale
    1.  Parish

or even:

    3. Bird
    1. McHale
    8. Parish

you'd get the exact same HTML output. The point is, if you want to,
you can use ordinal numbers in your ordered Markdown lists, so that
the numbers in your source match the numbers in your published HTML.
But if you want to be lazy, you don't have to.

If you do use lazy list numbering, however, you should still start the
list with the number 1. At some point in the future, Markdown may support
starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by
up to three spaces. List markers must be followed by one or more spaces
or a tab.

To make lists look nice, you can wrap items with hanging indents:

    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
        Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
        viverra nec, fringilla in, laoreet vitae, risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
        Suspendisse id sem consectetuer libero luctus adipiscing.

But if you want to be lazy, you don't have to:

    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

If list items are separated by blank lines, Markdown will wrap the
items in `<p>` tags in the HTML output. For example, this input:

    *   Bird
    *   Magic

will turn into:

    <ul>
    <li>Bird</li>
    <li>Magic</li>
    </ul>

But this:

    *   Bird

    *   Magic

will turn into:

    <ul>
    <li><p>Bird</p></li>
    <li><p>Magic</p></li>
    </ul>

List items may consist of multiple paragraphs. Each subsequent
paragraph in a list item must be intended by either 4 spaces
or one tab:

    1.  This is a list item with two paragraphs. Lorem ipsum dolor
        sit amet, consectetuer adipiscing elit. Aliquam hendrerit
        mi posuere lectus.

        Vestibulum enim wisi, viverra nec, fringilla in, laoreet
        vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
        sit amet velit.

    2.  Suspendisse id sem consectetuer libero luctus adipiscing.

It looks nice if you indent every line of the subsequent
paragraphs, but here again, Markdown will allow you to be
lazy:

    *   This is a list item with two paragraphs.

        This is the second paragraph in the list item. You're
    only required to indent the first line. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit.

    *   Another item in the same list.

To put a blockquote within a list item, the blockquote's `>`
delimiters need to be indented:

    *   A list item with a blockquote:

        > This is a blockquote
        > inside a list item.

To put a code block within a list item, the code block needs
to be indented *twice* -- 8 spaces or two tabs:

    *   A list item with a code block:

            <code goes here>


It's worth noting that it's possible to trigger an ordered list by
accident, by writing something like this:

    1986. What a great season.

In other words, a *number-period-space* sequence at the beginning of a
line. To avoid this, you can backslash-escape the period:

    1986\. What a great season.



<h3 id="precode">Code Blocks</h3>

Pre-formatted code blocks are used for writing about programming or
markup source code. Rather than forming normal paragraphs, the lines
of a code block are interpreted literally. Markdown wraps a code block
in both `<pre>` and `<code>` tags.

To produce a code block in Markdown, simply indent every line of the
block by at least 4 spaces or 1 tab. For example, given this input:

    This is a normal paragraph:

        This is a code block.

Markdown will generate:

    <p>This is a normal paragraph:</p>

    <pre><code>This is a code block.
    </code></pre>

One level of indentation -- 4 spaces or 1 tab -- is removed from each
line of the code block. For example, this:

    Here is an example of AppleScript:

        tell application "Foo"
            beep
        end tell

will turn into:

    <p>Here is an example of AppleScript:</p>

    <pre><code>tell application "Foo"
        beep
    end tell
    </code></pre>

A code block continues until it reaches a line that is not indented
(or the end of the article).

Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
are automatically converted into HTML entities. This makes it very
easy to include example HTML source code using Markdown -- just paste
it and indent it, and Markdown will handle the hassle of encoding the
ampersands and angle brackets. For example, this:

        <div class="footer">
            &copy; 2004 Foo Corporation
        </div>

will turn into:

    <pre><code>&lt;div class="footer"&gt;
        &amp;copy; 2004 Foo Corporation
    &lt;/div&gt;
    </code></pre>

Regular Markdown syntax is not processed within code blocks. E.g.,
asterisks are just literal asterisks within a code block. This means
it's also easy to use Markdown to write about Markdown's own syntax.



<h3 id="hr">Horizontal Rules</h3>

You can produce a horizontal rule tag (`<hr />`) by placing three or
more hyphens, asterisks, or underscores on a line by themselves. If you
wish, you may use spaces between the hyphens or asterisks. Each of the
following lines will produce a horizontal rule:

    * * *

    ***

    *****
        
    - - -

    ---------------------------------------

        _ _ _


 * * *

<h2 id="span">Span Elements</h2>

<h3 id="link">Links</h3>

Markdown supports two style of links: *inline* and *reference*.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately
after the link text's closing square bracket. Inside the parentheses,
put the URL where you want the link to point, along with an *optional*
title for the link, surrounded in quotes. For example:

    This is [an example](http://example.com/ "Title") inline link.

    [This link](http://example.net/) has no title attribute.

Will produce:

    <p>This is <a href="http://example.com/" title="Title">
    an example</a> inline link.</p>

    <p><a href="http://example.net/">This link</a> has no
    title attribute.</p>

If you're referring to a local resource on the same server, you can
use relative paths:

    See my [About](/about/) page for details.

Reference-style links use a second set of square brackets, inside
which you place a label of your choosing to identify the link:

    This is [an example][id] reference-style link.

You can optionally use a space to separate the sets of brackets:

    This is [an example] [id] reference-style link.

Then, anywhere in the document, you define your link label like this,
on a line by itself:

    [id]: http://example.com/  "Optional Title Here"

That is:

 *   Square brackets containing the link identifier (optionally
    indented from the left margin using up to three spaces);
 *   followed by a colon;
 *   followed by one or more spaces (or tabs);
 *   followed by the URL for the link;
 *   optionally followed by a title attribute for the link, enclosed
    in double or single quotes.

The link URL may, optionally, be surrounded by angle brackets:

    [id]: <http://example.com/>  "Optional Title Here"

You can put the title attribute on the next line and use extra spaces
or tabs for padding, which tends to look better with longer URLs:

    [id]: http://example.com/longish/path/to/resource/here
        "Optional Title Here"

Link definitions are only used for creating links during Markdown
processing, and are stripped from your document in the HTML output.

Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:

        [link text][a]
        [link text][A]

are equivalent.

The *implicit link name* shortcut allows you to omit the name of the
link, in which case the link text itself is used as the name.
Just use an empty set of square brackets -- e.g., to link the word
"Google" to the google.com web site, you could simply write:

        [Google][]

And then define the link:

        [Google]: http://google.com/

Because link names may contain spaces, this shortcut even works for
multiple words in the link text:

        Visit [Daring Fireball][] for more information.

And then define the link:
        
        [Daring Fireball]: http://daringfireball.net/

Link definitions can be placed anywhere in your Markdown document. I
tend to put them immediately after each paragraph in which they're
used, but if you want, you can put them all at the end of your
document, sort of like footnotes.

Here's an example of reference links in action:

    I get 10 times more traffic from [Google] [1] than from
    [Yahoo] [2] or [MSN] [3].

      [1]: http://google.com/        "Google"
      [2]: http://search.yahoo.com/  "Yahoo Search"
      [3]: http://search.msn.com/    "MSN Search"

Using the implicit link name shortcut, you could instead write:

    I get 10 times more traffic from [Google][] than from
    [Yahoo][] or [MSN][].

      [google]: http://google.com/        "Google"
      [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
      [msn]:    http://search.msn.com/    "MSN Search"

Both of the above examples will produce the following HTML output:

    <p>I get 10 times more traffic from <a href="http://google.com/"
    title="Google">Google</a> than from
    <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
    or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

For comparison, here is the same paragraph written using
Markdown's inline link style:

    I get 10 times more traffic from [Google](http://google.com/ "Google")
    than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
    [MSN](http://search.msn.com/ "MSN Search").

The point of reference-style links is not that they're easier to
write. The point is that with reference-style links, your document
source is vastly more readable. Compare the above examples: using
reference-style links, the paragraph itself is only 81 characters
long; with inline-style links, it's 176 characters; and as raw HTML,
it's 234 characters. In the raw HTML, there's more markup than there
is text.

With Markdown's reference-style links, a source document much more
closely resembles the final output, as rendered in a browser. By
allowing you to move the markup-related metadata out of the paragraph,
you can add links without interrupting the narrative flow of your
prose.


<h3 id="em">Emphasis</h3>

Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
emphasis. Text wrapped with one `*` or `_` will be wrapped with an
HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
`<strong>` tag. E.g., this input:

    *single asterisks*

    _single underscores_

    **double asterisks**

    __double underscores__

will produce:

    <em>single asterisks</em>

    <em>single underscores</em>

    <strong>double asterisks</strong>

    <strong>double underscores</strong>

You can use whichever style you prefer; the lone restriction is that
the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

    un*fucking*believable

But if you surround an `*` or `_` with spaces, it'll be treated as a
literal asterisk or underscore.

To produce a literal asterisk or underscore at a position where it
would otherwise be used as an emphasis delimiter, you can backslash
escape it:

    \*this text is surrounded by literal asterisks\*



<h3 id="code">Code</h3>

To indicate a span of code, wrap it with backtick quotes (`` ` ``).
Unlike a pre-formatted code block, a code span indicates code within a
normal paragraph. For example:

    Use the `printf()` function.

will produce:

    <p>Use the <code>printf()</code> function.</p>

To include a literal backtick character within a code span, you can use
multiple backticks as the opening and closing delimiters:

    ``There is a literal backtick (`) here.``

which will produce this:

    <p><code>There is a literal backtick (`) here.</code></p>

The backtick delimiters surrounding a code span may include spaces --
one after the opening, one before the closing. This allows you to place
literal backtick characters at the beginning or end of a code span:

        A single backtick in a code span: `` ` ``
        
        A backtick-delimited string in a code span: `` `foo` ``

will produce:

        <p>A single backtick in a code span: <code>`</code></p>
        
        <p>A backtick-delimited string in a code span: <code>`foo`</code></p>

With a code span, ampersands and angle brackets are encoded as HTML
entities automatically, which makes it easy to include example HTML
tags. Markdown will turn this:

    Please don't use any `<blink>` tags.

into:

    <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>

You can write this:

    `&#8212;` is the decimal-encoded equivalent of `&mdash;`.

to produce:

    <p><code>&amp;#8212;</code> is the decimal-encoded
    equivalent of <code>&amp;mdash;</code>.</p>



<h3 id="img">Images</h3>

Admittedly, it's fairly difficult to devise a "natural" syntax for
placing images into a plain text document format.

Markdown uses an image syntax that is intended to resemble the syntax
for links, allowing for two styles: *inline* and *reference*.

Inline image syntax looks like this:

    ![Alt text](/path/to/img.jpg)

    ![Alt text](/path/to/img.jpg "Optional title")

That is:

 *   An exclamation mark: `!`;
 *   followed by a set of square brackets, containing the `alt`
    attribute text for the image;
 *   followed by a set of parentheses, containing the URL or path to
    the image, and an optional `title` attribute enclosed in double
    or single quotes.

Reference-style image syntax looks like this:

    ![Alt text][id]

Where "id" is the name of a defined image reference. Image references
are defined using syntax identical to link references:

    [id]: url/to/image  "Optional title attribute"

As of this writing, Markdown has no syntax for specifying the
dimensions of an image; if this is important to you, you can simply
use regular HTML `<img>` tags.


 * * *


<h2 id="misc">Miscellaneous</h2>

<h3 id="autolink">Automatic Links</h3>

Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:

    <http://example.com/>
    
Markdown will turn this into:

    <a href="http://example.com/">http://example.com/</a>

Automatic links for email addresses work similarly, except that
Markdown will also perform a bit of randomized decimal and hex
entity-encoding to help obscure your address from address-harvesting
spambots. For example, Markdown will turn this:

    <address@example.com>

into something like this:

    <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
    &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
    &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
    &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

which will render in a browser as a clickable link to "address@example.com".

(This sort of entity-encoding trick will indeed fool many, if not
most, address-harvesting bots, but it definitely won't fool all of
them. It's better than nothing, but an address published in this way
will probably eventually start receiving spam.)



<h3 id="backslash">Backslash Escapes</h3>

Markdown allows you to use backslash escapes to generate literal
characters which would otherwise have special meaning in Markdown's
formatting syntax. For example, if you wanted to surround a word with
literal asterisks (instead of an HTML `<em>` tag), you can backslashes
before the asterisks, like this:

    \*literal asterisks\*

Markdown provides backslash escapes for the following characters:

    \   backslash
    `   backtick
    *   asterisk
    _   underscore
    {}  curly braces
    []  square brackets
    ()  parentheses
    #   hash mark
        +       plus sign
        -       minus sign (hyphen)
    .   dot
    !   exclamation mark
#+end_export
** OS Wars
The operating system wars are still going, they've just taken on a new form: the
ecosystems of major software development centers like microsoft, facebook,
google, apple, amazon, have just become the new battleground.  All of these
ecosystems are seeking to replace the entire unix operating system stack with
their own internal APIs and code. from writing code in awk/sed/bash to utilize
the OS's commands as an api, to generalizing this in python-esque languages, and
now to new programming frameworks for every language which package endless
libraries that are just sloppy new rewrites of decades-old functionality already
in the GNU environment. the good news is that there's a ton of energy going into
language research, compilers, and there are many new emerging standards as a
result for message sending (alan kay "real objects"), network federation,
package management, build tools, live coding, web technology, execution
platforms, and everything in between. the bad news is that basically all energy
is just going towards building, and rebuilding, and rebuilding application
frameworks. Call them libraries, packages, eggs, utilities, or whatever, they're
all just another incomplete rewrite of tools that have been around and
maintained for over half a century. They're easier to use, which is great, but
that user interface (i.e. language syntax and package management) doesn't need
to be divorced from existing functionality. As far as I can figure, it's just
gouche, or somehow seen as less sophisticated and interesting, if a language
keeps C dependencies after a certain point. Almost all languages start out their
life as C programs, and it's considered a major milestone when the language's
compiler can finally compile itself and become self-hosting. All this proves is
that the language can generate a compiler, though. It's a sloppy metric of
progress. It's another major milestone when the language's libraries no longer
have any C library dependencies (i.e. all commonly used APIs for handling i18n,
unicode, hashtables, etcetera, have been reinvented in the new
language). And perhaps its greatest achievement of all is to remove dependence
on libc - the single most rugged and well-tested system interface on the
planet.

What I'd really like to see is a language that