MuRGe

MUltilanguage Report GEnerator
Preliminary Specification

What, exactly, does "Mu" stand for? Multiple-Language? Multi-Language? Multilanguage? M$-Word says "Multilanguage" is a word.

Introduction

Murge is a second version of C++ Report Generator version 1 (referenced throughout as v1). The title of the program has been changed to "Murge," which stands for MUltilanguage Report GEnerator.

The major changes from C++ Report Generator v1 to Murge are outlined here (this may not be a comprehensive list):

Support for more reference tags - these are detailed later
Support for multiple "types" of projects, ie pre-report parsing, templates with containers, templates without containers, multiple containers, etc
A new, much friendlier GUI layout
Support for drag-and-drop

By far, the most significant change is the addition of the reference tags, which will cause significant changes to both the interface and the way the program works. The changes are detailed in this document.

1 Containers and Templates

v1 relied completely on the idea of containers and templates. Templates were HTML files that contained the reference tags (see Reference Tags, below) that specified the placement for the formatted and colored C++ code. For each entry in the project, the same (or a speicified different) template was placed end-to-end, and this file was placed in a container file, which usually contained a header (such as the title) and a footer (such as the name of the author). This limited projects to files which lended themselves to this method, such as homework assigned out of a book.

Since this method limited projects to container-n-template styles only, we have decided to add support for pre-report files. The container/template style project is also supported in Murge.

The two different types of projects are detailed in Section 3: Project Types.

2 Reference Tags

Reference tags are the heart of Report Generator. reference tags specify where in HTML pre-reports, containers, and/or templates specific elements should be placed.

2.1 Old Reference Tags

The following reference tags were supported in v1:

 - inserts the finished template file (containers only)
 - inserts the name of the entry (templates only)
 - inserts the filename of the file (file.ext) (templates only)
 - inserts the formatted source code (templates only)
 - inserts the output text (templates only)

2.2 New Reference Tags

The following are reference tags that are supported by Murge. This may not be a definitive list:

Reference Tag	Description	Containers	Templates	Pre-Reports
`<!-- #murge: type-pre -->`	Specifies that the file is a pre-report; used for drag-n-drop	---	---	Yes
`<!-- #murge: stylesheet(type) -->`	Inserts the stylesheet used for HTML color formatting. `type` specifies how to insert the stylesheet (see Section 2.2.2: stylesheet).	Yes	Yes	Yes
`<!-- #murge: start-optfield(name) -->`	Start an optional field with the name name.	Yes	Yes	---
`<!-- #murge: end-optfield(name) -->`	End an optional field with the name name.	Yes	Yes	---
`<!-- #murge: var(name) -->`	Inserts a user defined variable with the name name.	Yes	Yes	Yes
`<!-- #murge: template -->`	Inserts the repeating, finished template file	Yes	---	---
`<!-- #murge: fileshort -->`	Inserts the short filename (filename.ext)	---	Yes	---
`<!-- #murge: filelong -->`	Inserts the long filename (D:\path\path\file.ext)	---	Yes	---
`<!-- #murge: entry -->`	Inserts the name of the entry from the project	---	Yes	---
`<!-- #murge: orig-source(file) -->`	Inserts the original, unformatted and uncolored source code. `file` specifies a filename when used with pre-reports (see Section 2.3.x: orig-source).	---	Yes	Yes
`<!-- #murge: source(file) -->`	Inserts the finished, formatted source code. `file` specifies a filename when used with pre-reports (see Section 2.2.x: source).	---	Yes	Yes

2.2.1 type-pre

Format:


Since pre-reports are often created on a per-use basis, it is helpful to be able to drag-and-drop the file onto the GUI or program executable in order to quickly open and parse the file. In order to let Murge know that the file is a pre-report, this line can be placed at the top of the file. It is not necessary for the code to be placed at the top of the file, however; it can be placed anywhere.

2.2.2 stylesheet

Format:


In order to keep the generated HTML files as neat as possible, Murge uses CSS (Cascading Style Sheets) to format the formatted source code. The stylesheet reference tag tells Murge that the CSS definition needed to display the page correctly should be placed at the indicated position.

The "type" keyword can be one of three things:

"full" tells Murge that the current HTML file has no shylesheet at all, and that a complete style sheet, with full <style> and </style> tags needs to be inserted.
"inline" tells Murge that the current HTML file already has a stylesheet defined, and that the Murge styles should be added to the current stylesheet (without the<style> and </style> tags) at the specified location.
Any other text specifies a CSS file, which should be nonexistant, that Murge will create and link to. If you already have a Murge stylesheet that you want to use, do not use this option, as the file will be overwritten.

If the "type" keyword is blank, or the (type) section is omitted, the reference tag is completely ignored, and the finished report may not be formatted correctly.

2.2.3 start-optfield and end-optfield

Format:



Opt-Fields are blocks of HTML that can be turned on or off during the course of the program. This is very useful for container/template projects, where some files have certain fields and other files do not.

Opt-Fields may be nested; however strange results may occur when opt-fields are nested incorrectly. For this reason, Murge will report an error when opt-fields are indeed nested incorrectly, and it will not generate a report.

The "name" keyword identifies an opt-field. Each opening opt-field must have a matching closing opt-field. Also, the "name" keyword may not be blank, nor may the (name) section be omitted. If it is, the reference tag(s) is/are completely ignored.

2.2.4 var

Format:
<!-- #murge: var(name)>

The var reference tag is used to place a user defined variable in the document. When you choose a container, template, or pre-file in the program, the file is scanned and all the variable names are listed on screen. You can type in text or pull text from an ASCII file, which is placed in the indicated position in the file.

The program allows several options, including HTML character escaping, preformatted text, and other miscellaneous details during execution.

The "name" keyword identifies the name of the variable so that Murge and you know what the variable is and where it goes. It may not be blank, nor may the (name) section be omitted. If it is, the reference tag is completely ignored.

2.2.5 template

Format:


The template reference tag is only used in container/template projects, and thus can only be used in containers. In this type of project, the report template is generated for each file in the project, then all the report templates are inserted into the container; this tag specifies where those documents should occur.