Navigation

HomeAboutBlogMy fiction

Let’s go

Yes, the format of this page is different from anything else used here. I am experimenting with the AsciiDoc markup language, through its Ruby-based processing engine AsciiDoctor.

Looking at it, I’m at a minor loss to understand why Markdown is chosen over it as a markup language. Markdown has differing implementations, such as GitHub flavoured, Markdown Extra, MultiMarkdown, et al.

That’s only scratching the surface though. AsciiDoc has a fuller specification, meaning you can add all kinds of markup to your document without resorting to embedding HTML for the things that Markdown lacks. Also, the underlying markup code isn’t that different, meaning someone proficient in Markdown would pick up AsciiDoc without too much trouble.

AsciiDoctor takes things a step further by doing processing tasks on the document, formatting it nicely as you can see. Headings, quotes, lists and so forth, are all defined by CSS, which of course is user-editable. So, it’s similar to pandoc, but its default styling is fuller.

Tip
CSS can be modified to suit one’s taste. The result doesn’t need to look like this.

As I gain familiarity with it, I’ll alter the CSS to make the result appear just that little less boilerplate.

One thing I’m going to research is how to put the CSS in a separate file. By default, it adds it to the document inline (view source for evidence), which in my opinion, is messy.

Update Yes, it can be done - followed the sage advice found here and now it all exists as external CSS.

So, the command is asciidoctor -a linkcss docname.adoc

Anyhow…​

But…​and this is a hopeful, provisional but…​there’s enough here with AsciiDoc that it may well supplant what already exists. Particularly for my fiction, as I feel its current implementation isn’t ideal.

Important
Petergreenwell.com is subject to alteration and authorial whim!

Let’s try something code-wise here…​

hello.rs
fn main() {
	println!("Hello World")
}

Yes, that worked.

Sidebar

This is a sidebar - like the nav one at the top.

Extras

I just noticed as I compiled a draft of this document, that it auto-converts quotes into "smart" quotes, or curly quotes as some call them. This is eminently useful for fiction writing, where the use of such quote styles is de rigueur (thought I’d try out another italic there). Will AsciiDoc replace LibreOffice? Hard to say. I tend to fall back to things I’m comfortable with.

Flipside

The main deficit I can see using AsciiDoc to replace writing raw HTML is the doubling of files. Rather than foo.html I will have foo.adoc and foo.html sitting in their directory. While that is not an issue in regards to space, I’m thinking more in terms of doubling the complexity. Things tend to go wrong more frequently with more moving parts.

There’s ways around this - keep the adocs in a separate directory, for one. I’m certain this extra file (non-)issue will resolve itself with familiarity.

And we’re done

That’s enough for one public experiment. I’ll delve into the fine art of AsciiDoc for a while and learn what I can conjure up.


I know always that I am an outsider; a stranger in this century and among those who are still men.
— H.P. Lovecraft
The Outsider

©1996-present Peter (Booth) Greenwell - texts and images CC BY-SA 4.0
Made with ♥ and Neovim!