Writing With Ink indentation

[PiOverFour]

Hello, I started using Ink and really like it. There are several things which have been bugging me in the documentation though, and the most confusing one is the inconsistent indentations. Now I know they hold no syntactic value, but many indentations are inconsistent within a single example, and across the whole text. This makes it harder to follow and get an idea for the style of the language.

This pull request does two things:

1. surround each example block with ```s, instead of indentations. This has at least three advantages:

• it makes the document more legible in text mode;
• it helps notice indentation errors;
• should you decide to ask GitHub for Ink syntax highlighting via Linguist, the markup will already be there. This is a feature from GitHub Flavoured Markdown, but it’s quite ubiquitous, and was even present in one example from this document. I also checked that it didn’t mess up Inky’s internal documentation—which appears outdated, by the way.

2. Reindent every example, trying to be more consistent. This is necessarily opinionated, since I haven’t found any guideline apart from this very document, but I hope it’s true to your vision for the language.

One thing to consider is that your examples use tabs a lot, which have some advantages, but don’t work nicely everywhere. Since GH uses 8-column tabs, some indentation which are meant for 2- or 4-column look broken. I’m writing a tool that automatically indents Ink files, so while I’m at it, I could reindent everything using spaces without much effort if you’d like.

[joethephish]

In general this sounds like a good pull request, especially with the use of ```. It would be amazing if we could get github support for ink.

Indentation consistency sounds good. We do have an in-house style that @joningold has developed that we'd prefer to use. Do you think you could summarise, Jon? I suspect this pull request hasn't quite matched it.

Oh, and yes I'd much prefer to use spaces rather than tabs. In general I'm not too militant about it, but github's 8-space tab size is a bit nuts.

[joningold]

I’ll take a look over this. Indentation is sometimes a bit contextual though depending on what sort of thing you’re doing! But I’ll take a look and see how it reads to me.

Jazz, in Three-Four Time: A Novel http://www.amazon.co.uk/dp/B004K1EYIE

[PiOverFour]

That’s great, I’d love an indentation guide! It would make it much easier to get sane auto-indentation, even if not perfect. Thanks for looking into it. :)

[PiOverFour]

Hello again; if you are interested in comparing, here is another branch indented with two columns of spaces.

[joethephish]

Sorry, this has become ancient and now has conflicts. It never quite bubbled up on our priority list.