How can we get more non-programmers involved?

Or we could have a common document declaration standard that allows for specifying if the user intends for hardwrapping or not. And leave the base default settings up to the administrator of a website.

This topic was intended to address the general population of this forum, rather than the authors of the spec (listed on the front page of commonmark.org), some of whom no doubt have a lot of experience with writers of Markdown.

In particular, the block directives discussion stands out as a syntax designed by the minds of programmers. This is not intended to offend anyone who contributed to that discussion, but the impression I get is that we’re moving away from Markdown as a language that is appealing to writers. That’s a direction that I hope CommonMark can avoid.

[quote=“jgm, post:13, topic:833”]But, if you have a site that does treat newlines as hard breaks, you’ll get complains from people who expect to be able to hard-wrap paragraphs (indeed, I note several such complaints on this site). (I would have complained to you, and to github, for rendering my hard-wrapped paragraphs as ugly jagged typographical monstrosities, but I’m too lazy.)
[/quote]

It does seem that people expect new lines to represent new paragraphs, but from the readability point of view it can be hard to see that a new line is a new paragraph. If the last line of the previous paragraph is the full width of the text editor, there is no way of telling that a new paragraph has started just by looking it the text. The same is true of line breaks.

I moved 3 posts to a new topic: Lists without a list indicator character?

1 Like

In the context of this thread: I’m a software engineer and unfamiliar with the intimacies of the spec.

I feel that the exact interface I used to compose this comment on talk.commonmark fulfills a large number of my use cases, with emphasis on:

  • Wiki style editing
  • Composition of short form content, akin to emails
  • Instant preview capabilities
  • Trial and error learning

With that in mind, my selfish question:
Is the code underlying this editor open-source, and available to be incorporated into other apps?

Less selfish question:
Is there a ‘quickstart’ guide anywhere that could get an ‘ignorant’ user capable of composing a simple post? I’d be happy to begin or contribute towards such a guide.

+++ Colin Fergus [Jan 26 15 23:36 ]:

In the context of this thread: I’m a software engineer and unfamiliar with the intimacies of the spec.

I feel that the exact interface I used to compose this comment on talk.commonmark fulfills a large number of my use cases, with emphasis on:

  • Wiki style editing
  • Composition of short form content, akin to emails
  • Instant preview capabilities
  • Trial and error learning

With that in mind, my selfish question:
Is the code underlying this editor open-source, and available to be incorporated into other apps?

I believe it is, but @codinghorror should be able to point you in the right direction.

Less selfish question:
Is there a ‘quickstart’ guide anywhere that could get an ‘ignorant’ user capable of composing a simple post? I’d be happy to begin or contribute towards such a guide.

Currently your best bet is to use John Gruber’s original Markdown docs.
http://daringfireball.net/projects/markdown/basics

There’s a thread in this forum about developing a CommonMark-specific guide. You might offer to help there.

Some do […] Others don’t.

Sure.

So, again, I must disagree.

I don’t think this is a point to agree or disagree about. It’s a matter of preference for the two of you, but when it comes to the spec shouldn’t this be resolved by more than anecdotal data?
The supposition that there is some selection bias could be addressed by advertising a survey on platforms that have implemented either approach (and comparing their response profiles) + ideally some markdown-naive people.
I’d venture another hypothesis: older people tend to want to be be able to hard wrap their paragraphs and view them as soft wrapped. Surely it depends a little on what sort of email client you were reared on.

For what it’s worth, I am also in contact with a lot of non-programmer academics using markdown. Many complained before I switched my software to hard line breaks, none since.

The line break behaviour has been discussed in the Default line break handling is inconvenient topic. The topic contains some solid reasoning for keeping soft line breaks.

One issue with a survey approach to spec changes is that it leaves decisions to popular opinion. But popular opinion isn’t necessarily as well thought out as decisions that are based on carefully examining a number of different angles.

+++ Ruben [Jan 29 15 18:54 ]:

Some do […] Others don’t.

Sure.

So, again, I must disagree.

I don’t think this is a point to agree or disagree about. It’s a matter of preference for the two of you, but when it comes to the spec shouldn’t this be resolved by more than anecdotal data?
The supposition that there is some selection bias could be addressed by advertising a survey on platforms that have implemented either approach (and comparing their response profiles) + ideally some markdown-naive people.
I’d venture another hypothesis: older people tend to want to be be able to hard wrap their paragraphs and view them as soft wrapped. Surely it depends a little on what sort of email client you were reared on.

I think that different sorts of populations are just going to have different preferences here. And I’m sure you’re right about the age bias. But I’d be completely against making the newline-is-hard-break behavior standard, for several reasons that seem compelling to me, and that go beyond my own preferences:

  1. It would be a significant break in compatibility with original Markdown,

  2. This feature of original Markdown is motivated by one of the guiding principles of Markdown, which we also endorse: that source texts look readable on their own. Being able to hard-wrap to a nice column width is important for that.

  3. Good typography very, very rarely demands a hard line break in the middle of a paragraph, and most of the time this looks terrible. We should not make it easy and common.

I think the way the spec currently handles this is a nice compromise. The spec allows that a “softbreak” might be rendered in various ways, either as a newline, or as a space, or as a <br/> tag, and leaves that as an option for the renderer. My own preference would be not to make this an option, but I’m willing to got that far.

1 Like

What’s the alternative to resolving defaults by asking users what most of them prefer?
I thought it’s already decided that it’s definitely an option left to the parser, but advocating a default that most people will like seems sensible to me.

In the discussion you link it seems that some people have arguments and angles, but a lot of responses essentially refer to popular opinion in an informal way (I know x users who don’t like, I’m surprised by the number of users who don’t know hard wrapping editors, I get lots of complaints about x/y).

I also think this is not of a case of objectively better or worse, it’s what you’re used to (i.e. text editors that softwrap or don’t). Some people argue that people are used to Markdown.pl but Github-flavoured also has a lot mileage.

So, I don’t think this is resolvable by considering various angles, but by popular opinion. At the moment this happens informally, which is bad (i.e. though I love pandoc I’m acutely aware that it has far fewer users than Stackoverflow and Github).

I don’t want to dismiss your experience or preference, I just don’t think that it’s the only experience that counts.

  1. However, many implementers (Github, this forum) have set a different standard. I’m not use which standard has more users, but I’d be interested to see which standard has more proponents.
  2. This is important if you use a text editor which does not soft-wrap. I think there may be fewer people who do so than you think (e.g. Microsoft Word, the presumably most widespread Text Editor of all by a far margin soft wraps and so do textareas in all browsers I know).
  3. I think enough examples to the contrary have been enumerated. People who think this looks terrible have an easy way out: don’t put in line breaks if you don’t want them to appear later. This may be bad for users of certain text editors, which I think are few in number.

So, basically I think all these points are down to experience, use cases etc. not just to finding good arguments that hold in all cases.

But I don’t want to count my anecdotes against yours. Even if the spec stays the same, I think data on users’ preferred solution in addition to information what population they’re part of may lead implementers to choose informed defaults (e.g. a forum for poets would use a different standard than a forum for xxx).

+++ Ruben [Jan 30 15 13:43 ]:

  1. However, many implementers (Github, this forum) have set a different standard. I’m not use which standard has more users, but I’d be interested to see which standard has more proponents.

Note that github actually has two standards. For READMEs and the like, it interprets newlines as soft breaks. In issue comments, it interprets newlines as hard breaks.

  1. This is important if you use a text editor which does not soft-wrap. I think there may be fewer people who do so than you think (e.g. Microsoft Word, the presumably most widespread Text Editor of all by a far margin soft wraps and so do textareas in all browsers I know).

Text boxes are frequently wider than the ideal line width (as are editor windows). And what if you want to make your lists pretty, like this?

2. This is important if you use a text editor which does not
   soft-wrap. I think there may be fewer people who do so than you
   think (e.g. Microsoft Word, the presumably most widespread Text
   Editor of all by a far margin soft wraps and so do textareas in
   all browsers I know).

I think that looks much better than

2. This is important if you use a text editor which does not soft-wrap. I
think there may be fewer people who do so than you think (e.g. Microsoft Word,
the presumably most widespread Text Editor of all by a far margin soft wraps
and so do textareas in all browsers I know).

which is how it might appear without newlines in a text box that soft-wraps.

Similarly, I think

> This is important if you use a text editor which does not
> soft-wrap. I think there may be fewer people who do so than you
> think (e.g. Microsoft Word, the presumably most widespread Text
> Editor of all by a far margin soft wraps and so do textareas in
> all browsers I know).

looks better than

> This is important if you use a text editor which does not soft-wrap. I
think there may be fewer people who do so than you think (e.g. Microsoft Word,
the presumably most widespread Text Editor of all by a far margin soft wraps and
so do textareas in all browsers I know).

It’s clearer that the whole thing is a block quote.

One of the guiding ideas of Markdown is that the source text should be highly readable on its own, without the need for any special rendering.

People who think this looks terrible have an easy way out: don’t put in line breaks if you don’t want them to appear later. This may be bad for users of certain text editors, which I think are few in number.

It goes both ways. People who want a newline to be interpreted as a hard break have an easy way out: add a backslash before it.

Let’s compare. If newlines count as hard breaks, then:

  • it becomes impossible to hard-wrap text, so people who prefer that are just out of luck, and
  • it becomes slightly easier to create hard breaks inside a paragraph (which is rarely called for in good typography)

With the current default:

  • it is possible to hard-wrap text, or not to do so, depending on the writer’s preferences, and
  • it is not at all difficult to create hard breaks inside paragraphs (in those rare cases when this is needed); you just need a backslash at the end of the line.

I think it’s better to keep more possibilities open for writers, rather than restricting them.

Even if the spec stays the same, I think data on users’ preferred solution in addition to information what population they’re part of may lead implementers to choose informed defaults (e.g. a forum for poets would use a different standard than a forum for xxx).

Sure. That is why the spec leaves the rendering of softbreaks as an option. However, I think that ultimately something like reST line blocks would be a better option for poetry, addresses, and the other cases where hard breaks make sense.

4 Likes

I am not a programmer (just know a little bash and Python).
I write everything in MacVim and use pandoc to convert it
to whatever and back again, if need be.

I like using semantic linefeeds, see

http://rhodesmill.org/brandon/2012/one-sentence-per-line/

That way my working file is easy for me to read.
Then when I need to serve that text up to someone or some website.
I just run it through pandoc and make it into pdf or html or docx.

I appreciate what you guys are doing, especially JGM
who makes life much easier for those of us who like to write in our favorite text editors.

Rick

Via arguments. I think @jgm’s post summed up the main arguments well.

It’s also important to encourage semantically meaningful markup. This isn’t necessarily a priority of writers if you asked them in a survey, but it could be argued that it should be. What people think they want for their own writing doesn’t necessarily reflect important behind the scenes details (such as how well structured semantic documents are produced).

I’ve read the arguments in the linked post. There’s no need to repeat them.

I submit that they ultimately boil down to preference and what you’re used to. They’re simply not time-, habit- or editor-invariant and if they were, you’d still have different ideas about how important each argument is. For example, I think it is very important that most users get it right quickly on their first try without needing much of an introduction. Backslash or <br> or two-space linebreaks fail that criterion in my experience, but I’ll be the first to say that my experience doesn’t count enough, data would be better.

There is a desire not to balkanize Markdown (any further). I think choosing the right default matters, consider this exchange, the makers of rmarkdown don’t want to make hard line breaks easy to choose for end users.

In politics (which is what I think this is), it’s not uncommon to have a vote, with the best arguments in favour and against displayed to voters. So I don’t think preference and arguments have to be divorced.
But of course I also know that votes don’t happen if the powers that be wouldn’t like the results (I’m joking, I don’t think there’s a linebreak conspiracy! :smile:).

I agree that there are different values/policies being prioritised here. Majority rules is also a value system. I’m more inclined to value staying true to the philosophy of Markdown (and HTML), even if that is not what the majority agrees with. In the end the spec will feel like more of an intentional and cohesive whole.

1 Like

If you want more non-programmers involved then shouldn’t the landing page have a button and page just for the person who barely knows what Markdown is?

As is, the curious beginner is cast headlong into a discussion of specs and standards, with no explanation of what Markdown is to begin with. How is it being used? How it’s proliferating, which is great, but then comes the Great Confusion and the Tower of Babel, so we need a spec etc.

I know. I talk big. Next free day perhaps I will try to write it myself.

Rick

This could be incorporated into the new website/tutorial being planned in this topic.

1 Like

@chrisalley, if @Rick is interested in collaborating on this, you might take him up on it. He’s a professional writer and National Book Award finalist!

1 Like

Pshaw that’s all? I write a blog! @rick next time bring some real credentials :wink: