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 threaddrkmttrApr 21, 2017
@teleclimber @Algot @roar It's not THAT hard is it? Even if you just remember headings and lists that's usually sufficient.
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 Forget

@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.

Apr 21, 2017 at 3:56pmWeb
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.