Code blocks in blockquotes
According to John Gruber's syntax page
http://daringfireball.net/projects/markdown/syntax#blockquote
it is possible to nest a code block in a blockquote.
But Markdown.pl 1.0.1 shows some strange behavior in this respect.
Let me take the following text example (I use `***BEGIN**` and `***END***`
as delimiters for the examples):
***BEGIN***
This is a block of code in a blockquote:
function hello = {
begin
begin
begin
return Hello world;
end
end
end
};
Thank you for your attention.
***END***
A Markdown.pl conversion returns this:
***BEGIN***
pThis is a block of code in a blockquote:/p
blockquote
precodefunction hello = {
begin
begin
begin
return Hello world;
end
end
end
};
/code/pre
/blockquote
pThank you for your attention./p
***END***
But the `begin...end` blocks should be indented by two more spaces, each.
The result should have been this:
***BEGIN***
pThis is a block of code in a blockquote:/p
blockquote
precodefunction hello = {
begin
begin
begin
return quot;Hello worldquot;;
end
end
end
};
/code/pre
/blockquote
pThank you for your attention./p
***END***
This last result is in fact, what I obtain with Pandoc 1.8.1.1.
There is also a weakness in the syntax explanation for these blockquotes,
which left me puzzled for a while and caused some trouble in a program I am
working on. The definition says that `` is the blockquote symbol, where in
fact, it is ` `, i.e. a greater-than plus a space.
For the nested code this means, that we have to start the line with `` and
5 spaces, at least. 4 spaces are not sufficient, although this is what the
definition suggests.
___
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?
On Mon, May 9, 2011 at 3:30 AM, Dr. Drang drdr...@gmail.com wrote: On Sun, May 8, 2011 at 7:28 PM, bucephalus org bucephalus@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 strong and h1), 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
What does Markdown do with HTML comments? Recommendation on Markdown file extension?
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 !-- blablabla -- 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: CodeDown = Markdown as the universal language for program documentation
Hi Bob, hi Waylan, There seems to be no end in good news I definitely need to study all that. Thank you very much! What I like in Markdown, compare to other lightweight-markups and in this context of program documentation, is the two little, but very useful features: backticks around a phrase turn it into code (i.e. `f(n)` turns into codef(n)/code) and the indentation of tabs or four spaces turns a code block into precode.../pre/code. This is probably the most convenient markup for inline and block code, one can imagine. Even more natural than the LaTeX $...$ for inline and $$...$$ for block code. On Tue, Apr 12, 2011 at 4:52 PM, Waylan Limberg way...@gmail.com wrote: On Tue, Apr 12, 2011 at 9:04 AM, Rob McBroom mailingli...@skurfer.com wrote: On Apr 11, 2011, at 5:46 PM, David Chambers wrote: Check out Jeremy Ashkenas's docco. Truly beautiful. People might also be interested in appledoc, which uses Discount to parse comments. There is also Apydia [1], which uses Python-Markdown (or textile or reStructuredText) on Python code. However, the really powerful documentation library in Python (also supports C/C++ with other language promised to be coming) is Sphinx [2]. Unfortunately, is uses reStructuredText, not Markdown. Now, if someone created a similar tool that used Markdown, that would be something. The great thing about Sphinx is that while is can extract comments from the source, it is primarily meant to write documentation separate from the source - which should almost always be a projects primary documentation. The automatically-generated-from-source reference should usually be in addition to the primary documentation. At least, that is if you want a well documented project. [1]: http://apydia.ematia.de/index.html [2]: http://sphinx.pocoo.org/ -- \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: CodeDown = Markdown as the universal language for program documentation
Hi Sherwood,
Thank you very much for your interest and reply!
On Mon, Apr 11, 2011 at 9:05 PM, Sherwood Botsford sgbotsf...@gmail.comwrote:
Interesting concept, but I think you have it partially reversed.
You want php - codedown - web
I think it would be better:
codedown - php
codedown - markdown - web
I am not sure, if I understand what you mean. But I am under the impression,
that maybe you don't understand what the general idea of CodeDown is. There
is not separate code called CodeDown, that could or should be translated
into PHP or Markdown. There is only the source code of a particular given
programming language, say PHP.
Consider the following simple script, called `example.php`, comprising the
following code
?php
/*
tripleThis($n) returns the three-fold of the given number $n.
*/
function tripleThis ($n) {
return 3 * $n;
}
?
This is plain standard PHP, with one comment between /*...*/.
I can run this through my ElephantMark converter, like so
php elephantmark.php example.php
and that returns an empty HTML document, pretty much like this
html
body
/body
/html
You can also run the example.php script itself and use the triple()
function, as usual with PHP!
The thing is, that a little modification of the script (in fact, there are
three simple syntax rules), turns it into a potential self-documentation of
the script. But note, that the script as PHP script is totally unchanged!
For example, by turning the ordinary command /*...*/ into what I called a
Markdown block /*** ... ***/, allows us to apply proper Markdown (as a
super-set of HTML). And putting the function definition between two lines of
// // // makes that part a literal block.
So our modified example.php is now say
?php
/***
# A nice function
`tripleThis($n)` returns the three-fold of the given number `$n`.
Its implementation is as follows:
***/
// // //
function tripleThis ($n) {
return 3 * $n;
}
// // //
?
If we now run the same command
php elephantmark.php example.php
the output will be a HTML document
html
body
h1A nice function/h1
p
codetripleThis($n)/code returns the three-fold of the given number
code$n$/code.
/p
p
Its implementation is as follows:
/p
precodefunction tripleThis($n) {
return 3 * $n;
}
/code/pre
/body
/html
So this is a HTML document generated from the PHP source, which is thus
both, a PHP script and its own documentation.
(I left away the intermediate step, that the script is first translated into
Markdown, and that is then translated into HTML. But the normal user will
not need this intermediate Markdown step.)
One of the weaknesses for most programming is that people postpone writing
the documentation.
In one of the few programming courses I had, the instructor had us write
the user manual first. THEN write the top level description of the program,
including documenting the algorithms. ONLY then could we write the
program. After we had to correct the previous levels.
This is exactly the way I personally use my ElephantMark (or PhpCodeDown)
all the time! Both the PHP program and its HTML documentation can grow
gradually and simultaneously, and both have the same single source file!
There is a lot of merit in this for anything that is too complicated to fit
into a single file.
In addition this approach requires no changes to markdown.
Codedown then only has to recognize a different commenting style for
whatever language you are using, which I think would make it quick to write.
I am not sure again, if I understand this last part. But maybe, it only
makes sense in your interpretation.
Thank you again, Sherwood, for your comment.
I think, for people knowing Markdown, the CodeDown idea is all too simple:
you just need one, two, or three syntax rules concerning the modification of
comments in the original programming language. And just that makes it so
universal and easy.
But maybe, it is so simple, that it is too difficult for me to explain.
Greetings,
Thomas
On Mon, Apr 11, 2011 at 10:17 AM, bucephalus org bucephalus@gmail.com
wrote:
Dear Markdown enthusiasts out there!
Sure, I don't need to tell you how great an versatile Markdown is for
writing standard documents.
I think, that it would make a really great universal standard as a
programming documentation language, too, and maybe CodeDown would be a
good title for this approach.
The idea started when I was trying to document some PHP scripts. I need to
use different programming languages for different purposes, but I am not a
full time programmer. The problem is, that for most of these languages, the
standard documentation tools are yet another language on their own, and I
already have difficulties remembering the idioms of the programming
languages. When I was working on the PHP scripts, I was looking
