home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / DDF.pm < prev    next >
Text File  |  1999-04-17  |  6KB  |  255 lines
  1. NAME
  2.     Text::DDF -- package for creating Impression Document
  3.     Description Format
  4.  
  5. SYNOPSIS
  6.         use Text::DDF
  7.  
  8.         print ddfencode(@text);
  9.  
  10.         use Text::DDF qw(ddfencode $strict_7bit);
  11.  
  12.         $strict_7bit = 1;
  13.         ddfencode(@text);
  14.  
  15.         $index = new Text::DDF::Style 'Index', qw (index on);
  16.         print $index->StyleWrap( @text );
  17.  
  18.  
  19. DESCRIPTION
  20.     Text::DDF provides subroutines and classes for creating files in
  21.     Impression Document Description Format.
  22.  
  23.     `Text::DDF::ddfencode' converts the array to `DDF', converting
  24.     all instances of '`{'' to '`{\123}''. If
  25.     `Text::DDF::strict_7bit' is true, it will also convert top-bit-
  26.     set characters to '`{\###}'' notation.
  27.  
  28.     `Text::DDF::ddfencode' modifies the array passed, and for ease
  29.     of use additionally returns the array that it converted.
  30.  
  31.   Effects and Styles
  32.  
  33.     `Text::DDF' provides classes for manipulating effects and styles
  34.     - `Text::DDF::Effect', `Text::DDF::Justify', `Text::DDF::Style'.
  35.     The overloaded interface hides the differences in the DDF syntax
  36.     used to turn styles and effects on and off.
  37.  
  38.   Common methods
  39.  
  40.     new <name> ...
  41.         Declare a style/effect with this name.
  42.  
  43.             $bold = new Text::DDF::Effect 'bold';
  44.             $centre = new Text::DDF::Justify 'centre';
  45.             $normal = new Text::DDF::Style 'Normal', qw(
  46.               font Trinity.Medium
  47.               fontsize 12pt );
  48.  
  49.  
  50.         Arguments after the style name are passed to the `Add'
  51.         method
  52.  
  53.             $no_op = new Text::DDF::Effect;
  54.  
  55.  
  56.         defines an empty effect
  57.  
  58.     StyleOn
  59.  
  60.     StyleOff
  61.         Return the `DDF' instruction to turn the style/effect
  62.         on/off.
  63.  
  64.     StyleWrap
  65.         Return the `DDF' turn the style/effect on, the verbatim
  66.         text, the DDF to turn the style/effect off. In array context
  67.         returns an array:
  68.  
  69.             (
  70.              StyleOn(),
  71.              @_,
  72.              StyleOf()
  73.             )
  74.  
  75.  
  76.         In scalar context this array is concatenated
  77.  
  78.     Define()
  79.         Returns the `DDF' needed to defined the style/effect.
  80.         Returns an empty string for an effect, so that a mixed array
  81.         of effects and styles can be `Define'd safely.
  82.  
  83.     Copy <newname>
  84.         Returns a new style/effect clone. (with the same class as
  85.         its parent.)
  86.  
  87.     Print
  88.         Returns a formatted definition of the style/effect. This is
  89.         mostly of use to the `Define' method.
  90.  
  91.         In array context effects return an empty array, whereas
  92.         styles return an array of lines.
  93.  
  94.         In scalar context styles return text of the form:
  95.  
  96.             style  "Normal";
  97.              font Trinity.Medium;
  98.              fontsize 12pt;
  99.  
  100.  
  101.         effects return: effect bold;
  102.  
  103.         NB scalars are terminated by "`\n'"
  104.  
  105.  
  106.   Style Methods
  107.  
  108.     Add Takes pairs of `attribute, value' and adds them to the style
  109.         definition.
  110.  
  111.             $verbatim->Add( qw(spacebelow 0pt) );
  112.  
  113.  
  114.         You can use `AddTabs' and `AddTabComma' to add tabs, but the
  115.         `Add' method will spot lines of the form
  116.  
  117.             Add( 'tabs', 'r18pt 24pt' );
  118.  
  119.  
  120.         and call `AddTabsComma'.
  121.  
  122.     AddTabs
  123.         Takes an array of tabs, and adds them to the style's array
  124.         of tabs.
  125.  
  126.         Tabs are strings such as
  127.  
  128.             r18pt
  129.             25.4mm
  130.             c4pi
  131.  
  132.  
  133.         The available prefixes are
  134.  
  135.     l     Left justify tab (the default if no prefix)
  136.  
  137.     c     Centre justify tab
  138.  
  139.     r     Right justify tab
  140.  
  141.     d     Decimal tab
  142.  
  143.     v     Vertical rule off
  144.  
  145.             $itemlist->AddTabs( qw( r18pt 24pt 72pt 144pt 216pt 288pt 360pt 432pt 504pt ) );
  146.  
  147.  
  148.     AddTabsComma
  149.         Adds a comma separated list of tabs. Literally:
  150.  
  151.             sub AddTabsComma {
  152.             my $self = shift;
  153.             $self->AddTabs( split (/,/, $_[0]) );
  154.             }
  155.  
  156.  
  157.     Get <attribute> ...
  158.         Returns an array of values corresponding to the array of
  159.         attributes passed
  160.  
  161.     Delete <attribute> ...
  162.         Delete values corresponding to the array of attributes
  163.         passed
  164.  
  165.     GetTabs
  166.         In array context returns the sorted array of tabs in the
  167.         format
  168.  
  169.             right 18pt
  170.             centre 3pi
  171.              25.5mm
  172.  
  173.  
  174.         In scalar context joins the list with commas
  175.  
  176.             right 18pt,centre 3pi, 25.5mm
  177.  
  178.  
  179.     DeleteTabs
  180.         Not implemented yet.
  181.  
  182.     PrintTabs
  183.         In array context returns the sorted array of tabs in the
  184.         format
  185.  
  186.             right 18pt
  187.             centre 3pi
  188.              25.5mm
  189.  
  190.  
  191.         In scalar context joins the list with commas and prefixes
  192.         'tabs'
  193.  
  194.             tabs right 18pt,centre 3pi, 25.5mm
  195.  
  196.  
  197.         or returns '' if there are no tabs defined.
  198.  
  199.  
  200. BUGS
  201.   Shortcomings of Impression's DDF interpreter
  202.  
  203.     *   DDF effects don't nest, whereas styles do.
  204.  
  205.             {bold on}Hello {bold on}W{bold}orld!{bold}
  206.  
  207.             {"bold" on}Hello {"bold" on}W{"bold"}orld!{"bold"}
  208.  
  209.  
  210.         produce
  211.  
  212.         Hello World!
  213.  
  214.         Hello World!
  215.  
  216.         respectively if `"bold"' is a style with the `bold'
  217.         attribute.
  218.  
  219.     *   Even in Impression 4.11 the DDF exporter can't cope with style
  220.         names containing `"' characters. Text::DDF::Style makes no
  221.         checks about the validity of characters in the style name.
  222.  
  223.     *   There's no way to `{keepregion}' two adjacent regions.
  224.  
  225.             {keepregion on}Pugh, Pugh, Barney McGrew,
  226.             Cuthbert, Dibble, Grub
  227.             {keepregion}{keepregion on}Time files by when you're the driver of a train,
  228.             and you ride on the footplate there and back again
  229.             {keepregion}
  230.  
  231.  
  232.         won't allow a breaks between the two regions.
  233.  
  234.             {keepregion on}Pugh, Pugh, Barney McGrew,
  235.             Cuthbert, Dibble, Grub{keepregion}
  236.             {keepregion on}Time files by when you're the driver of a train,
  237.             and you ride on the footplate there and back again
  238.             {keepregion}
  239.  
  240.  
  241.         will allow a break between *Pugh, Pugh, Barney McGrew,* and
  242.         *Cuthbert, Dibble, Grub*.
  243.  
  244.  
  245.   Shortcomings of this package
  246.  
  247.     You can't (yet) merge styles.
  248.  
  249.     You can't (yet) merge effects into styles. (This would require a
  250.     hash/function to map effect names into style attributes).
  251.  
  252. AUTHOR
  253.     Nicholas Clark <nick@unfortu.net>
  254.  
  255.