kissup_spec.txt

KissUp is extensible BBCode with Markdown syntactic sugar for use in technical
documentation.

"Keep It Simple: Stupid markUp"

Principles
==========

* The user shall never have to look up syntax rules after one hour of
  experience with the language.
* Corollary: syntax should be familiar, simple, or both.
* Implementations should be able to add complex features without requiring
  new syntax.

Why not HTML?
=============

* You won't know what tags you can use
* You'll expect it to only ever output to HTML
* You'll never be completely certain it isn't XML

BBCode Dialect
==============

BBCode is a tiny subset of SGML. Tags:
* Have a name
* Have zero or more required or optional arguments
* Can have text contents (normal) or not (self-closing)

// comments are a thing
/* yes they are */

// commands can be self-closing or not
[command arg1=x arg2="y"]   // self-closing
[another_command arg1=x arg2="y"]I have text in me![/another_command]  // not self-closing

[command arg1="\"string escaping is a thing\"" arg2={but there may be many options for delimeters}]

You can also type \[literal brackets\].

The set of available tags is implementation-defined.

Everything that follows this line is simply a text transform for syntactic
sugar and requires explicit implementation support.

Tables
======

// Tables don't try to use shitty ASCII syntax
[table]
  [th][td]header cell[/td][/th]
  [tr][td]normal cell[/td][/tr]
[/table]

Line-Level Syntactic Sugar
==========================

# Heading 1
-> [h1]Heading 1[/h1]

Heading 1
=========
-> [h1]Heading 1[/h1]

## Heading 2
-> [h2]Heading 2[/h2]

Heading 2
---------
-> [h2]Heading 1[/h2]

* Unordered list
  with continuations
  * and nesting
    - and different symbols
      1. and nested ordering
->  [ul]
      [li]
        Unordered list with continuations
        [ul] /* ...screw it you get the idea */ [/ul]
      [/li]
    [/ul]

1. Ordered list
  a. blah
2. Yay
1. Obey numbers

> Blockquotes
-> [blockquote]Blockquotes[/blockquote]

```cpp      // comments work here
someCode(); // but comments don't work in here
```
->  [codeblock language=cpp]
    someCode(); // but comments don't work in here
    [/codeblock]

Inline Syntactic Sugar
======================

// These four work with nesting:
*italic*
_italic_
-> [i]italic[/i]
**bold**
__bold__
-> [b]bold[/b]

`monospace text`
-> [code]monospace text[/code]
``monospace text ` with `tics``
-> [code]monospace text ` with `tics[/code]
// see also [code language="js"]self.highlightedInlineCode()[/code]

![image caption](image URL)
-> [img title="image caption"]image URL[/img]

[link text](link URL)
-> [url="link URL"]link text[/url]

:emoji:  // variable substitution, actually
-> [replace_variable name="emoji"]
  -> [img]emoji URL[/img]

KissUp is extensible BBCode with Markdown syntactic sugar for use in technical
documentation.

"Keep It Simple: Stupid markUp"

Principles

• The user shall never have to look up syntax rules after one hour of
  experience with the language.
• Corollary: syntax should be familiar, simple, or both.
• Implementations should be able to add complex features without requiring
  new syntax.

Why not HTML?

• You won't know what tags you can use
• You'll expect it to only ever output to HTML
• You'll never be completely certain it isn't XML

BBCode Dialect

BBCode is a tiny subset of SGML. Tags:

• Have a name
• Have zero or more required or optional arguments
• Can have text contents (normal) or not (self-closing)

// comments are a thing
/* yes they are */

// commands can be self-closing or not
[command arg1=x arg2="y"] // self-closing
[another_command arg1=x arg2="y"]I have text in me![/another_command] // not self-closing

[command arg1=""string escaping is a thing"" arg2={but there may be many options for delimeters}]

TH: It would be much more readable if had the same closing symbol for all tags. I have always hated how verbose languages which a different symbol per word read. They also look terrible as plain text.

You can also type [literal brackets].

The set of available tags is implementation-defined.

Everything that follows this line is simply a text transform for syntactic
sugar and requires explicit implementation support.

Tables

TH: The shitty ascii syntax github uses is a million times better as plain text and actually easier to use. I would say: make a better ascii syntax.

// Tables don't try to use shitty ASCII syntax
[table]
[th][td]header cell[/td][/th]
[tr][td]normal cell[/td][/tr]
[/table]

Line-Level Syntactic Sugar

Heading 1

-> [h1]Heading 1[/h1]

Heading 1

-> [h1]Heading 1[/h1]

Heading 2

-> [h2]Heading 2[/h2]

Heading 2

-> [h2]Heading 1[/h2]

TH: Have clear unambiguous rules for indentation and nesting. A formal grammar for this thing is a must. The lack of it is what makes Markdown such a cluster of different takes on the daring fireball spec. Start with a grammar!

• Unordered list
  with continuations
  • and nesting
    • and different symbols
      1. and nested ordering
         -> [ul]
         [li]
         Unordered list with continuations
         [ul] /* ...screw it you get the idea */ [/ul]
         [/li]
         [/ul]

1. Ordered list
   a. blah
2. Yay
3. Obey numbers

Blockquotes
-> [blockquote]Blockquotes[/blockquote]

TH: Are you going to have indented code blocks? If not, how are code blocks going to work in lists. You needs to have both the syntatic rules and the semantic rules for unambiguous translation. I can help you with how you write semantic rules.

```cpp      // comments work here
someCode(); // but comments don't work in here
\```

[codeblock language=cpp]
someCode(); // but comments don't work in here
[/codeblock]

Inline Syntactic Sugar

TH: Personally, it has always annoyed me that you can't do underlining with markdown. IMO: _asdf_ should be underlined and __asdf__ should be nothing. ~asdf~ or -asdf- should be strike through. Once again a grammar will clarify HOW it works with nesting.

// These four work with nesting:
italic
italic
-> [i]italic[/i]
bold
bold
-> [b]bold[/b]

monospace text
-> [code]monospace text[/code]
monospace text with tics
-> [code]monospace text withtics[/code]
// see also [code language="js"]self.highlightedInlineCode()[/code]

-> [img title="image caption"]image URL[/img]

[link text](link URL)
-> [url="link URL"]link text[/url]

:emoji: // variable substitution, actually
-> [replace_variable name="emoji"]
-> [img]emoji URL[/img]

TH: You should go ahead and define the syntax for @ mentions and # mentions. I would also recommend code links as this for documentation. What that looks like.

Tag syntax

I'm not sure what you mean by "same closing symbol for all tags." Do you mean that attributes inside tags should also use square brackets? If so, I would have to disagree, because people will expect to type quotes. Or do you mean that self-closing tags should not have the same closing character as non-self-closing tags? (i.e. right square bracket)

Underlines and strikethroughs

Yes.

Nesting rules

Everything can be nested if written in BBCode.

Everything can be nested in Markdown, except that "line-level" markup (mostly as described by this doc but formally specified) may not be nested inside "inline markup". However, the converse is fine.

Tables

ASCII tables are fine, but someone else will have to design the spec and implement them. :-)

I just want to make sure it isn't nearly impossible to make wide tables while limiting the source files to 80 characters per line.

@ and #

Fine with me. This would be "inline markup."

"Code links"

I think I'll leave this one to BBCode. This seems fine: [ref function_name="fooBar"] (or, if we're doing trailing slashes in self-closing tags, [ref function_name="fooBar" \])

References of this type in markup languages often cause token-itis: the language adds new tokens just to serve features like this, and it's hard to remember the exact variant of link syntax you need to do the thing you want.