roarApr 20, 2017

This is an example of a revolutionary new document
format called "Plain Text". Some of the features of this format are:

* supported by every editor!
* requires no internet connection!
* editable on any device, from your phone to your TV!
* simple to backup and restore!
* compare documents with "diff"!
* search documents with "grep"!
* can be modified programaticaly using "sed" and "awk"!
* Plain-text supports every version control system out there!

Try plain-text today!

Show threadAlgot (Still)Apr 20, 2017

@roar

My only personal extra is the plain text benefit of Markdown.

Still plain text, but easy to accomplish effective fancy RTF through a tool like Pandoc.

Give them a try and see what you think.

Show threadOlivier ForgetApr 20, 2017
@Algot @roar markdown requires that you know all the special meanings of the special characters of the markdown flavor you are using. If you don't you get unexpected formatting. No thanks.
Show threaddrkmttr
@teleclimber @Algot @roar It's not THAT hard is it? Even if you just remember headings and lists that's usually sufficient.
Apr 21, 2017 at 1:58pmWeb
Show threadAlgot (Still)Apr 21, 2017

@drkmttr @roar @teleclimber

I'm a fan of markdown.
It seemed the most useful of the formats to use so UNPROCESSED text was still very legible.

Passed through a translator like Pandoc, I can get many useful complex formats without significant extra work.

I think the question was whether plain text was the best choice for raw documentation of a project like Mastodon instead of a strict requirement for a particular toolchain.

Show threadroarApr 21, 2017

@Algot @drkmttr @teleclimber

The question had nothing to do with Mastodon. It was just a rant in relation to having to jump hurdles to use Confluence without using their crappy interface.

I write in markdown (well, multimarkdown mostly) because it's currently the best option, but it's not great (and no, I'm not capable of doing better).

Show threadroarApr 21, 2017

@drkmttr @teleclimber @Algot

no, it's not hard, I don't think anyone ever said it was. it is terrible, however, as explained here:
http://undeadly.org/cgi?action=article&sid=20170304230520

Show threaddrkmttrApr 21, 2017
@roar @teleclimber @Algot You're right, "hard" was the wrong word to use. However, I feel that there are only so many ways to structure text while still being productive. Sure, md lacks in in functionality compared to LaTeX and the like but its also easier to adopt and understand immediately which is why it's so widely used. At the end of the day, use whatever floats your boat. ☺️
Show threadOlivier ForgetApr 21, 2017
@roar @drkmttr @Algot Good link! The author breaks down all the flaws with MD in a way I was never able to express.
Show threadOlivier ForgetApr 21, 2017

@drkmttr @Algot @roar Knowing headings and lists is sufficient? Precisely not! A fundamental flaw of markdown is that if you don't know the entire set of special character combinations by heart you will end up with unexpected results.

I once tried documenting code in md. My vars are snake_case so I ended up with subscripts everywhere. Awesome.

To compound the problem there are 47 flavors of MD, each slightly different, so yeah, no.

Show threaddrkmttrApr 21, 2017
@teleclimber @Algot @roar Fair enough, I will agree that the variations of md have gotten out of hand but that's not a problem unique to md. What's your proposed solution for dealing with underscores? Did you try escaping them with a backslash?
Show threadOlivier ForgetApr 21, 2017

@drkmttr @Algot @roar Yes but having to think about escape characters defeats the purpose of something like MD to me. It should to be easy to write. MD makes me think too much. I end up "markdowning" (fiddling with special chars) instead of "documenting".

So I just write things in plain *unprocessed* text (yes, with * for emphasis). If I need more structure or visual expressiveness I go to HTML.

Show threaddrkmttrApr 21, 2017
@teleclimber @Algot @roar If that makes more sense to you than all the more power to you. I agree that you should use what you prefer and makes you more productive. If people people want to be involved with your projects then they will have to learn your documentation methodology. Simple as that.