search

FLIF-hub / FLIF-doc

Documentation related to FLIF: a paper, a spec, design rationale, etc.
5 stars 4 forks source link

FLIF Spec #2

Open hrj opened 7 years ago

hrj commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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

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

jonsneyers commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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

panicbit commented 7 years ago

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 commented 7 years ago

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

:question:

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 :/