adapting beyond markdown recommendations for janet docstrings

adapting-beyond-markdown-recommendations-for-janet-docstrings.md

Draft - Summary of Recommendations for Janet Docstrings

1. Emphasis

   • Use distinct characters for emphasis and strong emphasis.
   • Don’t use doubled-character delimiters.
   • Simplify emphasis rules. May be don't allow nesting?
   • Introduce special syntax for intraword emphasis, with ~ behaving like a space as far as parsing emphasis goes, but render as nothing.

2. Reference links - Don't have any kind of links

   • Don’t make parsing something as a link depend on whether a reference link definition exists elsewhere in the document.
   • Remove shortcut reference links.

3. Code (Blocks)

   • Remove indented code blocks. Use only fenced blocks for code. Allow both kinds of code blocks.

4. Lists - Need to examine these closely

   • Use simple rule for determining what belongs under a list item: anything indented at all with respect to the list marker belongs in the item.
   • Require a blank line between paragraph content and a following list.
   • Revise rules for tight lists: a list is tight if any two items lack a blank line between them.

5. HTML Don't do any special processing of HTML

   • Remove automatic pass-through of raw HTML. Things like <br> will now be treated as regular text and escaped.
   • Introduce an explicit syntax for passing through raw content in an arbitrary format. In inline contexts, a code span followed by {=FORMAT}; in block contexts, a fenced code block with info string {=FORMAT}.

6. Attributes - Don't implement any kind of attribute mechanism

   • Introduce a uniform attribute syntax, like this: {class #identifier key=value}.
   • Allow attributes on any block element. The identifier must appear by itself on the line before the block element. Multiple attributes can be specified on successive lines; they will be combined.
   • Allow attributes on any inline element. The identifier must appear immediately after (and adjacent to) the inline element to which it is to apply.

adapted list from: via: https://talk.commonmark.org/t/beyond-markdown/2787