On Fri, Jan 11, 2002 at 04:07:22PM -0700, Sean M. Burke wrote:
> [...verbatim sections...formatting sequences...]
While on the topic of verbatim sections, here is something I thinked
with my mind in a city far, far away in another country that uses
loons for money.
Verbatim sections are fundementally broken. Period. They exist as a
formatting construct, but don't really describe much. Furthermore, the
formatting must be perverted to become prepended with whitespace at some
point in order to acquire verbatim behavior. (The ultimate sin of Texinfo,
spontaneously rediscovered in brand new way) As a result, I've always
seen this:
#!/usr/bin/perl
use strict;
as a syntactic sugar for this (modulo leading whitespace):
=begin verbatim
#!/usr/bin/perl
use strict;
=end verbatim
Now, once you get snagged on tagging verbatim sections, it becomes
natural to see many different classes of verbatim text. There is
verbatim text that comes from screen shots, verbatim text that is
Perl code, and verbatim text that is XML, Pod or some other form
of document.
This is akin to what DocBook does with multiple "verbatim environments".
That is, many different tags map to the "verbatim" style, each
denoting a different kind of object within a document. Code gets
labeled one way, which is slightly but importantly different from
screen shots.
So, where does that take us?
Adopting the idea of a general "verbatim environment" from DocBook
(Please put down the Uzi, turn on the safety and remove the clip.
Please. Thank You) we need some piece of metadata to identify
which verbatim paragraphs/blocks are which. Like so:
=begin code
#!/usr/bin/perl
use strict;
=end code
=begin output
Just another Perl hacker!
=end output
Now, with that distinction, the formatter can be coerced into formatting both
as verbatim sections, but another processor can identify which verbatim
sections are code -- and then run 'perl -c' on them. (Try and get DocBook
to find syntax errors in your Perl code!)
Of course, simply labelling verbatim sections as code isn't sufficient.
Most code blocks may be Perl, but what about XSubs? [Inline::]Python? C?
Try this on for size:
=begin code: perl
=begin code: perl6
[basically <code type="perl">...</code>]
Pretty wacky? Well let me mention the word *optional*. Consider this
an extension to core Pod. At first I didn't like =begin/=end for every
sort of block like this, but that has acceptible processing behavior
with standard Pod. So in order to take advantage of this behavior,
an extensible Pod parser/formatter combination will be required here;
something that can glean the extra metadata and do something useful with
it (like lookup that 'code' sections are really verbatim, just like 'output';
perhaps with an =equate semantic, perhaps with =use, perhaps with
=set_the_controls_for_the_heart_of_the_sun).
Back to the original question: how to incorporate formatting sequences
in a verbatim paragraph. Why not just create a new type of verbatim
environment? One that allows and processes formatting sequences?
No change to verbatim paragraphs. No change to copy-and-paste running
Perl code in Pod documents. Just change when you want something to
behave differently.
:-)
> I like fezzes.
Be careful what you wish for.... :-)
Z.
