Re: CodeDown = Markdown as the universal language for program documentation
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 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. 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. Respectfully, Sherwood of Sherwood's Forests Sherwood Botsford Sherwood's Forests -- http://Sherwoods-Forests.com 780-848-2548 50042 Range Rd 31 Warburg, Alberta T0C 2T0 On Mon, Apr 11, 2011 at 10:17 AM, bucephalus org bucephalus@gmail.comwrote: 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 for a standard tool to write some docs, but I was overwhelmed by phpDocumentor. In the past, I often used Perl's POD to write tutorials for some of my programs, and that always did a good job. But a while ago I discovered Markdown, and I found that even more convenient and intuitive. I thought, it would be very easy to use that as the format for literal programming in PHP: by a simple modification of the usual comment delimiters /* ... */ and // in PHP, these comments would become designated blocks for Markdown comments or delimiters for source code parts, that would appear in the documentation. The possibility these literal code blocks is an essential part of Donald Knuth's literal programming concept, and most standard documentation tools are not even capable of realizing that. In a first conversion step, these blocks would turn into Markdown, and in a second conversion step, the Markdown is converted to HTML. phpToMarkdown markdownToHtml PHP source code -- Markdown -- HTML For the markdownToHtml function, I used Michel Fortin's PHP Markdown, so my actual converter is a pretty small script. I called it ElephantMark (see http://www-bucephalus-org.blogspot.com/2011/01/elephantmark.html) and the according script is its own documentation. This approach can be used for any mainstream programming language. My current favorite is Haskell, and I wrote a HaskellDown module, that does similar things for Haskell. The main converter is just a composition of two functions haskellToMarkdown markdownToHtml Haskell source code - Markdown HTML For the markdownToHtml part I used the very powerful Pandoc module, written by John MacFarlane. This week, I'll give a talk about it on a meeting of the Dutch Haskell User Group, and I intend to publish it, as soon as possible. During the preparations for the talk, I thought I should call the whole idea CodeDown, including Php(Code)Down as the CodeDown for PHP, PythonCodeDown as the CodeDown for Python, etc. There could even be a general CodeDown tool, that does the conversion for all these particular languages alltogether. But before I put any more work into this project, I would like to find out, if there is really a general interest or support for this idea. Please, don't spare on your comments, answers or questions. Greetings, Thomas (bucephalus.org) ___ 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
Re: CodeDown = Markdown as the universal language for program documentation
Check out Jeremy Ashkenas https://github.com/jashkenas's
doccohttp://jashkenas.github.com/docco/.
Truly beautiful.
David
On 11 April 2011 13:32, bucephalus org bucephalus@gmail.com wrote:
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.org@
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
Re: ol start with a specific number?
On Wed, Apr 6, 2011 at 11:34 PM, Aristotle Pagaltzis pagalt...@gmx.de wrote: * Waylan Limberg way...@gmail.com [2011-04-07 04:15]: I'm not opposed to adding this, but I noticed that no other implementation (of those on Babelmark) implements this by default (not counting Pandoc's extended mode). I haven't checked if other implementations offer this as an option. John’s reason was that the `start` attribute was deprecated in HTML 4 Strict. That's why I'm so fond of Markdown implementations that support inline attribute lists (IALs) or similar, since all you need to do arbitrary styling on the CSS layer is a hook. kramdown [1], my favorite, borrowed IALs from Maruku [2] to nice effect. I don't use inline attributes often, but they're a lifesaver in certain spots. But because of my recent addiction to hyde [3] I find myself using python-markdown a lot, so either write one-off post-processing instructions to insert a hook or rely on `markdown=1`. (BTW, python-markdown honors `markdown=1`, but doesn't strip the attribute from output -- though post-processing fixes this, too.) IMO, any elegant facility for specifying arbitrary attributes inline solves not only the list-numbering problem but a raft of others. LQ [1]: http://kramdown.rubyforge.org/syntax.html#inline-attribute-lists [2]: http://maruku.rubyforge.org/proposal.html#attribute_lists [3]: https://github.com/lakshmivyas/hyde -- Lou Quillio http://quillio.com/ pub...@quillio.com ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Email Obfuscation Techniques
On Tue, Feb 1, 2011 at 10:43 AM, Arno Hautala a...@alum.wpi.edu wrote: The other thread brought to my attention that only the email syntax obfuscates mailto links. Plus, while the entity encoding technique probably fools some scrapers, I doubt it's all that effective. Incredibly, it's still very effective. Back when I kept a personal site with actual content, I kept an entity-encoded mailto: link to assw...@quillio.com on all pages. For maybe eight years (up until about four years ago), that alias never received a message. I still use entity-encoding mailtos on public sites and don't have the impression that they're scraped. I think the harvesters are all about low-hanging fruit, and decoding is still more expensive than it's worth. Might change some day, but doesn't seem to have -- yet. LQ -- Lou Quillio http://quillio.com/ pub...@quillio.com +1 518.285.0003 (gVoice) ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
