Re: header syntax.

On 24 November 2012 15:10, Ryan Freebern <rfreebern@unionstmedia.com> wrote:
> On Nov 24, 2012, at 8:56 AM, Max Albrecht <1@178.is> wrote:
>
>> On 24 Nov 2012, at 09:20, Dave Pawson <dave.pawson@gmail.com> wrote:
>>
>>> 1. I think it unlikely that 'all' implementations action all this
>>> header syntax in exactly the same way. We have no evidence of that.
>>
>> Why do you continue to ignore the facts? Every implementation has implemented it.
>> Karl provided a link to Babelmark2, which I already re-posted. There are no differences.
>
> Babelmark2 is a small, self-selected group of implementations. While
> it's probably a representative sample, it's not all of them.

Of course, it's impossible to cover every use-case. Anyway, covers
most used (popular) implementations.

>> To sum up the discussion: Dave and other are against including trailing hashed in the new spec.
>>
>> They have presented these arguments agains it:
>> - It adds to much complexity
>> - If we follow the original spec, we would be doing nothing
>> - Easier for the user
>>
>> The first argument is subjective, so we have asked to back it up with facts. None were given. ("It is complex" is not an answer to "why is it complex?")
>
> It's not subjective. A header syntax definition that includes trailing
> hashes is undeniably more complex than a header syntax that does not
> include trailing hashes.

We are describing the markup, the document, and what the user is going
to write. If tomorrow, supposedly we won't use underlines or trailing
hashes because they are out of the spec the following situations could
arise:

1) Implementers love the spec: so they force users to adhere to our
spec, then suddenly super-markdown-implementation stop allowing
underlined headers. Suddenly all my documents are broken. Probably I'd
be more tempted to find a markdown implementation that helps me that
change my markup (that's the real world). What did we actually
solved?. Let's not turn that extreme, let's suppose they decided to
keep those "uncomplying" styles... what did the spec did for anyone?
2) Implementers don't care about the spec: we work a lot, nothing
happens, there aren't changes. The spec in the end, doesn't help
anyone.

On the other hand imho, if already includes what is actually used we
can help implementers agree on corner cases (REAL corner cases), then
everybody wins. Most developers already say it. If they don't care
about the spec... do you think users will care? Of course not... our
main "issue" are the developers behind the already most used
implementations.

> The question here is: should we codify this
> complexity as part of the markdown core, or simplify the core to a
> common, easy-to-use and easy-to-implement syntax, and relegate the
> alternative syntax to an intermediate profile?

I think everyone here agreed that we were trying to make markdown easy
and cover corner cases. Now we (somehow) started discussing about
"profiles", "intermediate profiles". There should be only one. Also,
we are not discussing how parsers work, that's the developer job.
Besides, it's already implemented everywhere so I guess it's not THAT
complex.

>> Regarding the second argument it has been pointed out that it is true for corner cases and this isn't one -- and there have been no facts provided why it should be one. Furthermore,
>
> It's a corner case because it's an alternative way to accomplish
> something that can be done more simply. Essentially, it's decorative.
> A core syntax probably shouldn't be concerned with covering all the
> currently-used options, but instead should clearly specify a minimal
> usable subset of the common syntax.

I still think it's not a "corner" case, underlined and hash are ways
to mark the document. Maybe the first one is decorative, but most
people can understand it without having to know the syntax (imho, the
reason why md is so popular).

>> you can look it at it the other way around: What good is a 'core' spec that is not complete, thus guaranteed
>
> You're begging the question by using the word "complete" without an
> agreed-upon definition of what "completion" is. The spec that we're
> trying to create will ideally define what "complete" means; since the
> spec is far from finished, "complete" is up to this group to decide.
> Thinking of Gruber's syntax as an existing spec invalidates what we're
> trying to do.

It's not a spec, it's the main reference, what's already implemented
and so the closest thing to a spec.

>> to be not followed by implementations or users? If the 'core' spec is missing critical features, doesn't that add to the overall complexity since everyone would have to implement/use core+ intermediate-profile-X?
>
> No, no-one would have to do anything. New parsers can choose to
> implement our spec alone, and existing ones could choose to deprecate
> the intermediate profile and encourage users to tighten their
> markdown, for instance, but ultimately it's up to them to decide what
> they support.

Then after almost a week I don't understand what is a "profile".

>> Third: It is debatable what is easier for the user. Some want to learn just 1 rule, some want to have choice.
>
> A single syntax is inarguably easier for the user. The question here
> isn't about ease, it's about whether we want to trade aesthetics for
> simplicity, as the alternate header syntaxes only provide users with
> options about how their document looks, not how it works. I think
> aiming for simplicity in our core spec and adding aesthetics in the
> other profiles is a good way to go.

Regardless of your totally true statement, the truth is that most
people use underline headers than only hashes because for them (myself
included) thinks it looks better. Also, you say it: markdown it's
about how it looks, not how it works, that's (I insist) the reason why
it's popular.

>> However going through old docs, deleting trailing hashes, is what nobody wants.
>
> If parsers choose to implement the intermediate spec, it won't be
> necessary. If users choose to use a parser that doesn't implement the
> intermediate spec, that's not our responsibility.
>
>> The arguments pro-inclusion:
>> - It DOES NOT BREAK existing documents. Fact: trailing hashed are in use, in the real world.
>
> If we aim for the status quo, we'll accomplish nothing, at best.

I really hate that argument. It's assuming the most time we invest,
the better result we have. Forgetting completely the usefulness of a
spec. XHTML 2.0 it's a good example of what I don't want to imitate.
Also, we can discuss if some common "extensions" (fenced code blocks
for example) are good ideas of stuff we can try to "standarize".

>> - This is a not a case of ambiguity in the Gruber spec nor where implementations differ. Fact: Babelmark2 shows it. [1]
>
> Again, Gruber's syntax is not a spec, or else we wouldn't be
> undertaking this process. While his syntax obviously needs to inform
> our decisions, it should not control them, and when we can strive for
> simplicity and clarity I think it's important that we do so.

Please, then let's try to create YARSML (Yet another simple markup
language; I wrote yaml first but I realized it already existed lol)
and forget about JG or all the implementations around. We can say it's
based on markdown and I can leave because I just plain don't care on
ANOTHER language.

Honestly, when I read Atwood post, and joined here I thought we were
going to formalize JG "spec", try to be clear on ambiguities and
study/discuss which "extensions" (if any) could be included in the
core.

Regards,
--
Pablo Olmos de Aguilera Corradini - @PaBLoX
http://www.glatelier.org/
http://about.me/pablox/
http://www.linkedin.com/in/pablooda/
Linux User: #456971 - http://counter.li.org/

Received on Saturday, 24 November 2012 21:07:34 UTC