Every step toward Literate Programming is worthwhile. It will be interesting to see how others react to the use of characters beyond 1970s ASCII as formatting requests. In a proposal of my own about using such a character in an addition to ` in Go, the "those strange characters scare me" sentiment seemed pretty strong.

fwiw: glyphs U+02DF and U+02B7 are not present in Go fonts

fwiw: glyphs U+02DF and U+02B7 are not present in Go fonts

Yes, WGL4 does not have them. This qualifies for "Open issues", thank you.

I'm totally in favour for rendering numbered and bulletpoint lists better
(read as ul and li in HTML) but Marktop is just dead ugly to read and
painful to write. It'll make my workday miserable when I have to write
it and when I have to read it.

This proposal aims at too much. I think the current godoc formating lacks
two things: a) Inline verbatim/fixed width/code styling and b) automatic
list detection.

Headings, paragraphs are solved and work (not perfectly but they work).

URLs can be detected reliably and I actually do like to see the URL of
a link before clicking on it, so I do not see the need for a link text that
differs from the URL. (This is different for very technical URLs with e.g.
lots of query parameters, but such URLs are uncommon in documentation).

For b) it is hard to find some heuristic which works well for list existing
in the wild (I tried it on the corpus). This might be fixable as most list
which are not detected by a simple heuristic are rendered badly in the
current version anyway. This might be doable and would make complicated
documentation (e.g. package doc better). Even the spec uses uls and lis.

Common wisdom for a) is to use backticks as in markdown. This is ugly,
simply because it is markdown and input and output render different
characters. A less invasive option would be to use two spaces which
makes a word/identifier to stand out in plain text:

Foo foos the  target  while aiming at bar.

Being rendered as "Foo foos target while aiming at bar."
I think something like this would help as it makes writing documentation
easier as you have to reword less and have to rename arguments less
to produce understandable documentation.

(Just my contribution to this bikeshedding.)

@vdobler

b) automatic list detection.

This would impose that the author has gotten intimate knowledge about how the used automat "thinks". Process of getting to this knowledge is painful and time consuming. (This "heuristic fallacy" now affects millions of markdDown and yaml users.)

For b) it is hard to find some heuristic which works well for list existing
in the wild (I tried it on the corpus). This might be fixable as most list
which are not detected by a simple heuristic are rendered badly in the
current version anyway.

Re-read mine's above ;)

There are NO heuristics allowed in the marktop processor. Period.
The author is in control of the output, not an AQI.

Every construct representable in marktop (the list item is one of) is introduced by a single rune and it usually ends where other of its kind begins. The specified hard rule imposes that any marktop introduced change surely ends at an empty line. No exceptions.

Therefore a list is rendered only where intented:

 ¹ List item, ends where another begins
 ¹ next item, begins where other ended

Empty line ended the list. Indent above is not a part of the syntax (hence refferal to the gofmt in the go-focused part of the spec).

Headings, paragraphs are solved and work (not perfectly but they work).

Marktop does not intent to interfere here. It just adds an identifier to the already recognized section, it allows any sentence to have a referral identifier added then used.
The intra-links that once upon a time worked well for the legalese are really useful in technical texts too. (Have you never changed the section title then hunted for references to the old one in prose?)

URLs can be detected reliably and I actually do like to see the URL of
a link before clicking on it, so I do not see the need for a link text that
differs from the URL. (This is different for very technical URLs with e.g.
lots of query parameters, but such URLs are uncommon in documentation).

URLs are not to be detected with marktop. The paths are to be listed.
The intent is to have (web) referrals readable in the source.

Common wisdom for a) is to use backticks as in markdown. This is ugly,
simply because it is markdown and input and output render different
characters.

Backticks are part of the Go language specification and they may carry their meaning even in the prose. Eg. you should use raw string, ie. one in `backticks`. None of marktop proposed runes is a part of any programming language syntax (one I know of, at least). Marktop was designed with possible ambiguities in mind and aims to not introduce one.

A less invasive option would be to use two spaces which
makes a word/identifier to stand out in plain text:

Mhm... then let your editor software strip an ending one:

...you should use  while  loo…
                                OOOPS!  
...you should use  while
loops

P.S. If you do like using space for formatting (and you are using graphical linux desktop on a PC), a short command:
xmodmap -e 'keycode 65 = space space nobreakspace nobreakspace macron diaeresis nobreakspace nobreakspace' on the console will put ˉcodeˉ (alt graph+space) and ¨bold¨ (alt graph+shift+space) under your two or three fingers. With sticky keys turned on it will work even for the mouthstick typing.

Closing this issue for now, until I address weaknesses pointed to me (on irc) mostly
by Windows users (I must admit that I did not know that Microsoft no longer supports creation of custom keyboard mappings, something that was available since XP SP2).

1. Windows stock US-Intl layout lacks breve and macron
2. MacOS stock US layout lacks superscript numbers
3. Various national layouts lack one or the other
4. possible IDE customization can be thought only "per language".

And 5: I desperately need a name without "mark" in it. Two out of five participants were not ashamed to acknowledge that they did not read this proposal past the title because they “abhor the very word markDOWN”.

I will, hopefully soon, open an improved version of this proposal.
Thank you all who read this dense text below the title :)