*NewLeaf* Page Layout Tools

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 73

What NewLeaf is not¶

Sorry, Toronto Maple Leaf hockey fans, this "NewLeaf" is not the team’s saviour to lead the team from out of the basement and into the playoffs.

What then is NewLeaf?¶

NewLeaf is a clever piece of software that greatly simplifies report writing in APL. With NewLeaf you can produce desktop-publishing results and even prepare output ready for the Internet.

NewLeaf is available in Dyalog APL/W and APL+Win versions. I use NewLeaf with Dyalog APL/W versions 7.2.7 and 8.0.11 for Windows 3.1 and Windows95 respectively. NewLeaf has been available in beta since the spring of 1996 from the Causeway Web site. It was officially released last August and an update was made available last November. I tested NewLeaf on a variety of personal computers. At the office, I use APL/W in a WIN-OS/2 session on a Pentium Pro-200 running the new, voice recognition and Java-enabled OS/2, version 4.0 (an impressive new release of this under-appreciated O/S). At home, I have a 486-33 running Windows95 and a 386-25 PC running OS/2 3.0. As expected, NewLeaf runs noticeably better on faster processors. NewLeaf on my 386 machine is usable but a little slow.

NewLeaf is a product from Causeway Graphical Systems Ltd. The two men behind Causeway are Adrian Smith and Duncan Pearson. Last spring Adrian spoke to the Toronto APLSIG about NewLeaf at a meeting which I attended.

NewLeaf ships as a single disk with three files. Those files include a workspace, a new APL font and an excellent help file. You also get a 100 page manual co-written by Adrian and Marc Griffiths. NewLeaf sells for £400. Updates and bug fixes are available from the Causeway Web site.

As we all know, printing in APL has never been the language’s greatest feature. The lack of easy, good reporting features has not helped APL. Dyalog’s APL/W offers a GUI Printer object that can produce good-looking output but it requires a fair bit of programming. Before NewLeaf, I would almost always bypass printing a report directly in APL. Instead, I copied my output to the clipboard or DDE out my variables to something like Lotus for final presentation and printing. NewLeaf offers an APL solution.

In Dyalog APL, NewLeaf takes advantages of "namespaces" which are unique to APL/W. Namespaces allow you to store groups of functions, variables and other objects in separate sub-workspaces All the NewLeaf code is contained in these namespaces. You can simply copy in the entire workspace or just the individual namespaces as required. Output from NewLeaf can be printed directly to your printer or you can save it in a workspace, component file, Postscript format, Encapsulated Postscript format or as a Windows metafile. Alternatively, output can be copied to the Windows clipboard as a bitmap or metafile and pasted into another application.

Instructions are included on how to convert your output into HTML format for Internet publishing. A separate HTML namespace is included but is only experimental at this time. If you have Adobe’s Distiller software you can use the output from NewLeaf to create a PDF file (Portable Document Format) that can be viewed with Adobe Acrobat readers.

NewLeaf is described as a frame-based publishing tool. Everything revolves around what you put into a frame. Every page contains a least one frame. You can create as many frames on a page as you like. Once you have established a page layout you then place or flow text as paragraphs (ie. nested arrays) into the frame. Besides flowing in text you can insert tables, Rain graphs, fixed text and bitmaps. Under program control you can direct specific APL variables into a frame.

Tables are easily handled in NewLeaf. NewLeaf offers two table functions. The first one, leaf.table.List handles simple columnar reports. If you want more control over formatting and cell wrapping you use the leaf.table.Spread function. You have control over grid lines and horizontal and vertical rule lines. For tables with numbers you can format each column with a left argument to function leaf.table.Qfmt that is the same specification used with ⎕FMT.

As stated earlier, the quality of the output is excellent. NewLeaf was designed to work with text, tables and Rain graphs. You can quite easily produce short or long reports. You can also design your output to look like letters, invoices, reports, multi-column newsletter styles and even books. The APL newsletters produced by other APL SIGS like the Toronto APLSIG "Gimme Arrays", a three column newsletter, can now be produced in NewLeaf.

To produce a report you write a function containing lines of code referencing the appropriate NewLeaf functions. NewLeaf functions set properties that control the look of your output. Properties not referenced will assume their default settings. To produce a simple report, here is a sample set of code which would produce an attractive report with a heading, some text paragraphs and a table:

leaf.Use ''                           ⍝ Start with default page layout
leaf.Style 'Heading'                  ⍝ Take the supplied style
leaf.Place 'Here is the Heading'      ⍝ Assume it will not wrap
leaf.PopStyle                         ⍝ Revert to previous style
leaf.Flow (text)(text)(more text)     ⍝ Wrap paragraphs of text
leaf.table.Set ('Coltitles' 'text' 'text')  ⍝ Set up table header
leaf.table.Spread matrix              ⍝ Do the report
PG←leaf.Close                         ⍝ Saves Postscript code to variable PG
PostScrp.View PG                      ⍝ Preview the result

As you can see from the above example this is how NewLeaf essentially works. For those not familiar with APL/W the period you see in "leaf." is how APL/W namespaces are referenced within the workspace. NewLeaf offers a host of properties you can set. Setting properties can either be done by direct reference to individual functions or you can group properties by using the leaf.Set function. If you have "paragraphs" or table formats that you wish to re-use you can save these customized styles and call them when you need them. You can save your own paragraph styles.

NewLeaf does not offer an integrated GUI interface but it does include some GUI tools. To start with, you can create customized page layouts with the page layout designer (Layout.Design). This tool assists you in defining and placing the frames on a page. You can save these layouts as a variable and re-use them later. This designer is quite powerful and can do most of your report design. In addition to creating frames, the designer has features for aligning frames properly and for defining other page properties such as the page size, orientation, page numbering, placeholder etc.

Another NewLeaf GUI tool is the Viewer. This function allows you to view the report on your screen. The viewer allows the user to print, zoom in and out or scroll through multi-paged reports. This tool is very useful and displays your output in an attractive and professional style. The viewer can be easily integrated into your application as a view before you print facility.

A third GUI tool, still under development, is a debug feature that shows the creation of your report as each NewLeaf statement is executed. I found this tool very helpful in seeing the build- up of your report. It is especially useful when something unexpected happens in your report.

A key feature of NewLeaf is the ability to include Rain graphs. Rain is separate Causeway product, written again by Adrian, that produces high-quality business graphics. A shareware version ships with APL/W. The latest version has a similar namespace design to NewLeaf. To get the documentation or to upgrade to a more powerful version, called "RainPro", you need to purchase it separately. I will be reviewing RainPro next issue. For now, any graph produced by Rain or RainPro can be inserted into a NewLeaf frame. NewLeaf will automatically fit the graph into the frame you have defined for it.

NewLeaf can handle small and large volume reporting. By default, NewLeaf will hold the report as a variable in your workspace. This is fine when the report is relatively small but it is not very efficient when the report gets larger. The solution is to hold the report’s pages as a component in a component file. You can also specify the report to be spooled to a file which is outside the workspace. The viewer tool can still access the resulting report.

NewLeaf vs other Reporting Tools¶

Both APL/W and APL+Win can support VBX and OCX add-ons. Therefore they both can use reporting packages written for Visual Basic such as Crystal Reports, ReportSmith and others. These packages offer more features than NewLeaf but they are more difficult to use because of the lack of documentation for the APL programmer. NewLeaf has the advantage of being written in APL and therefore uses APL concepts (i.e. nested arrays, matrices etc.).

Conclusion¶

If you purchase NewLeaf, I recommend you work through the tutorials contained in the manual and examine the sample functions that ship with NewLeaf. The help file is also an excellent reference.

Error checking could use some improvement. Sometimes an error occurs (not often). When it does, you a get a deeply nested series of functions displayed where the error occurs. As you get more familiar with NewLeaf you get better at deciphering the error. This can be frustrating if you are a new user. Sometimes you have to experiment a bit to get around errors. Sometimes the error occurs is because you are setting a property in the wrong order.

I would like to see more extensions that follow the Dyalog GUI so that NewLeaf essentially allows you to do WYSIWYG output. Multi-level Row titles for example are now a feature of the APL/W grid object. Adrian has already included basic HTML support. I look forward to seeing this feature enhanced further. Another suggestion relates to table formatting. I would like to be able to control individual row as well as column formatting. In fact individual cell attribute specification would be a useful extension. I know Adrian plans to address these issues and add other enhancements with future releases. He requests and is very responsive to suggestions.

Overall, I rate this product an 8.0 (out of 10). There is no doubt it fills a valuable role and void in APL programming. I have not covered all the functionality already in NewLeaf and more is sure to come. I can easily recommend this one for anyone wanting to do some serious report writing in APL.

More information is available about NewLeaf and other Causeway products by visiting their Web site at:

http://www.causeway.co.uk
E-mail: causeway@compuserve.com