What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[bucephalus org]

Hi there!

(1.)

It may sound awkward, but I would like to use comments in Markdown texts.
According to the rule that proper HTML works as HTML, I should be able to
use



But the converters I use do strange things with comments. Is there an
official rule about that?


(2.)

I wonder if there is a recommended standard file extension for Markdown
source files.
For my own files I always use `.markdown`.
But other important sources seem to prefer `.text`.

Do you have an opinion on that, or is there even a standard?
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Waylan Limberg]

On Wed, May 4, 2011 at 9:03 PM, bucephalus org  wrote:
> Hi there!
> (1.)
> It may sound awkward, but I would like to use comments in Markdown texts.
> According to the rule that proper HTML works as HTML, I should be able to
> use
>     
> But the converters I use do strange things with comments. Is there an
> official rule about that?

As you can see here [1], most implementations pass comments through.

[1]: http://babelmark.bobtfish.net/?markdown=<%21--++blablabla+-->

>
> (2.)
> I wonder if there is a recommended standard file extension for Markdown
> source files.
> For my own files I always use `.markdown`.
> But other important sources seem to prefer `.text`.
> Do you have an opinion on that, or is there even a standard?
>

This has been a hotly debated topic in the past and IIRC J. Gruber
(the creator of Markdown) has indicated that he will not support a
standard and he personally uses '.text'. However, most projects I'm
aware of use '.md' or '.markdown'. Personally, I prefer '.txt' or
'.text' but notice what happened when I requested that github work
with that [2].

[2]: https://github.com/mojombo/jekyll/issues/230



-- 

\X/ /-\ `/ |_ /-\ |\|
Waylan Limberg
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[bucephalus org]

Hey Waylan,

this is very helpful. Thank you!

On Thu, May 5, 2011 at 3:23 AM, Waylan Limberg  wrote:

> On Wed, May 4, 2011 at 9:03 PM, bucephalus org 
> wrote:
> > Hi there!
> > (1.)
> > It may sound awkward, but I would like to use comments in Markdown texts.
> > According to the rule that proper HTML works as HTML, I should be able to
> > use
> > 
> > But the converters I use do strange things with comments. Is there an
> > official rule about that?
>
> As you can see here [1], most implementations pass comments through.
>
> [1]: http://babelmark.bobtfish.net/?markdown=<%21--++blablabla+-->
>
> Yes, you are right. It turns out, that I made a type error in my own tests.
I didn't know this babelmark.bobtfish.net, and it is a great tool (even
though some of the converters are quite outdated).


> > (2.)
> > I wonder if there is a recommended standard file extension for Markdown
> > source files.
> > For my own files I always use `.markdown`.
> > But other important sources seem to prefer `.text`.
> > Do you have an opinion on that, or is there even a standard?
> >
>
> This has been a hotly debated topic in the past and IIRC J. Gruber
> (the creator of Markdown) has indicated that he will not support a
> standard and he personally uses '.text'. However, most projects I'm
> aware of use '.md' or '.markdown'. Personally, I prefer '.txt' or
> '.text' but notice what happened when I requested that github work
> with that [2].
>
> [2]: https://github.com/mojombo/jekyll/issues/230
>
> O.k. This is interesting. I need to think about all that, but I suppose, I
am not convinced in the end. I think, there should be some special standard
other than `txt` or `text`.
But of course, have a/no standard is more important than having my standard
as standard, so I can live with that.

Thank you, again, for your kind response.

Cheers, Tom

>
> --
> 
> \X/ /-\ `/ |_ /-\ |\|
> Waylan Limberg
> ___
> Markdown-Discuss mailing list
> Markdown-Discuss@six.pairlist.net
> http://six.pairlist.net/mailman/listinfo/markdown-discuss
>
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Edi Stojicevic]

* bucephalus org  [2011-05-05 03:03:05 +0200] wrote :

> Hi there!

Hi ;)

[...]

> (2.)
> 
> I wonder if there is a recommended standard file extension for Markdown
> source files.
> For my own files I always use `.markdown`.
> But other important sources seem to prefer `.text`.
> 
> Do you have an opinion on that, or is there even a standard?

On my side, I'm using .mkd ... Can't remember exactly where I saw that
one ... but works fine for vim :)

-- 
 .''`.  Edi Stojicevic
: :'  : Debian GNU/Linux user, admin & developer - http://www.debian.org 
`. `~'  Debianworld - http://www.debianworld.org 
  `-
Linux is obsolete
-- Andrew Tanenbaum
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Tommy Bollman]

Hello.

Not having tried to use MultiMarkdown for comments, but knowing that they work 
for including
raw latex, I can't see why they shouldn't work for html as comments.

I ran this test:

 MMD document:
## comment test html

To comment or not comment is a question about reflection.

-- Resulting html:
comment test html



To comment or not comment is a question about reflection.
 
hth

Tommy

Den 5. mai 2011 kl. 03.03 skrev bucephalus org:

> Hi there!
> 
> (1.)
> 
> It may sound awkward, but I would like to use comments in Markdown texts.
> According to the rule that proper HTML works as HTML, I should be able to
> use
> 
>
> 
> But the converters I use do strange things with comments. Is there an
> official rule about that?
> 
> 
> (2.)
> 
> I wonder if there is a recommended standard file extension for Markdown
> source files.
> For my own files I always use `.markdown`.
> But other important sources seem to prefer `.text`.
> 
> Do you have an opinion on that, or is there even a standard?
> ___
> Markdown-Discuss mailing list
> Markdown-Discuss@six.pairlist.net
> http://six.pairlist.net/mailman/listinfo/markdown-discuss

Best regards



Tommy Bollman
--
Mollison's Bureaucracy Hypothesis:
If an idea can survive a bureaucratic review
and be implemented it wasn't worth doing.

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Aristotle Pagaltzis]

* Waylan Limberg  [2011-05-05 03:25]:
> However, most projects I'm aware of use '.md' or '.markdown'.

`.mkd` and `.mkdn` are also popular. I’ve seen `.mdwn` also,
and I think even `.mdn` though I’m not sure about that one.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Seumas Mac Uilleachan]

On 05/06/2011 06:00 PM, Aristotle Pagaltzis wrote:
> * Waylan Limberg  [2011-05-05 03:25]:
>> However, most projects I'm aware of use '.md' or '.markdown'.
> `.mkd` and `.mkdn` are also popular. I’ve seen `.mdwn` also,
> and I think even `.mdn` though I’m not sure about that one.
>
> Regards,
I also recall seeing .mdown somewhere. I think the point is that the
extension really shoudn't matter. Use what you want. Let the metadata
take care of the rest. Similar to a #! in shell scripts to specify
language interpreter. Don't matter what the extension is there either.

I have also over the years seen .txt, .text, .doc, .note, .asc, .ascii,
and no extension at all for text files. Also read.me
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[bucephalus org]

Hello, all you nice people out there!

Thank you for your comments and reactions, this is helpful and I got the
message.

Markdown is a great format for writing standard texts and it has become my
first choice.
I use a couple of tools to create my own "office environment" that allows me
to comfortable work with it.
I am also using it for my own program code documentations [1]. This concept
of using Markdown as both a documentation language and the intermediate
format in the conversion process has great potentials and I already outlined
it on this mailing list under the title of CodeDown [2]. I am working on a
script that implements all that, and this is making slow but steady
progress.
As soon as this is operational, I would like to announce it here, again, and
I am already keen on the criticism.

In this context, I was wondering, if there is a standard extension for
Markdown files, because that would be a convenient indicator for converters
and other scripts to identify the source type automatically.

I can live with the facts and I don't see it as my mission to enforce a
standard. But maybe the Markdown community and authorities should really
reconsider this issue. When it comes to (formal) languages, freedom is no
freedom, but ambiguity. And that never helps, certainly not on the long run.
There are so many great programming languages out there that died of their
plurality of dialects and lack of standardization. Perl's "there are more
than one way to do it" may even be another example for the recipe for
trouble and its own downfall.
I think, even Markdowns own plurality, e.g. that
  _this_
and
  *this*
are identical, is not helping anybody, but only increasing the learning and
reading problems.
Waylan, earlier in this thread, pointed out some arguments against a
standard, but these advantages are minor, in my opinion.

Well, maybe I am a bit carried away, by now. What really started my email
was my wish to thank you for all the interesting answers on my questions.

Yours, Tom


[1]
http://www.bucephalus.org/ElephantMark/elephantmark.php?php=elephantmark.php&title=ElephantMark&css=mystyle.css
[2]
http://six.pairlist.net/pipermail/markdown-discuss/2011-April/thread.html
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Dr. Drang]

On Sun, May 8, 2011 at 7:28 PM, bucephalus org  wrote:
> I think, even Markdowns own plurality, e.g. that
>   _this_
> and
>   *this*
> are identical, is not helping anybody, but only increasing the learning and
> reading problems.

Is anyone really confused by this? Or by the two ways of doing
headers? I doubt it.

I'll bet most people on this list will agree that Markdown's
flexibility is a prime reason for its success. It accommodates what
people are already doing.

--
Dr. Drang
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[bucephalus org]

On Mon, May 9, 2011 at 3:30 AM, Dr. Drang  wrote:

> On Sun, May 8, 2011 at 7:28 PM, bucephalus org 
> wrote:
> > I think, even Markdowns own plurality, e.g. that
> >   _this_
> > and
> >   *this*
> > are identical, is not helping anybody, but only increasing the learning
> and
> > reading problems.
>
> Is anyone really confused by this? Or by the two ways of doing
> headers? I doubt it.
>
> I'll bet most people on this list will agree that Markdown's
> flexibility is a prime reason for its success. It accommodates what
> people are already doing.
>
>
Sorry, but I disagree.
The success of Markdown is just not its flexibility, but its simplicity and
convenience.

There may be one good reason for the double syntax in some of its features
(like  and ), and that is history. If there are communities that
use different standards, then it can be a good choice to import that in a
formal language, because it integrates standard conventions and that is
convenient for (new) users. I am not sure how this worked in case of the
Markdown syntax.

But in a clean design of a new formal syntax, flexibility is a bad choice.
This is what I think I learned by making this mistake myself on several
occasions.

You say, "Is anyone really confused by this? Or by the two ways of
doing headers? I doubt it." Well, I was confused. Of course, the double rule
for say *this* and _this_ is simple and is not that hard to understand. But
I had neither a history or habit with either *this* or _that_. So, I spend
some time on the question, what the best choice would be and which one I
should make my own default. You may say, "whatever you prefer". But this is
what I exactly don't expect from a standard: to be left with this choices.
When people read my markdown and when I read other peoples texts, I rather
want us to use the same conventions.
And more important for me was the other "freedom" I mentioned: that there is
no standard file extension. I did spend one or two hours trying to find an
answer to which extension I should use for my own texts. And not only did it
waste my time, this ambiguity really makes my life more difficult, because
the tools I wrote don't know how to deal with it.

What you call "flexibility" will lead to the same problems, that many
mainstream programming languages suffer from. When they grow from tiny tools
to big systems and communities, people ask for standards. And then, all
these "good style" recommendations need to be agreed upon and have to be
learned on top of the syntax itself. What you call "flexibility" is
counter-productive in standards and as a general feature, it is a
misunderstanding of the way a formal language works in time.

Well, Markdown is a nice design. And, as I said, the few "double standards"
might be well motivated and actually a good choice. And for the rest,
Markdown is not ambiguous in principle. I used the ".markdown" extension in
the past, and I probably stick to the habit until the Markdown community
comes up with a decision and helps me out of my misery. ;-)
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[David Parsons]

On May 9, 2011, at 8:34 AM, bucephalus org wrote:


Sorry, but I disagree.
The success of Markdown is just not its flexibility, but its  
simplicity and convenience.


There may be one good reason for the double syntax in some of its  
features (like  and ), and that is history. If there are  
communities that use different standards, then it can be a good  
choice to import that in a formal language, because it integrates  
standard conventions and that is convenient for (new) users. I am  
not sure how this worked in case of the Markdown syntax.


But in a clean design of a new formal syntax, flexibility is a bad  
choice.


If you want to design a new markup language that looks something  
like

markdown, that's a noble goal.   But I don't think that markdown needs a
"clean" "new" syntax; the existing definition combined with the  
reference

spec defines the language well enough so that there are, what, 20 or so
different implementations that are essentially compatable, most of which
use their own codebases (instead of recoding the original perl mess of
regular expressions in $Language.)

 *People use different characters for emphasis*
 _People use different characters for emphasis*
 /People use different characters for emphasis/

Be thankful that the archaic form of *emphasis  (yes, just one star
at the start of a word) never got popular so there wasn't any sort of
demand that html markup languages support it.   Text markup is going to
be ugly, just because that's now it works.a "clean" "new" syntax  
that

doesn't take how people mark up text documents into consideration is a
syntax that needs to be taken back for revision.


 -david parsons
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[David Chambers]

What you're saying is that Markdown is more of a Perl than a Python. :)

There are other options which provide one and only one way to do a
particular thing, but in my opinion none is as elegant as Markdown.
Rather than view Markdown's flexibility as a design flaw, I'm learning
to embrace it. As with programming, my style changes with time. I like
the fact that this can occur.

Incidentally, Gruber wrote the first Markdown conversion script in
Perl. It's interesting to wonder whether Markdown's syntax would be
stricter if he'd used Python instead.

David
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Arno Hautala]

On Mon, May 9, 2011 at 11:34, bucephalus org  wrote:
>
> Of course, the double rule
> for say *this* and _this_ is simple and is not that hard to understand. But
> I had neither a history or habit with either *this* or _that_. So, I spend
> some time on the question, what the best choice would be and which one I
> should make my own default. You may say, "whatever you prefer". But this is
> what I exactly don't expect from a standard: to be left with this choices.

This is the key. Markdown *isn't* a standard. As defined by Gruber it
is "two things: (1) a plain text formatting syntax; and (2) a software
tool, written in Perl, that converts the plain text formatting to
HTML." The second applies specifically to Gruber's implementation. The
first covers the Markdown community as a whole. Overall, the Markdown
syntax is a standard only in the sense that it has a large number of
implementations that share the same core syntax, while expanding as
desired.

> When people read my markdown and when I read other peoples texts, I rather
> want us to use the same conventions.

In that case, you should communicate with those people and agree to
use the same restricted set. Markdown offering multiple forms of
emphasis markup isn't any different than SHOUTING vice using an
exclamation mark!

> And more important for me was the other "freedom" I mentioned: that there is
> no standard file extension.

If you want a standard file extension, use what Gruber does: ".text".
In my view, there isn't any such thing as a "Markdown document". If
there was, the Markdown syntax would have failed to achieve its goals.
There are *text* documents which are formatted according to Markdown
conventions, but they're still *text*. This isn't quite the same as
HTML, which are text documents that are only meant to be interpreted
as HTML. Markdown is always text, meant to be read as text, with
formatting to convey additional, but non-critical, information.

-- 
arno  s  hautala    /-|   a...@alum.wpi.edu

pgp b2c9d448
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: What does Markdown do with HTML comments? Recommendation on Markdown file extension?

[Seumas Mac Uilleachan]

On 05/09/2011 11:34 AM, bucephalus org wrote:
>
>
> On Mon, May 9, 2011 at 3:30 AM, Dr. Drang  > wrote:
>
> On Sun, May 8, 2011 at 7:28 PM, bucephalus org  @gmail.com > wrote:
> > I think, even Markdowns own plurality, e.g. that
> >   _this_
> > and
> >   *this*
> > are identical, is not helping anybody, but only increasing the
> learning and
> > reading problems.
>
> Is anyone really confused by this? Or by the two ways of doing
> headers? I doubt it.
>
> I'll bet most people on this list will agree that Markdown's
> flexibility is a prime reason for its success. It accommodates what
> people are already doing.
>
>  
> Sorry, but I disagree.
> The success of Markdown is just not its flexibility, but its
> simplicity and convenience.
>
> There may be one good reason for the double syntax in some of its
> features (like  and ), and that is history. If there are
> communities that use different standards, then it can be a good choice
> to import that in a formal language, because it integrates standard
> conventions and that is convenient for (new) users. I am not sure how
> this worked in case of the Markdown syntax.
>
> But in a clean design of a new formal syntax, flexibility is a bad
> choice. This is what I think I learned by making this mistake myself
> on several occasions. 
>
> You say, "Is anyone really confused by this? Or by the two ways of
> doing headers? I doubt it." Well, I was confused. Of course, the
> double rule for say *this* and _this_ is simple and is not that hard
> to understand. But I had neither a history or habit with either *this*
> or _that_. So, I spend some time on the question, what the best choice
> would be and which one I should make my own default. You may say,
> "whatever you prefer". But this is what I exactly don't expect from a
> standard: to be left with this choices. When people read my markdown
> and when I read other peoples texts, I rather want us to use the same
> conventions.
> And more important for me was the other "freedom" I mentioned: that
> there is no standard file extension. I did spend one or two hours
> trying to find an answer to which extension I should use for my own
> texts. And not only did it waste my time, this ambiguity really makes
> my life more difficult, because the tools I wrote don't know how to
> deal with it.
>
> What you call "flexibility" will lead to the same problems, that many
> mainstream programming languages suffer from. When they grow from tiny
> tools to big systems and communities, people ask for standards. And
> then, all these "good style" recommendations need to be agreed upon
> and have to be learned on top of the syntax itself. What you call
> "flexibility" is counter-productive in standards and as a general
> feature, it is a misunderstanding of the way a formal language works
> in time.
>
> Well, Markdown is a nice design. And, as I said, the few "double
> standards" might be well motivated and actually a good choice. And for
> the rest, Markdown is not ambiguous in principle. I used the
> ".markdown" extension in the past, and I probably stick to the habit
> until the Markdown community comes up with a decision and helps me out
> of my misery. ;-)
>
>

The original intent for Markdown was a tool to add formatting to text
without having to use html. As such it relied heavily on the existing
conventions used in email. That is why there is more than one way to add
markup for certain things (emphasis, strong, headers) because there was
more than one way in common use at the time. There were in some cases
more than two or three, and I believe all were considered by John Gruber
and Aaron Swartz as they developed the original syntax. But Markdown is
not a "formal syntax" and was never intended to be. It is not a
replacement for html and was never intended to be. It is a way to
unobtrusively add syntax to text while leaving the text highly readable.
And part of the success of that lies in the flexibility of the syntax.
If I need to emphasise a sentence with asterisks I can use _..._,
otherwise I tend to use *...*. Thus the multiplicity of options for
syntax for me is a feature.

If you need a formal syntax, consider creole. It is almost as
unobtrusive as Markdown.
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss