pozorvlak: This is a test

pozorvlak (

pozorvlak) wrote,
@ 2008-04-29 16:35:00

Entry tags:

beware the geek, computers, meta, perl, programming

This is a test
=pod

... do not be alarmed.

What happened was that I was talking on Reddit with Masklinn about Literate Programming, and s/he wanted to know if there were any systems other than Literate Haskell which allowed for blog posts which are valid code. "Hrmmm," I thought, "I don't see any obstacle to doing that with POD..."

[Yes, my inner monologue does contain hyperlinks. :-) ]

Literate Programming, by the way, is a workaround for the limitations of early Pascal compilers encountered by Donald Knuth when he was writing TeX. The bit everyone remembers is about intermingling code with a description of that code - a program called weave would then produce TeX source, which could be compiled into a beautifully-typeset manual, and another program called tangle would produce highly portable, lowest-common-denominator Pascal source, which could then be compiled into a runnable program. The original WEB system had many other features to enable higher-level programming without compromising portability: most of these are IMHO considerably less necessary with modern languages, and many of the rest are handled by systems such as Doxygen. Anyway, Literate Haskell handles the "intermingling code with docs" bit for Haskell, and POD does a similar job for Perl. Mark Dominus has written an article explaining where POD falls short of Knuth's WEB system (and of Knuth's conception of Literate Programming) - as far as I can see, most of it applies to Literate Haskell too. Knuth's original paper is, well, written by Donald Knuth - obviously it's worth reading! :-)

Anyway, having fulfilled Criterion 1 of Literate Programming (start with a long paragraph explaining what LP is and what it's for, and only then reveal that - shock, horror! The document you're reading is in fact a program!), I should get on with some actual coding.

=cut

print "Hello, Literate World!\n";

=pod

Did'ja see that? I totally embedded some code right in my blog post! Wow. Note that this was the classic "Hello, World" program - by tradition (which in hacker circles has a force greater than physical law and only slightly less than mathematical inevitability), this is the first program you must write with any new system.

Let's do something a bit more interesting:

=cut

while (<>) {
        s/!+/./g; print;
}

=pod

That accepts some text on standard input (and/or any files specified on the command line), and replaces all sequences of exclamation marks with a single full stop. The result is then placed on standard output. I used to have that as a filter on my incoming mail - we had a very excitable JCR committee, who used to send out lots of emails of the form "Massive event happening tonight!!!!!!! Everyone must come!!!!!".

But, uh-oh, there's a problem - see where it says while (<>)? That's actually while (<>), which isn't valid Perl. But if I didn't do that, your browser would think I'd included an empty tag, which would disappear silently when your browser tried to render it - not very helpful. The upshot is that you can't just save this HTML file as witteringmoron.pl and expect it to work - you'll have to cut-and-paste the body of the post (being sure to get the =pod at the top) and save it separately. Sorry about that. But actually, you needed to do that anyway - the interpreter expects to start off in Perl mode, not POD mode, and all the HTML header gubbins isn't valid Perl.

Anyway, let's try it. Copy... paste into a new text editor window... save as witteringmoron.pl... now, open a command-line and type perl witteringmoron.pl:

Hello, Literate World!

Excellent. Now, type some sample input:

This is, like, totally a test!!!!! ZOMG!!!!!!

This produces the output

This is, like, totally a test. ZOMG.

Which is correct, albeit somewhat deflating. You can stop the program from asking for more input by typing Ctrl-D.

So, yeah, you can write blog posts in POD, subject to the above limitations. Woo!

Right, back to work.

(Post a new comment)

	totherme 2008-04-29 04:07 pm UTC (link)
	Is tradition really so important in hacker circles? Should it be? (Reply to this)(Thread)

	necaris 2008-04-29 04:53 pm UTC (link)
	Some programming traditions are important for their hilarity ;-) (Reply to this)(Parent)

	pozorvlak 2008-04-29 05:38 pm UTC (link)
	I was in a slightly silly mood when I wrote this, as you can probably tell... Seriously, though, the role tradition plays in computing is an interesting one. For such a young field (and one which is constantly reinventing itself), it certainly has a lot of mythology. (Reply to this)(Parent)

	necaris 2008-04-29 04:52 pm UTC (link)
	I imagine you could do something similar using Python doctests...? (Reply to this)(Thread)

probably, but
(Anonymous)
2008-04-29 05:06 pm UTC (link)

Python doctests have several issues:

it wasn't created for code but for tests, so you have to specify all the ouput lines too (nice for verification, annoying for the writer of a blog post/demo)

if I remember well it requires an indentation before the prompt, which will be a pain to render in your post (you'll have to e.g. wrap everything in <pre> and add an indentation to every code block)

Most Python tools don't cope well (there's Emacs doctest-mode but that's pretty much it) with doctest code

and since it wasn't created for code, I don't know how it scales with complex classes definitions & stuff

You could probably use it, but it wouldn't exactly be straightforward.

(Reply to this)(Parent)(Thread)

	Re: probably, but necaris 2008-04-30 08:10 am UTC (link)
	Good points -- a pain in the neck, as you say, and probably wouldn't scale at all, but within the realms of possibility. Not something I'll be trying any time soon, in any case ;-) (Reply to this)(Parent)(Thread)

	Re: probably, but pozorvlak 2008-04-30 09:45 am UTC (link)
	Ah, go on. You know you wanna :-) (Reply to this)(Parent)

	michiexile 2008-04-29 08:16 pm UTC (link)
	Doesn't that email filter make it difficult for you if people write you with list-indexing Haskell code (!!) or with arcane combinatorial discussions (involving the factorial of the factorial of something)? Or, actually, it would seem that the factorial alone would also get killed if I read my regexps right. (Reply to this)(Thread)

	pozorvlak 2008-04-29 08:23 pm UTC (link)
	I had a key bound to "read raw text" - if I encountered those situations, I'd use that. But I haven't needed the filter for a few years, anyway :-) (Reply to this)(Parent)

You simply do not understand it

anonym_mouse
2008-05-06 11:13 pm UTC (link)

Holy cow..

[1] You do not understand the idea of literate programming.

It does NOT stand for "voluble commentaries", and POD has nothing to do with it.
Moreover, a program without commentaries can be written in the "literate" style, as defined by Knuth (although that would not be natural or very useful), and vice versa, a program with tons of commentaries and code samples can have nothing to do with literal programming.

The MAIN IDEA is that you can PROGRAM IN HUMAN LANGUAGE, and your ad-hoc invented phrases become precise "variables" or, to be even more precise, MACROS that will expand to valid code.
The "untangle" program will extract this code, in correct machine order, while you are allowed to write in logical order, the order of proper thinking

[2] You miss even the basic usage of "POD" in perl.
It does not escape code unless the first symbol(s) on the line is/are blanks or tabs
So, move your code one space to the right, and POD will preserve it as code.

..without becoming a "literal programming" tool, of course

(Reply to this)(Thread)

	Re: You simply do not understand it anonym_mouse 2008-05-06 11:20 pm UTC (link)
	.. and to think only that the first reference you gave in your text explains exactly this point, that POD has nothing to do with literal programming ... oh, well.. (Reply to this)(Parent)(Thread)

	Re: You simply do not understand it pozorvlak 2008-05-07 09:00 am UTC (link)
	I'm glad you spotted that and saved me the effort of pointing it out to you. Though re-reading the text, I see that I could have made this point clearer: I'll fix that now. (Reply to this)(Parent)

Re: You simply do not understand it
pozorvlak
2008-05-07 09:27 am UTC (link)

[2] Actually, it's you who's misunderstood POD usage. Indentation is how you include code samples in documentation: it's the equivalent of a <pre> block in HTML. What I want to do, however, is include actual running code, for which you use =cut

The difference is easy to see. Save the following as podtest.pl:

=pod

Here is some documentation, including an example C<print> statement:

    print "This line will not be printed.\n";

=cut

print "This line, however, will be printed.\n";

Run perl podtest.pl. Note that the second "print" statement is called, but the first one isn't. Now run pod2html podtest.pl > podtest.html and open podtest.html in your browser. You should see the following:

Here is some documentation, including an example print statement:
    print "This line will not be printed\n";

BTW, "literate" != "literal".

[Sorry to spam your inbox: stupid markup errors]

(Reply to this)(Parent)(Thread)

Re: You simply do not understand it
(Anonymous)
2008-05-07 01:45 pm UTC (link)

(a) so you understood what they typo meant - and corrected it, ok.

(b) concerning your idea - I still do not understand what would prevent you from
escaping "=pod" and "=cut" mark-up with C<=pod> etc. in the source code, then processing it with pod2html, and finally either saving your html page as text - or, if multicolumn format and stupid embellishments do not produce a plain text file, simply copy-passting THE WHOLE article column, and running it as perl src??

Why do not you use the C<bla-bla> ?

(Reply to this)(Parent)(Thread)

	Re: You simply do not understand it (Anonymous) 2008-05-07 01:48 pm UTC (link)
	i.e. if you do not indent the paragraph POD should treat it as text and escape to correctly display in html, I mean. Just escape the POD start-end marks (Reply to this)(Parent)

Re: You simply do not understand it
pozorvlak
2008-05-07 02:32 pm UTC (link)

You seem to have misunderstood my intentions. I was not trying to write a blog post using POD markup on the backend. That would be trivial. What I was trying to do was write a blog post which the reader can copy-and-paste into a Perl script and run without further interference. This practice is common in the Haskell community, and now I've shown that it is indeed possible with POD and Perl - copy and paste this blog post and invoke perl on it as described to see this.

If I had been trying to use POD as a markup language, then yes, I could have escaped the =pods and =cuts with C<...>, and indented all the code by four spaces so it looked right. Running that through pod2html would then have resulted in HTML output that, once copied-and-pasted, ran as an executable Perl script. The pipeline would then have been POD->HTML->POD. But that's not what I did, and it's not what I was trying to do: instead, I wrote the HTML-that-would-become-POD directly.

(Reply to this)(Parent)(Thread)

Re: You simply do not understand it
(Anonymous)
2008-05-07 05:58 pm UTC (link)

=pod

This is my section ()

=cut

  opendir(FAQDIR,$faqdir)|| die "can't open $faqdir $!";
  my @faqs = grep /faq/,readdir FAQDIR;
  closedir FAQDIR;
  foreach my $faq (@faqs) {
      open(FAQ,"$faqdir/$faq")||die "can't $!";
      while (<FAQ>) {
          if (s/^=head2($pattern)/$1/io) {
              print "$faq:$_" ;
              if ($opt_f) {
                  while(<FAQ>){
                      last if m/^=head(?!$pattern)/io;
                      print;
                  }
              }
          }
      }
      close FAQ;
  }

=pod

More of your inane shit ()

If I had been trying to use POD as a markup language, then yes, I could have
escaped the =pods and =cuts with ..., and indented all the code by four
spaces so it looked right. Running that through pod2html would then have
resulted in HTML output that, once copied-and-pasted, ran as an executable
Perl script. The pipeline would then have been POD->HTML->POD. But that's
not what I did, and it's not what I was trying to do: instead, I wrote the
HTML-that-would-become-POD directly.
=cut

(Reply to this)(Parent)

	If so, how did I generate it a second ago? (Anonymous) 2008-05-07 06:00 pm UTC (link)
	If so, how did I generate it a second ago? From a text POD with one command? (Reply to this)(Parent)

Re: You simply do not understand it
(Anonymous)
2008-05-07 06:07 pm UTC (link)

i.e. I ran pod2html pod.example >pod.example.html and then copied the html source into the LJ comment window.

LJ allows simple HTML markup in commentaries, it looks slightly better if I open it in the browser as pod.example.html

Now, if I copy-paste the column with my mouse (or save as text, if multicolumn formatting won't get in the way), I'll get a valid perl file with text inside POD sections

Now, if you look at its source, you'll see that POD _did_ escape all angle brackets in the perl code snippet etc.

So can you turn on your head for a moment and remember what a simple escape is, and that in POD it is C<....> ??

(Reply to this)(Parent)

	HTML-that-would-become-POD directly. (Anonymous) 2008-05-07 06:32 pm UTC (link)
	"HTML-that-would-become-POD directly" Now, where's the problem with that ??? Go to the "noweb" page, get one example of literate "wc" prog marked up with html, and run it through the "tangle" and "weave" utilities. I think you are trying to force an unlocked door, as they say. I still do not get what your difficulty could be (Reply to this)(Parent)(Thread)

	Re: HTML-that-would-become-POD directly. pozorvlak 2008-05-07 06:40 pm UTC (link)
	My difficulty is that my blog is infested by idiots who insist on telling me things I already know at great length. Begone. (Reply to this)(Parent)(Thread)

	rrrright. (Anonymous) 2008-05-08 02:07 am UTC (link)
	.. and this is from someone who believes he fulfilled the first precept of literate programming because he wrote a chatty first paragraph?! hehehe (Reply to this)(Parent)

Mini Sitemap:

Username:		Create an Account Forgot your login? Login w/ OpenID
Password:
	Remember Me
	English • Español • Deutsch • Русский…