Consultix
Site Menu
Home
Training Services
Public Class Schedule
Training Classes
Clients and Endorsements
Publications
Interviews
About Consultix
B<Magicpoint-EZ> - Preprocessor for "Magicpoint" presentation viewer

NAME

Magicpoint-EZ - Preprocessor for "Magicpoint" presentation viewer

VERSION

v0.02

DOCUMENTATION

The latest documentation on this module is always available at http://teachmeperl.com/magicpoint-ez.html.

DOWNLOADS

At the present time, this program has not yet had its first general release.

It is currently being made available to a few selected individuals for testing, before being released on CPAN (http://cpan.org).

Watch for updates on its status at http://teachmeperl.com/magicpoint-ez.html.

OVERVIEW

SYNOPSIS

First convert the *.mg file to *.mgp using:

 mgp-ez presentation.mg > presentation.mgp

Then run Magicpoint on the *.mgp file as usual:

 mgp presentation.mgp

Explanation

mgp-ez takes a filename like presentation.mg as an argument, and writes output for a presentation.mgp file, for viewing with Magicpoint (see http://www.mew.org/mgp).

The input file is called *.mg to indicate that it is nearly ready to be displayed with Magicpoint, but not quite -- it still needs some additional processing by Magicpoint-EZ before it will become a *.mgp file.

Magicpoint (http://www.mew.org/mgp) is great, and free, and open source, which are all wonderful properties. But for people who want to create non-trivial presentations, it's too cumbersome for efficient use. This program alleviates that problem.

Slides of YAPC 2004 talk on Magicpoint-EZ

The Author gave a talk at the 2004 North American "Yet Another Perl Conference" on this software, whose slides (at http://teachmeperl.com/publications/YAPC.04/mgpez.pdf) illustrate its benefits and provide many examples of its usage.

Demonstration #1: Title Page

The mgp-ez program lets you create a Magicpoint presentation much more easily, and with the option of using many powerful new features.

For instance, consider a page whose basic design is described in the first section below. It's created by storing in a *.mg file the required text, Magicpoint directives, and special mgp-ez tags, shown in the second section. This file is then processed by mgp-ez to create the *.mgp file, shown in the third section, that tells Magicpoint how to lay out the page.

The *.mg file to describe the page only requires 532 characters, but the associated *.mgp file for Magicpoint's use takes 1221! Somebody has to do 130% more work; why should it be you?

Please examine the image of this page, to get the full appreciation for how many stylistic changes are involved, and how nice the result looks. It's available at http://teachmeperl.com/Page1.jpg, or reproduced below, if the your document format supports images.

You may click the image to make it larger. http://teachmeperl.com/mgp_demos/mp4shuap_p2.jpg

1. Basic Design for Title Page

 Title
 Sub-title
 Part II in series
 <IMAGE HERE>
 Author
 URL of Company Web-Site
 Email address
 Phone Number
 Date of Printing

Complication: I want lots of color and font changes on this page!

2. Page Composed in *.mg file

Here's the *.mg file that creates the above page, complete (and replete) with color and font changes, as well as other formatting conveniences that aren't provided by Magicpoint itself. (Described below).

NOTE: As detailed in Sample .mg2mgprc file, style codes starting with C_, F_, and S_ are respectively for color, font, and size changes. The user can also use the actual color-names (e.g., mediumseagreen), if desired, but many will prefer abbreviations for frequently used names. <TITLE>, <SUBTITLE>, <PARTS_TITLE>, <PARTS_TEXT>, and other bracketed words that aren't colors, fonts, or size requests, are user-defined styles, described below.

command% sed 's/^/ /' MG2MGP_demos/mp4shuap_p2.mg

3. Output from mgp-ez that Creates Page

You may have thought the *.mg file looked complicated, but here's what you would have had to type on your own (excluding comments) to get the same result directly with Magicpoint.

command% sed 's/^/ /' MG2MGP_demos/mp4shuap_p2.mgp

Demonstration #2: Source Code

Here's another sample page, which shows off some of the source-code oriented features of mgp-ez, including its ability to render comments differently.

Sample Source-Code Page

You may click the image (at http://teachmeperl.com/mgp_demos/data_validation.jpg) to make it larger. http://teachmeperl.com/mgp_demos/data_validation.jpg

Here's the *.mg file, of 682 bytes:

command% sed 's/^/ /' MG2MGP_demos/data_validation.mg

And here's the corresponding *.mgp file, of 1,918 bytes:

command% sed 's/^/ /' MG2MGP_demos/data_validation.mgp

DESCRIPTION

The purpose of Magicpoint-EZ is to make it much easier for the user to prepare Magicpoint presentations, through use of a highly configurable preprocessor that allows user-defined styles to be easily applied to text.

Styles are defined by adding custom style definitions to the .mg2mgprc configuration file, which is distributed with some sample styles that the Author uses.

Other features make it easier to acquire and prepare text obtained from operating system commands, and control how it is displayed.

For example, recursive file inclusion is provided by the include% directive, line exclusion is provided by skip%/unskip%, special formatting of computer programs is provided by the code% directive, and execution of arbitrary commands and collection of their output is provided by command%.

In addition, tpage% provides support for sections started by "title pages", and npage% for pages within those sections, with (adjustable) default styles in effect and automatic two-part page numbering in the heading.

To make it easier to proofread demonstrations, %pause directives can be filtered out using the command mgp_nopause, so each page can be viewed in one glance.

Implementation

This software is provided as a script called mgp-ez, that relies on a MGPez.pm module that's provided separately. This distribution requires the user to employ traditional Perl techniques to download and install the module before using it, and is provided for those familiar with that routine.

Once the customary Perl-module installation has been accomplished for the mgp-ez version, the scripts are used identically.

Subroutines

The program makes us of many subroutines. Those that start with the prefix "mgp_" are Magicpoint-specific. But there are also others (include, skipper, code_command, etc.) that are of general text-processing applicability, which you may like to use in other applications (e.g., I'm using them in a custom POD pre-processor).

Ultimately, this body of software will be distributed on the CPAN (www.cpan.org), probably under the name Magicpoint::Ez.

This is a preliminary version that is implemented as a single Perl script, which can be invoked under the following names (if it's multiply linked on installation):

skipper, include, po2pod, process_command, process_code, _mgp_force_gaps, add_newlines, mgp_nopause, mgp-emgp-ez

Most importantly, the mgp-ez invocation implements the following cascading filter, so you don't have to go to all the trouble of indenting those lines correctly yourself: 8-}

<INPUT_HERE> include skipper code_command mgp_rm_comment mgp_pages mgp_styles mgp_tinygap mgp_nopause _mgp_force_gaps add_newlines mgp_squeeze_gaps <OUTPUT HERE>

STYLE DEFINITIONS

The user is allowed considerable freedom in choosing names for styles, such as BIG, Bold, Red47, Hot_Pink, Centered_and_Italic, and even such names as $ and _. The current rule is that the first character of a style name must be a letter, digit, underscore, @, ~, *, &, or $. The following characters in the style name are allowed to be letters, digits, underscores, and the +, -, ., and $ characters.

Of course, other special characters could be added to this list on request, if anybody finds this set too restrictive.

A collection of pre-fabricated style definitions is provided in the configuration file, using a naming convention that the Author finds helpful.

For example, the following is a style definition of the color-changing variety, whose leading C_ marking identifies it as such, for switching to gold text:

 C_G
 %fore "gold"

A style definition of the alignment (A_*) variety, for line centering, follows below. It is expressed in a different format, because in addition to specifying how to apply the centering style itself, which is indicated on the first line after the style name, it also defines the "undo style" to be applied thereafter, on the second line:

 A_C
 %center
 %leftfill

This facility is needed because there's no native way in Magicpoint to undo a style change.

Style Tags

In the body of the presentation itself, a style change is requestaed using angled-brackets around a style name, and optionally the text to be rendered in that style (if the "undo" behavior is desired).

For example,

    in the mgp view, all words will be <C_G>golden from here on

To request the automatic application of the "undo" style, you can embed the text to be rendered within the style tag, so long as you have provided the optional undo line in the definition.

(NOTE: The implementation of the "undo" style is not quite mature yet; in particular, there's a problem with extraneous blank lines appearing when two or more appear in a row; I'll fix this eventually.)

For example, given the style definition for centering shown above, the following text would get the results shown below (although the lines might not look centered in this document):

Sample Style Definitions

 A_C
 %center
 A_C-R
 %center
 %rightfill

Input

<A_C>CENTERED NEXT

<A_C-R centered>next more

Output

                                      CENTERED
NEXT


                                      Centered
                                                                           Next
                                                                           More

Additional Sample Style Definitions

 A_C
 %center

Input

<A_C These words are centered> and these will be on a separate line, left-filled

Output

                    These words are centered
 and these will be on a separate line, left-filled

Predefined Styles

Colors

For convenience, hundreds of color names are predefined in the program itself.

If you wish, you can use these directly, and avoid defining any color "styles" of your own. But you need to know the color names before you can use them, so a special invocation of the script is provided for this purpose. For example, to see all the available colors with red in their names, you can do the following:

mgp_grep_colors 'red'

        darkred => #8B0000
        indianred => #CD5C5C
        mediumvioletred => #C71585
        orangered => #FF4500
        palevioletred => #DB7093
        red => #FF0000
        red1 => #FF0000
        red2 => #EE0000
        red3 => #CD0000
        red4 => #8B0000

With this information, you'd be free to use these color styles in your presentation like so:

 Sunset shifts hues from <orangered>orange to<darkred>dark red

Font sizes

Predefined font-size requests ranging from <S_2> (or <S_02>) through <S_5.75> (or S_05.75) to <S_16> in quarter-point increments are provided.

They can be used like so, to make the word BIG relatively large, and shorty relatively small: 

 <S_8>With music by the world-famous <S_14>BIG<S_5>shorty!

Or, with an indented line, the RESET style can be used to automatically reinstate the original size:

        With music by the world-famous <S_14>BIG<RESET>shorty!

Vertical spacing

Predefined style requests that generate vertical-gaps of sizes ranging from <V_03> through <V_95>, also return the vgap setting to DEFAULT_VGAP, but these styles are meant for controlling the vertical spacing between collections of adjacent text lines, whereas these directives merely insert a single vertical gap where requested.

User-Defined Variables

See the configuration file documentation for complete information on defining your own variables, for use in style definitions.

For example, the following style definition changes the foreground color to "turquoise", and then its "undo" style switches to the foreground color that's specified in the definition of FORE_COLOR variable of the .mg2mgprc file, and the font specified as the "default" in the Magicpoint configuration file specified on the first line of the presentation file:

 LHEAD
 %font "bull1", size 6.0, leftfill, fore "turquoise"
 %font "default", fore "$FORE_COLOR", leftfill

The RESET Style

The single biggest problem with Magicpoint, from the point of view of somebody who wants to do intra-line changes of text attributes, is that there's no way to "undo" a change, to revert to the orignal settings.

The RESET style helps with this problem, by allowing the user to request the reinstatement of the default attributes for the current indentation level.

Example

        This is a <ITALIC>Level 1<RESET> heading
                This is a <ITALIC>Level 2<RESET> heading
                        This is a <GREEN><ITALIC>Level 2<RESET><GREEN> heading

Because the first line above is indented by one tab, it will have certain attributes assigned to its text, such as a "bold" font at size 6. The <ITALIC> style request changes the font, and then the <RESET> request reinsates the "bold" font and size 6.

The appropriate "resetting" would also occur for the 2nd-level bullet, although the particulars of font, size, color, etc., might well have been defined differently in the configuration file.

Note however that in the 3rd line, the <RESET> style would undo the changes to both the GREEN color and the ITALIC font, requring the user to reinstate the GREEN color to achieve the effect of undoing only the font change to ITALIC.

DIRECTIVES

The mgp-ez program implements several directives, that enhance or extend those provided already by Magicpoint.

Unlike style definitions, directives don't have undo information, because their job is not to change, and then (optionally) change again (for "undoing"), display parameters. Instead, they filter, collect, generate, or reformat text, which may involve harvesting data and applying formatting codes.

The mgp-ez directives are all of the same form: a word terminated by a %. Yes, that's exactly backwards from the %word format used by Magicpoint itself, so that if mgp-ez is unavailable, the presentation can still be prepared using Magicpoint. In contrast, if this program used additional directives of the %word form, each would trigger a fatal error if Magicpoint were run directly on the *.mg file.

Next, we'll examine each of the Magicpoint-EZ directives in turn.

fvgap%, hvgap%, & qvgap%

These directives respectively provide full, half, and quarter -sized vertical gaps on the page.

Example

        Here's a line
        hvgap%
        I want this line pretty close to the previous one
        qvgap%
        # I want this image even closer to the line above
        %newimage "pic.jgp"

Magicpoint doesn't provide any easy way to get a vertical gap that's smaller than usual, and then return to the previous setting. And this program can't really do that properly either, because only Magicpoint itself knows what the current %vgap size is. These directives have proven useful for producing vertical gaps of various proportions of the size of the DEFAULT_VGAP setting in the configuration file.

Incidentally, the predefined vertical-gap styles, <V_30> through <V_95>, also return the vgap setting to DEFAULT_VGAP, but these styles are meant for controlling the vertical spacing between collections of adjacent text lines, whereas these directives merely insert a single vertical gap where requested.

include%

Example

    include% "filename"

File inclusion is provided by the include% directive. The contents of the indicated file are read, and then recursively, its contents are scanned for additional include% directives which are read, and so forth. The resulting text is inserted into the *.mgp file in place of the directive.

This is valuable for two reasons:

  1. It allows inclusions of files at arbitrary positions, unlike Magicpoint's %include, which can only be used in the presentation's "preamble", and

  2. It enhances the behavior of %filter, which needs to find literal text in the document to provide as command input, by allowing the data to be obtained from a file: 
        %filter "/bin/sort"
    %include "input_lines.txt"
    %endfilter

    If the data don't reside in a file, but are available as command output (see below), then command% can provide a similar service:

        %filter "/bin/sort"
    command% "/bin/who"
    %endfilter

    This compensates for the limitation that %filter doesn't allow shell commands to use special characters, such as:

        %filter "/bin/who | /bin/sort"

    and

        %filter "/bin/sort < /etc/passwd"

skip% & unskip%

Example

"Line exclusion" is provided by skip%/unskip%, which allows a *.mg document to retain lines that do not become part of the current presentation. This allows multiple versions of the presentation to be retained in a single file, by restricting the pages that will be shown in a particular talk.

 This line is in the presentation
 skip%
 This one is NOT in today's presentation; maybe tomorrow!
 unskip%
 This line is in the presentation
 skip%
 The rest of the file is excluded, unless an unskip% appears below

code% [blank-gap:other-gap]

Example

    code% tail +1 perlgrep.plx 25:35

One problem with Magicpoint's %filter directive is that it doesn't support the concept of applying special formatting to the command's output. So unless you edit the *.mgp file directly, there is no way to apply any markup variations to the obtained data. This directive addresses that limitation.

The syntax requirement of code% is simply that at least one non-whitespace character must appear after the code% directive. If the vertical gap specifications are provided at the end, they will be stripped off, and the the rest will be submitted verbatim to your OS's command interpreter, so you must also supply any quotes that might be needed.

There are security concerns that may apply here, especially if the Magicpoint-EZ script is running with altered permissions (which is NOT recommended), which are covered in the next subheading.

As a first step in providing something more useful for the display of computer programs, code% applies a fixed-width font and specified color to the acquired program text, and renders #-prefixed comments in a separately specified font and color (according to the variable settings in the configuration file).

The blank-gap dictates how much vertical space should be used to represent blank lines in the code, and the other-gap the amount of space to be used after non-blank lines. The units are percentages of the font height, so 100 means use a full-sized blank line, and 50 a half-size, etc.

Security Alert!

Because this directive executes arbitrary commands submitted by the user, the usual precautions are applicable if the program is running with an ID other than that of the user executing it. (Later versions might use Perl's "taint mode", to do some sanity checking on the command. Until then, excercise caution with this directive!)

command%

Example

    command% nl -ba perlgrep.plx

As with code%, there must be at least one non-whitespace character after the command% directive. All the rest will be submitted verbatim to your OS's command interpreter, so you must also supply any quotes that might be needed. (There are security concerns, which are covered in the next subheading.)

This directive is a variation on code%, which simply imports the command output into the presentation (without applying any formatting). Unlike Magicpoint's %filter directive, pipelines and other complex commands can be used (as they can also with code%). For example:

    command% man mg2mgp | head -20 | col -bx

Arbitrarily complex commands are allowed.

Security Alert!

Because this directive executes arbitrary commands submitted by the user, the usual precautions are applicable if the program is running with an ID other than that of the user executing it. (Later versions might use Perl's "taint mode", to do some sanity checking on the command. Until then, exercise caution with this directive.)

tpage%

Example

 tpage%

The tpage% directive provides support for sections started by "title pages", whose headings have individually specified default text formats. This directive can be used anywhere the standard %page directive would be allowed. Its effect is to insert a "chapter header" on the indicated page, with page-numbering reset to 1.

npage%

Example

 npage%

The npage% directive creates pages that are endowed with a header line containing the Author's name, the Copyright year (defaulting to the current year), and a web-site URL, along with page-numbering in the two-part section-page format.

The headings are governed by style specifications provided through variable settings in the .mg2mgprc file (still under development). At the present time, users are encouraged to use the predefined format, which is activated by setting the variables AUTHOR, URL, and YEAR in the sample .mg2mgprc file.

The npage% directive can be used anywhere the standard %page directive would be allowed, but npage% is designed for use with tpage%. So if you use it without requesting a Title Page with tpage% first, the section number will show as zero. It's okay to intermix %page directives with npage% ones, but this is generally undesirable. In any case, this directive does much more for you, so you probably won't feel the need to use %page ever again.

table%

Example

    table%
        (table specificatons)
    endtable%

Under construction.

ASSOCIATED COMMANDS

mgp_nopause

Examples

 mgp-ez presentation.mg | mgp_nopause > presentation.mgp
      OR
 export MGP_NOPAUSE='on';  mgp-ez presentation.mg > presentation.mgp

To make it easier to proofread demonstrations, %pause directives can be filtered out of your *.mg file using the command mgp_nopause. This allows each page to be viewed in its entirety in one glance, which speeds up proofreading considerably if many %pause directives have been used.

As shown above, as an alternative to using mgp_nopause (which is just another name for the mgp-ez program), you can set the OS environment variable MGP_NOPAUSE to "on", and run mgp-ez in its place.

po2pod

This program, which is another name for mgp-ez, can be used to convert *.po files (not quite in POD format) to *.pod files, if invoked under this alternate name. In other words, this program does for POD documents what mgp-ez does for Magicpoint presentations.

FILES

The .mg2mgprc file can be used to define styles (STYLES) and variables (VARS) that make it vastly easier to prepare Magicpoint presentations. This program is distributed with a sample file, which you're free to edit to your own tastes.

For example, I use lots of colors, and would rather type C_LROD to get lightgoldenrod than its entire name.

The configuration file is looked for under the following directory/name combinations:

  1. .mg2mgprc in the current directory,
  2. .mg2mgprc in the HOME directory,
  3. in a fully specified pathname (ending in any arbitrary filename) provided in the (optional) $MG2MGPRC environment variable,
  4. in /etc/mg2mgprc,
  5. in mg2mgp.rc in the current directory

Sample .mg2mgprc file

command% sed -e 's/^#_SKIP%/SKIP%/' -e 's/^#_UNSKIP%/UNSKIP%/' /home/contix/.mg2mgprc | /local/timbin/skip | sed 's/^/ /' > /tmp/_mg2mgprc && cat /tmp/_mg2mgprc

SUPPORT

I am using this program heavily in my own work, so it is improving by leaps and bounds on a daily basis. Please let me know how you like it, and if you find any bugs.

AUTHOR

Tim Maher, tim(AT)teachmeperl.com, yumpy(AT)cpan.org

COPYRIGHT & LICENSE

Copyright (C) 2003-2004, Timothy F. Maher. All rights reserved.

AFFILIATION

Consultix, a division of Pacific Software Gurus, Inc. www.TeachMePerl.com

PROGRAM's WEB-SITE (coming soon)

http://www.teachmeperl.com/mg2mgp.html

© Copyright 1994-2008   Pacific Software Gurus, Inc.   All Rights Reserved.

   Powered by Google