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]

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.