~vlmutolo/sona

A markup language designed for humans.

1aaca03 fix typo and sentence structure in README

~vlmutolo pushed to ~vlmutolo/sona git

a day ago

516b427 add figure example to README

~vlmutolo pushed to ~vlmutolo/sona git

a day ago

#sona

A new markup language designed to replace Markdown and LaTeX for document authorship.

#Why a new markup langauge?

I wanted to write a book, and instead of doing that, I started writing a markup langauge.

Generally, I was looking for a set of features I couldn't find anywhere else in a complete package.

  • Explicit, semantic markup. This disqualifies Markdown. As much as I love Markdown's syntax for its simplicity, the simplicitly becomes a problem when I'm trying to write long, complex documents with figures, captions, references, etc.
  • "Compile" to different document representations. The two I presently care about most are HTML (also epub) and PDF.

Basically, I want a redesigned-but-similar version of LaTeX that can output HTML as well as PDFs and is easier to customize. I want to go all-in on separation of content and style, and make it easier to specify the style than it is in LaTeX.

#Examples

Because you can't tell people anything, I'll just let the following examples try to speak for themselves. They're not for teaching, but rather for gaining some familiarity with the syntax and the general feeling of the language.

#Novel Text

This is the reason I started writing the langauge in the first place. I wanted it to support me in writing a book. To that end, sona had to be terse and flexible. Terse because endless HTML tags make the source impossible to read fluidly. Flexible because I wanted to be able to write things like shout and have it semantically mean shout in the text.

[meta] {
	[title] Alice's Adventures in Wonderland
	[author] Lewis Carroll
	[date] 2008-06-25
	[edition] THE MILLENNIUM FULCRUM EDITION 3.0
}

Alice was beginning to get very tired of sitting by her sister on the bank,
and of having nothing to do: once or twice she had peeped into the book her
sister was reading, but it had no pictures or conversations in it, "and what 
is the use of a book," thought Alice "without pictures or conversations?"

#Figure with Caption

In undergrad, I majored in physics. This means that I've written one-thousand-too-many lab reports, and that I'm sympathetic to those who need complex figures and captions in their documents. We need to be very flexible in allowing users to add information in this area, which is where sona comes in handy over something simple like Markdown.

[meta] {
	[title] My Amazing Lab Report
	[author] Jack Beanstock
	[date] [s]{today}
}

I've measured the voltage output of the equator. It's seven. Oh no!
Here's a figure explaining why doomsday is upon us.

	[figure]
		[image-path] r# /home/vlmutolo/doomsday-pics/doom.png r#
		[width] 7in
		[flow] false

		[caption] Here's a very long caption. Pretend that it
		gets line-wrapped. We want things like this to be easily
		supported. You can even do arbitrary markup inside it, like
		referencing something previously labeled: [ref]{eq:previous}.

And now we're back to regular document text.

#Grocery List

Ah, the paragon of an informative example. Every markup language needs a good grocery list. Well, here's mine. Keep in mind, though, that users are free to embed more complex information in the list, and then tell sona how to render it as HTML with a simple template-like syntax. So I'll give a simple grocery list, and then one that I might create if I wanted to add more information.

#Simple
[meta] {
	[title] Groceries,
	[author] Vince Mutolo
}

[document]
Here's a list of groceries.

	[list, ordered: no]
		[i] apples
		[i] bananas
		[i] columbian co… uh… coffee

I imagine many people's first reaction will be something like "But in Markdown, I can just use hyphens." Yes, Markdown will always win in syntax. I know this. Sona, however, is meant to give you powers that Markdown cannot. Consider the following example. Also, the above list really isn't that bad. It's a bit more typing if you're allergic to copy-paste.

#Less Simple
[meta] {
	[title] Groceries, Redux
	[author] Vince Mutolo
}

Here's a more complicated list of groceries.

	[grocery-list]
		[recipe] Soufflé,
		[description] I don't know what this word means.

		[i, aisle: 2] Baking powder
		[i, aisle: π] secrets of the universe
		[i, aisle: -1] cooking is so hard

Before we look at the list itself, notice I had to use the raw tags r# and #r in the title. This is because I wanted a comma in the title, so I wrapped the whole thing in raw tags. Inside raw tags, you can put literally whatever you want, including newlines, and it will be included exactly as-is, byte-for-byte. If you want to include the raw tag itself, you can do so like this: r##r###r, which will render as r#. Use as many #s (octothorpes) as you want.

So, the list. As the user, I can (very quickly) create a template that maps [grocery-list] (you can technically have spaces, but some habits never die) to another scope type like [list] that sona already knows how to render. Technically, sona doesn't know how to render anything, but we've included some basics that users will likely find are pretty comprehensive.

In my mind, [grocery-list] will act just like [list] except that it will render the description in a smaller font under the name of the list. This way, we can render multiple grocery lists on the same document and have them separated nicely. I don't know why anyone would want to do this, but it's nice to have choices.

I'm also picturing the aisle key-value tag in the [item] scope to render by putting something like (aisle: 2) in parentheses after the item. Again, these kinds of small substitutions are made to be easy for users to define. They're one of the principal reasons I created the language in the first place.