These "examples" were only used for testing by a former maintainer, and thus 
were removed from the official distribution (2.026). However, I feel that 
they can provide some interesting examples of code, and thus should 
continue to be provided.

SOME OF THESE EXAMPLES MAY NOT WORK (SEE NOTES). USE AT YOUR OWN RISK. THEY
ARE NOT INTENDED TO BE OFFICIAL TEST CASES, NOR ARE THEY WELL DOCUMENTED OR
NECESSARILY EVEN WELL WRITTEN. They are provided as examples of code, and some
(e.g., listing of fonts) may even be useful to you.

Run from parent of examples directory, e.g., perl examples/011_open_update.
Creates output PDF files in examples directory (with exceptions as noted).

Fixing these examples is a low priority task, but I will try to get to it over
time. Meanwhile, fixes, suggestions, and even new (working!) examples from the 
community are welcome.

As of 2.025 (last version tested against)...
(see bug 108987)
tested against 3.003 April 2017
tested against 3.004 July 2017
tested with each release thereafter

=========== broken:

=========== possibly OK:

BarCode.pl       Demonstrate the bar code library, 1 page (11 one-dimensional
                 barcodes). It appears to mostly be there, but some heavy bars 
                 seem to be merging into their neighbors, AT LEAST ON LOW-TO-
                 MEDIUM RESOLUTION screens, and there may be other problems. On 
                 a laser printer the merged or "blotted" lines appear to
                 separate into discrete lines, but MAY still be too close for
                 accurate scanning! My advice is to use the barcode functions 
                 in production code ONLY WITH EXTREME CAUTION AND TESTING FOR 
                 SUITABILITY. Be sure to scan a number of sample bar codes with 
                 production scanner equipment, before deciding that they're 
                 suitable for real use.

=========== successful (produced reasonable looking PDF, and no messages):

 011_open_update  BASE is one page Hello World!. UPDATED is two page, second
                 page is new Hello World! (2). Internal string adds third page
                 Hello World! (3). STRING PDF adds fourth page Hello World! (4).

 012_pages       output pages numbered i - iii, 1, 9, 2 - 8 (generate pages 
                 1 - 8, insert page 9 before 2, insert Front Matter i-iii)

 020_corefonts   latin1 encoding only (actually looks more like Windows-1252). 
                 4 variants most faces
                 one page per font plane (256 characters each), as most fonts
                     have more than 256 glyphs from a variety of encodings
                     (uses automap).
                 command line list of core fonts to display, or entire list
                     by default
                 note that "utf8" (and any other multibyte characters) does not
                     appear to work with core fonts!

 020_textrise    show a line of text with rise of +5 (superscript) and -5
                 (subscript). Also +/- 10 and 20 units.

 020_textunderline  show off textlabel() call with angles, colors, and a
                 variety of underlining.

 021_psfonts     Given one or more Type1 (PS) fonts and their metrics files
                 on the command line, a PDF showing the characters and CID
                 details is produced for each font file.

 021_synfonts    .75 slant, 12 oblique, 4 bold, and small caps variants (where
                 available) of the given core fonts, as available, for 32 core 
                 fonts. Also, a sample page with combined variants.

 022_truefonts   Given one or more TrueType (.ttf) font FILES on the command
                 line, a PDF showing the characters (256 per indicated SINGLE
                 BYTE encoding, default is 'latin1'), the CID details for all
                 the characters in the font, and some ASCII
                 sample text is produced for each file. Note that unlike most
                 of the other example programs, the resulting PDF(s) are in
                 the directory you run the program from, not the examples/ 
                 directory where 022_truefonts lives! OpenType (.otf) fonts
                 also appear to work well here. The first (encoding) page works
                 only with single byte encodings (not UTF-8). The CID list is
                 independent of the encoding, and the sample text is ASCII.

 022_truefonts_diacrits_utf8   similar to 022_truefonts in its inputs and
                 outputs (no CId character dump). times.ttf and tahoma.ttf 
                 (and presumably others) contain the U+0361 combining diacritic
                 used on the second page.
                 'utf8' encoding doesn't work for the first page (dump of 256
                 characters in given encoding), only single byte encodings.
                 UTF-8 input is used for the second page string, and the 
                 encoding is ignored.

 023_cjkfonts    (MyungJo fonts only) the last several hundred characters (2 
                 pages, rotated ASCII) get an undefined value returned by 
                 $font->uniByCId($xo), and so end up being formatted U+???? 
                 to avoid a fatal error. Presumably, rotated text should not
                 have a Unicode number.
                 The Lorem Ipsum text on the last page of some fonts (KozGo, 
                 KozMin, MyungJo) appears to be using the fixed pitch variants
                 of Latin alphabet, rather than proportional.

 024_bdffonts    produces a grid and sample text for a customer-supplied
                 BDF (bitmapped) font.

 025_unifonts    produces a PDF with a segment of an attached PDF-J file
                 (SJIS encoding) rendered in four different Western+CJK font 
                 combinations.

 026_unifont2    a selection of Unicode alphabets and symbols, in several
                 font faces (Helvetica Bold, Times Roman, symbols). Note that
                 the glyph name is printed at an angle, due to its length.

 030_colorspecs  displays 16 pages each of RGB, RGB Gamma 2.2, CMYK, and L*a*b
                 colorspaces, and almost 3 pages of named colors. 16 pages of
                 256 colors each, except named colors. All are sorted from 
                 lower left to upper right (opposite of font pages). Black 
                 (K) = 0 for all CMYK entries, else it would have 256 pages.

 031_color_hsv   displays 7 page subset of HSV colorspace as color wheels.

 032_separation  show color separation (CMYK) grid.

 040_annotation  demonstrate open and closed "text" annotations on a page. Both
                 permit editing of the text, with the "open" annotation 
                 coming up already opened for editing, and the "closed"
                 annotation needing to be clicked on to allow editing. If you
                 make a change to the open annotation, when you exit you will 
                 be prompted to save the changes (you don't have to, unless you
                 want to open the PDF again and see your entry still there).
                 Also show some "markup" annotations on the second page.

 041_annot_fileattach  demonstrate file attachment annotations on a page. Two
                 small files are attached in six different ways (mostly a 
                 variety of icons and their coloring).

 042_links       demonstrate some links from PDF text to other places in a 
                 document, to other PDFs, and to HTML files in browsers.

 050_pagelabels  all 26 pages show "Page Index=n" (0..25). The reader's 
                 thumbnail display is labeled with the appropriate Roman
                 Numerals, etc., and is NOT on the page itself. Note that each
                 time the display format is changed, the page number resets to
                 1 (I, i, A, a).

 055_outlines    take PDF like 012_page's, and add three outlines (bookmarks)
                 to physical pages 1, 4, and 11 (labeled i, 1, 7).

 060_transparency  show writing opaque and translucent text by two methods.

=========== other example material:

Bspline.pl       show off splines which connect all given points.

Content.pl       demonstrate Content.pm graphics and text calls, 5 pages.

ContentText.pl   demonstrate Content-related text call, 10 pages.

RMtutorial.pl    Rich Measham's basic tutorial on using PDF::API2, updated
                 for PDF::Builder.

HarfBuzz.pl      show use with HarfBuzz::Shaper to shape complex scripts as
                 well as ligatures and kerning in Latin fonts.

Rotated.pl       demonstrates how to rotate selected pages

Boxes.pl         demonstrates PDF "boxes".

ShowFont.pl      list glyphs in a font. output varies by font, encoding(s),
                 and font type.

Windows/
  027_winfont  demo Windows registry access
  Win32.pm     glue routine (lib/PDF/Builder/Win32.pm) only used in 027_winfont.
               The Windows routines have been broken at least since Windows 7,
               and the demo wasn't terribly useful, anyway, so it has been 
               removed.
  Notes:
   * Makefile.PL  commented out Win32::TieRegistry prereq
   * examples.bat has been updated to remove Windows test (027_winfont)
   * t/00-all-usable.t has not been changed, as Win32.pm should not be 
      encountered during testing
