******************************************************************
*                                                                *
*                           !Scribble v.0.1                      *
*                                                                *
*                           G.C.Wraith 03/07/02                  *
******************************************************************

!Scribble is an application for creating PDF files. Once !Scribble
has been 'seen' or filer_booted, you can create PDF files by
describing them in a simple language, Scribble, in a text file.
Changing the file's type to Scrib and double-clicking its
icon will cause the PDF files described in it to be created.

!Scribble uses PDFLIB 4.0.3 (http://www.pdflib.com/) under the
Aladdin Free Public License (version 8, Nov. 18, 1999), with a
Lua 4.0 binding written by Luiz Henrique de Figueiredo. Lua
(http://www.lua.org/) is free and non-proprietary, copyright
of TeCGraf, PUC-Rio. Gavin Wraith put these pieces together
for Risc OS, using GCC 2.95. If you find any bugs please
mailto:gavin@wraith.u-net.com.

A PDF document is created with a command

    <doc_name> = BEGIN <filename>

where <doc_name> is a name consisting of alphabetic
characters, digits or underscores, which does not begin
with a digit. Upper case letters are treated as different
from lower case letters. There is also a list of reserved words
which should not be used. They are

and	break	do	else	elseif	end	for
function	if	in	local	nil	not
or	repeat	return	then	until	while  

A string expression giving a valid full Risc OS filename
is what <filename> denotes. If it is not a literal string
it should be enclosed in parentheses.

A PDF document has associated to it functions called its
'methods'. The syntax is

    <doc_name>:<method_name> (<argument list>)

An important example is the END method which closes the
document and writes it out to <filename> as a PDF file.
It takes no arguments. 

Between BEGIN and END come the essential parts of scribble -
method-calls to describe the document. Here is a scribble
script for creating a single page saying "Hello":

-- Hello in green on an A4 page

x = BEGIN "<Scrib$dir>.^.Hello"

x:set_info ("Creator","Scribble")
x:set_info ("Author","Magog")
x:set_info ("Title","Greeting")

x:begin_page (A4.width,A4.height)  -- note use of format A4

font = x:findfont ("Helvetica-Bold", "host", 0)

x:setfont (font, 24)
x:setcolor ("both","rgb",0,1,0,0) -- green
x:set_text_pos (80,700)
x:show "Hello"
x:END ()

-- end of example

Note that comments begin with "--" and last to the
end of the line.

Other formats provided are:

     A0,A1,A2,A3,A4,A5,A6,B5,Letter,Legal,Ledger.

Knowing about PDF document methods is all you need for
Scribbling. However if you also know Lua you will recognize
that Scribble is a fragment of it, and that the horizon of
possibilities is much wider than that delineated in the
introduction above.

                PDF Document Methods in Scribble
                --------------------------------

Default measurements are in DTP points (= 1/72 inches).
Default coordinates run left to right, bottom to top.
The coordinate system can be translated, rotated,
scaled and skewed but previously drawn objects are unaffected.
Templates are buffers into which often re-used figures can be drawn.
They cannot contain hypertext links.

<pdf_doc>:END ()
   includes an end_page method

<pdf_doc>:begin_page (width,height)

<pdf_doc>:end_page ()

<pdf_doc>:set_parameter (keystring,valuestring)
     keystring = "serial"
                   serial string 
                 "prefix"
                     directory for file searching
                 "resourcefile"
                     filename of resource file
                 "compatibility"
                     "1.2" "1.3" "1.4"
                 "warning"
                      "true", "false"
                 "FontAFM"
                 "FontPFM"
                 "FontOutline"
                 "Encoding"
                 "fontwarning"
                   "true", "false"                 
                 "underline"
                   "true", "false"
                 "overline"
                   "true", "false"
                 "strikeout"
                   "true", "false"
                 "nativeunicode"
                    "true", "false"
                 "fillrule"
                     "winding", "evenodd"
                 "imagewarning"
                    "true", "false"
                 "openaction"
                    "retain", "fitpage", "fitwidth", "fitheight", "fitbox"
                 "openmode"
                    "none", "bookmarks", "thumbnails", "fullscreen"
                 "bookmarkdest"
                 "transition"
                   "split" "blinds" "box" "wipe" "dissolve" "glitter" "replace"
                 "base"
                    base URL
 
                 
<pdf_doc>:set_value (keystring,valuenumber)
     keystring = "compress"
                   0 = no compression,
                   1 = best speed,
                   6 = default value,
                   9 = best compression
                 "pagewidth"
                 "pageheight"
                 "leading"
                 "textrise"
                 "horizscaling"
                 "textrendering"
                    0 = fill,
                    1 = stroke outline,
                    2 = fill and stroke,
                    3 = invisible,
                    4 = fill and add to clip path,
                    5 = stroke and add to clip path,
                    6 = fill and stroke and add to clip path,
                    7 = add to clip path
                 "charspacing"
                 "wordspacing"
                 "textx"
                    text cursor x
                 "texty"
                    text cursor y
                 "font"
                 "fontsize"
                 "capheight"
                 "ascender"
                 "descender"
                 "duration"
                 "CropBox/<@>"
                 "BleedBox/<@>"
                 "ArtBox/<@>"
                 "TrimBox/<@>"
          where <@> is one of llx, lly, urx, ury
                 
string = <pdf_doc>:get_parameter (keystring,modifiernumber)
              keystring = "version"
                          "scope"
                          "underline"
                          "overline"
                          "strikeout"
                          "fontname"
                          "fontencoding"
 
                          
number = <pdf_doc>:get_value (keystring,modifiernumber)
              keystring = "major"
                          "minor"
                          "revision"
                          "pagewidth"
                          "pageheight"
                          "leading"
                          "textrise"
                          "horizscaling"
                          "textrendering"
                          "charspacing"
                          "wordspacing"
                          "textx"
                             text cursor x
                          "texty"
                             text cursor y
                          "font"
                          "fontsize"
                          "capheight"
                               font
                          "ascender"
                               font
                          "descender"
                               font
                          "currentx"
                             graphics cursor x
                          "currenty"
                             graphics cursor y
                          "imagewidth"
                             imageno
                          "imageheight"
                             imageno
                          "resx"
                             imageno
                          "resy"
                             imageno
              
fontnumber = <pdf_doc>:findfont (fontname,encodingstring,embednumber)
  built in font names = "Courier"
                        "Courier-Bold"
                        "Courier-Oblique"
                        "Courier-BoldOblique"
                        "Helvetica"
                        "Helvetica-Bold"
                        "Helvetica-Oblique"
                        "Helvetica-BoldOblique"
                        "Times-Roman"
                        "Times-Bold"
                        "Times-Italic"
                        "Times-BoldItalic"
                        "Symbol"
                        "ZapfDingbats"

   encodingstring =  "winansi"         embednumber = 0,1
                     "macroman"
                     "ebcdic"
                     "builtin"
                     "host"

<pdf_doc>:setfont (fontnumber,fontsize)

<pdf_doc>:show (text)

<pdf_doc>:show_xy (text, x, y)

<pdf_doc>:continue_text (text)

number = <pdf_doc>:show_boxed (text,left,top,width,height,
                                   modestring,featurestring)
             modestring = "left","right","center",
                           "justify", "fulljustify",  ""
             featurestring = "blind", ""                      
                       
<pdf_doc>:set_text_pos (x,y)

number = <pdf_doc>:stringwidth (text,fontnumber,fontsize)

<pdf_doc>:setdash (blackunits,whiteunits)

<pdf_doc>:setflat (flatnessnumber)

<pdf_doc>:setlinejoin (number)
           number = 0  miter
                  = 1  round
                  = 2  bevel

<pdf_doc>:setlinecap (number)
            number = 0  butt end caps
                   = 1  round end caps
                   = 2  square end caps

<pdf_doc>:setmiterlimit (number)

<pdf_doc>:setlinewidth (number)

<pdf_doc>:initgraphics ()

<pdf_doc>:save ()
                   Save state.

<pdf_doc>:restore ()
                   Restore state.

<pdf_doc>:translate (dx,dy)
          Move origin of coordinates.
          
<pdf_doc>:scale (sx,sy)
          Scale the coordinate system.

<pdf_doc>:rotate (angle)

<pdf_doc>:skew (alpha,beta)

<pdf_doc>:concat (a,b,c,d,e,f)

<pdf_doc>:setmatrix (a,b,c,d,e,f)

<pdf_doc>:moveto (x,y)

<pdf_doc>:lineto (x,y)

<pdf_doc>:curveto (x1,y1,x2,y2,x3,y3)

<pdf_doc>:circle (x,y,r)

<pdf_doc>:arc (x,y,r,alpha,beta)

<pdf_doc>:arcn (x,y,r,alpha,beta)

<pdf_doc>:rect (x,y,w,h)

<pdf_doc>:closepath ()

<pdf_doc>:stroke ()

<pdf_doc>:closepath_stroke ()

<pdf_doc>:fill ()

<pdf_doc>:fill_stroke ()

<pdf_doc>:closepath_fill_stroke ()

<pdf_doc>:endpath ()

<pdf_doc>:clip ()

number = <pdf_doc>:makespotcolor (spotname,length)
      length = length of spotname or 0 for null-terminated name

<pdf_doc>:setcolor (typestring,colspacestring,c1,c2,c3,c4)
         typestring = "stroke","fill","both"
         colspacestring = "gray","rgb","cmyk","spot","pattern"

number = <pdf_doc>:begin_pattern (w,h,dx,dy,paintnumber)
           paintnumber = 1  pattern has its own colours
                       = 2  current fill or stroke colour

<pdf_doc>:end_pattern ()

number = <pdf_doc>:begin_template (w,h)

<pdf_doc>:end_template ()

<pdf_doc>:place_image (imagenumber,x,y,scale)

number = <pdf_doc>:open_image (imgtypestr,sourcestr,datastr,
                               length,w,h,components,bpc,paramstr)
             imgtypestr = "jpeg", "ccitt", "raw"
             sourcestr = "fileref", "url", "memory"
                          bpc = 1,2,4,8                 
                               
result = <pdf_doc>:open_image_file (imgtypestr,filename,
                                     paramstr,maskint)
             imgtypestr = "jpeg", "png", "gif", "tiff"
             paramstr = "mask", "masked", "ignoremask", "colorize", ""
 
<pdf_doc>:close_image (imagenumber)

<pdf_doc>:add_thumbnail (imagenumber)

result = <pdf_doc>:open_CCITT (filename,w,h,BitReverse,K,BlackIs1)

number = <pdf_doc>:add_bookmark (text,parent,open)
           open = 0,1

<pdf_doc>:set_info (keystring,valuestring)
            keystring = "Subject"
                        "Title"
                        "Creator"
                        "Author"
                        "Keywords"
                        "Trapped"  = "True", "False", "Unknown"
                        anything apart from "CreationDate",
                        "Producer", "ModDate" = any printable
                        string with no blanks or
                        % ( ) < > [ ] { } / #

<pdf_doc>:attach_file (llx,lly,urx,ury,filename,
                       description,author,mimetype,iconstr)
                       
<pdf_doc>:add_note (llx,lly,urx,ury,contents,title,iconstr)

<pdf_doc>:add_pdflink (llx,lly,urx,ury,filename,
                           pageno,labelstr)

<pdf_doc>:add_launchlink (llx,lly,urx,ury,filename)

<pdf_doc>:add_locallink (llx,lly,urx,ury,pageno,labelstr)

<pdf_doc>:add_weblink (llx,lly,urx,ury,URL)

<pdf_doc>:set_border_style (stylestr,width)
             stylestr = "solid"
                        "dashed"
                        
<pdf_doc>:set_border_color (r,g,b)

<pdf_doc>:set_border_dash (blackno,whiteno)                  
                                   
string = <pdf_doc>:get_buffer ()
          get the PDF document as a string
          
-----------------------------------------------------------------------

