FLIF Spec

[hrj]

Creating an issue here for further discussions.

I was planning to write the spec in AsciiDoctor format. It seems to produce pretty nice output, in HTML as well as PDF.

It also has support for specifying diagrams.

[jonsneyers]

AsciiDoctor looks interesting, but let's start with markdown for now. We can convert later if it turns out we need additional features. Markdown is convenient because it can be viewed directly from github.

[hrj]

Oh yes, markdown is fine for now. Forgot to mention that.

AsciiDoc is also fully supported by Github.. see these examples

[jonsneyers]

We might want to use something that allows includes (dunno if Markdown or AsciiDoc support that), so we can split the spec into multiple files (to keep it manageable) while we can still generate a single (long) document that contains the full spec.

I've been working a bit on the spec; it's going to take some effort to fully describe everything, and I get tired of it after a while, so I'm hoping others will help flesh it out :)

[panicbit]

We might want to use something that allows includes

In that case AsciiDoc it is. AsciiDoc supports includes (and a lot of other cool stuff) and Markdown does not. http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files

[jonsneyers]

OK. Anyone feels like converting to AsciiDoc? I'm done editing for today...

[panicbit]

The conversion should be trivial when relying on AsciiDoctor's Markdown compatability, i.e. simply renaming it to .adoc or .asciidoc might work.

PS: Tables need some tweaks.

[panicbit]

Do we want to keep the Markdown-style formatting of tables i.e.

| c1 r1 | c2 r1 | c3 r1
| c1 r2 | c2 r2 | c3 r2
| c1 r3 | c2 r4 | c3 r4

or format them like in the AsciiDoctor syntax quickref shows i.e.

| c1 r1
| c2 r1
| c3 r1

| c1 r2
| c2 r2
| c3 r2

| c1 r3
| c2 r4
| c3 r4

❓

The former has the advantage to be more compact, but is more annyoing to keep nice looking. The latter is easier to maintain but uses a lot of vertical space. (The only difference is in the raw format, the rendered view is identical.)

PS: I suppose it makes sense to use the Markdown style for tables with short text and the AsciiDoc style for tables with long text.

[hrj]

I suppose it makes sense to use the Markdown style for tables with short text and the AsciiDoc style for tables with long text.

I like that idea!

[hrj]

The former has the advantage to be more compact, but is more annyoing to keep nice looking.

BTW, if you use VimWiki, it automatically aligns tables and columns as you edit them. (Need to copy-paste between buffers when editing an AsciiDoc). There are other, dedicated plugins too.

[panicbit]

BTW, if you use VimWiki, it automatically aligns tables and columns as you edit them. (Need to copy-paste between buffers when editing an AsciiDoc). There are other, dedicated plugins too.

Doesn't look like there's a plugin for sublime :/