Markdown and Gemini

[Sean Conner]

It was thus said that the Great James Tomasino once stated:
> >From IRC:
> 
> <solene> I'm on a quite fun project I'll write about soon. I rewrote a
> minimalism markup system, it's markdown but only with titles and code
> blocks supports :D the html converter is 18 lines of awk (1 instruction
> / line)
> 
> For those unfamiliar, solene is an openbsd developer and posts here:
> gopher://dataswamp.org/1/~solene
> 
> She's not working on Gemini, but this mini-markup she's developing may
> prove useful for folks writing clients. As we've discussed, it probably
> doesn't make sense to support the full markdown spec (even if you can
> choose one flavor). Her micro-version might be handy.
> 
> Also, many have said they don't want to translate to HTML for rendering,
> which makes sense for most applications. Regardless, her awk parsing
> will be a helpful aid to anyone looking to write their own.
> 
> I've informed her about potential Gemini applications and she said
> she'll be sharing her code soon. I'll post a link to the list when it
> comes up.

  Having written my own markup-langauge, I think I can offer some notes and
insights into the process.  I am in no way trying to promote what I have as
a standard, as it barely works for me.  Also, it outputs HTML directly (I
use it for blogging).

  Anyway.  I came up with my own markup-laguage [1], based off OrgMode from
Emacs.  It's over 700 lines of Lua code [2] geared towards how I write blog
entries.  I love it and absolutely hate it at the same time.  Mainly, I hate
it because I keep forgetting what are "special" characters and what aren't,
and more often than not, I end up with half the post in an italicized
monspaced font.

  The other problem is when a block section isn't parsed properly, and I
have to hunt down what corner case I ran into this time (in fact, just today
[3] I fixed yet another corner case in rendering, and that happens nearly
every time I use the thing.  Yes, it starts out simple.  Then you want to
format this, and then that, and then the other thing, and pretty soon you
end up with a 700+ line of exceptions threatening to explode.

  As an aside, there are a few aspects I do love about the system.  One is
the automatic conversion of HTML entities (with exceptions like &amp; and
&lt; for technical reasons) into their UTF-8 equivalents.  This let's me
type those characters I can't type, like "?" as "&uuml;".  It can also
handle entities like "&#9772;".  The second aspect is conversion of some
short-cut sequences like `` (two agrave accents) into ? (typographical
quotes).  A third aspect is the ability handle acronyms---that is, it
converts

		TCP

into

		<abbr title="Transmission Control Protocol">TCP</abbr>

but on an ad-hoc, defined in file, way. [4]

  Anyway, I digress.

  So let's define a simple markup language just to discuss some issues.  A
line starting with '#' is a header.  _This is italic text_.  And **some bold
text**.  And

	* a bullet list
	* uses a single asterisk, bold uses two.
	* This is an unordered list.

But

	1 this is a numbered list
	2 like this
	3 see?

  Othersise, paragraphs are reflowed.  Links ... um ... just for now, let's
go with [[http://boston.conman.org][this format for links]].  And already
there are issues, such as: for a bulletted list, are these the same?

*a bullet list
*uses a single asterisk, bold uses two.
*This is an unordered list.

* a bullet list
* uses a single asterisk...
* This is an ...

	*a bullet list
* uses a single ...
	* This is an ...

  And that last one---is that two lists, one with a sub-list underneath it?
And I picked two asterisks for bold just to make it eastier to detect a list
vs. bold text.  Because otherwise, you'll end up with bizzare rules like:

	If a line starts with 0 or more whitespace plus a '*' and the
	following line starts with 0 or more whiatepsace plus a '*' then the
	'*' marks a list, otherwise it starts bold text ...

  That's just part of the problems I have with my own markup language---the
overloaded nature of it all.  I mean, I didn't include a way to have
preformatted text (like source code examples).  Assuming we go along with
the four leading spaces, what happens when we have a nested list?

* Major Topic I
  * Minor detail A of topic I
    * detail 1
    * detail 2

Um ... and then what if we *do* want a list in a preformatted format?

    * Major Topic 1
      * Minor detail A of topic 1
        * detail 1
        * detail 2

  Or is that just a list?

  The point here isn't to try to define a format, my point is to say it's a
messy, difficult job with lots of people wanting different things.  Anyway,
I rambled on long enough ... 

  -spc

[1]	https://github.com/spc476/mod_blog/blob/master/NOTES/testmsg

[2]	https://github.com/spc476/mod_blog/blob/master/Lua/format.lua

[3]	http://boston.conman.org/2019/08/21.1
	It's the blacked out text in the table.  

[4]	I really like HTML in case you can't tell.