example Perl code files

[PhilterPaper]

Just some notes on the Perl examples (md1.pl and pdfapi1.pl), after I played with them a bit:

• I find it useful to tell users (in the comments at the top) what the example code is supposed to do. For instance, "md1" outputs markdown text to the terminal (explain the 2 lines expected), and "pdfapi1" outputs 4 lines (explain what each line is supposed to be) to a pdfapi1.pdf file. If nothing else, this can reassure users that the system is working correctly.
• I don't know what use lib "../lib" and use lib "../CPAN" are intended to do, as I'm probably not running in the same directory structure as you are. It seems to run OK in spite of them.
• I generally use Latin-1 (actually, just ASCII) here, and my US English keyboard doesn't have any easy way to enter accented characters (whether Latin-1 or UTF-8). Apparently gViM can be configured to work in UTF-8, but I haven't bothered, since there's really no way to enter non-ASCII except possibly by Alt-nnn. I find it easier to use strings and \x notation, which might be easier for beginners to understand. Anyway, the copy-paste from GitHub turned the A-acute into Latin-1, which the program barfed on until I turned the q{} into "" and \xC1 for the character. Just keep in mind that most US users, especially on Windows, will not be set up for UTF-8 text. That reminds me -- any plans to support HTML-style entities? E.g., allow Á? Rather than writing and maintaining a long list of HTML entity definitions, perhaps prereq HTML::Entities or HTML::HTML5::Entities.
• Presumably anyone using PDF::Builder instead of PDF::API2 will at least know how to change references to PDF::API2 to Builder, but a comment at the top might be useful.
• You might want to reduce the text size a bit, so the full strings will fit, and centered text won't appear to be left-justified. I added <small> around "brown" so that the 4th line would fit, but the 3rd line overflows the page.
• The third line could use a comment/reminder that it's plain API2/Builder "text" output, without any markup.
• The fourth line comment says "right align", but it's actually centered.
• Windows users won't have ITC Garamond installed by default, and need to change those entries to something else. I changed them to DejaVuSerif, as I happened to have it (not sure if it comes with Windows).

None of these things are critical, but you might want to keep them in mind when you develop examples, to avoid unnecessarily frustrating some users, especially those new to Perl or to text processing.

[sciurius]

The example files were initially intended for internal test purposes and not meant to be included in the kit. Sorry for that. Your remarks are very valuable, so I'll probably rework the examples to be more generally useful.