Author: Robbert de Groot
Copyright: © 2007-2007, Robbert de Groot
Description: G.O.D.D.A.M.U. (GODDAMU) stands for
Groot's Organized Document Definition Aggregation and Manipulation Utility. The purpose of this program is to ease the
development of documentation and web pages. It does this by separating
the content from the formatting of the content. This was the same content
can be manipulated into different file formats whether it be HTML, TXT,
Rich Text File (RTF) etc. Another feature of this separation is that
the content can be in multiple languages and still be targetted to the
various file formats.
This License agreement ("AGREEMENT") is between you (either as an individual or a single entity) and Robbert de Groot ("DEVELOPER") for GODDAMU ("PRODUCT"), including any associated media and accompanying on-line or printed documentation and also any future versions, patches or updates.
Using the PRODUCT for Commercial Purposes ("COMMERCIAL PURPOSES") is defined to be
using the PRODUCT in exchange for Money (Salary or via Contract), for services,
for products or any combination.
The DEVELOPER relies on your intergrity and your observance of the laws that protect
intellectual property.
By installing, copying, accessing or otherwise using the PRODUCT, you agree to be bound
by the terms of the AGREEMENT.
The PRODUCT is owned by DEVELOPER and is protected by copyright laws and international
copyright treaties. The PRODUCT is Licensed, not sold.
The PRODUCT is distributed as Commercial Software. An unlicensed version is available
for evaluation for unlimited time and can be used for non COMMERCIAL PURPOSES. You
may License the PRODUCT in order to use the PRODUCT for COMMERCIAL PURPOSES.
Contact the developer to obtain a License.
This License grants you the following rights and limitations if you
do or do not hold a License for the PRODUCT:
This License grants you the following rights and limitations if you do not hold
a License to the product:
This License grants you the following rights and limitations if you hold a License
to the product:
DISCLAIMER
THE PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
IN NO EVENT WILL DEVELOPER BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE, MISUSE OR INABILITY TO USE THE
PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF DEVELOPER
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
DEVELOPER
Robbert de Groot
Vancouver, BC, Canada
zekaric, at, yahoo.ca
http://members.shaw.ca/zekaric
G.O.D.D.A.M.U. (GODDAMU) stands for Groot's Organized Document Definition Aggregation and Manipulation Utility. The purpose of this program is to ease the development of documentation and web pages. It does this by separating the content from the formatting of the content. This was the same content can be manipulated into different file formats whether it be HTML, TXT, Rich Text File (RTF) etc. Another feature of this separation is that the content can be in multiple languages and still be targetted to the various file formats.
GODDAMU files are simple ASCII files but they are formatted in a very specific way. It's format is simple but fussy in that there is little to not variation allowed. The format and restrictions are discussed in a following chapter.
These ASCII files all have the extension "GOD". However there are three purposes that a GOD file can have.
Variable Definition file just holds variable substitutions or whatever you wish for it to contain. This is useful when you have a common name and at some point down the line that name may change. You would only need to change one place instead of everywhere that name is used.
Template Definition file holds the formatting of the content data. A Content Data file would indicate a template file to use to format the content. A Template Definition file will hold all the templates for all destination targets you plan to publish to.
Content Data file holds the actual content minus any target specific formatting. All formatting should be abstracted out. A Content Data file will have all the languages that you plan on publishing to.
GOD files are simple ASCII/UTF-8 files. They use the UNIX file ending only. That means all lines end with only a line feed. Not a line feed, cursor return as you would find on MS-DOS machines nor just cursor return only as you would find on Apple Machintosh computers. You will need to find a editor that will allow you to save the text files with line feeds only.
The format is very simple but the a touch fussy. I'll cover the fussiness later. All that a GOD file contains are Key, Value pairs. From there the GODDAMU processor takes care of the rest. However there are special keys that you need to be aware of which will be covered later.
Defining a comment in the file. A '#' is used to indicate a line is a comment. The # should be the first letter of a line. Part of the fussiness. # won't mean anything special if it is not the first letter.
# This is a comment in a .GOD file.
Defining a single line value.
# This is a single line value singleLineValueKey .Single Line Value Value
A word about keys. They can be about anything you like. However when the parser hits a period, it will assume that it has read the key. So the only restriction would be that the key can not contain periods. It's also probably a good idea to avoid spaces and # signs. In the above case we can see the period is not exactly at the end of the key. There are spaces there. These spaces will be trimmed off so the actual key will be singleLineValueKey. Leading spaces will also be trimmed but it's probably not a good idea to have them. What ever follows the period, to the end of the line, is the value for this key.
Defining a multi line value.
# This is a single line value multiLineValueKey line 1. line 2. line 3. .
Here the key is the entire first line. Spaces will be stripped again if you made the mistake of having spaces after the last non space character. The value appears on multiple lines below the key. Notice the first character is a space. This is important. This space is trimmed off and the rest of the line is used as is. The value is terminated by a single period on it's own line and not indented by a space.
There you have it. The GOD format in all it's glory. Not much to it. The fussiness is worth repeating though.
Currently GODDAMU is a command line program. This means you will need to bring up a command prompt. I won't go into this as I assume you should know a little bit about this before using GODDAMU. If you are one of those people who know nothing about command prompts then you might want to hold off trying GODDAMU until I make a grpahical front end to the program.
in order to run GODDAMU you need to be in the same directory as your GOD files. looks only in the current directory for GOD files. Just running from the command line prompt will show you this.
GODDAMU Help zgoddamu.exe -l(languageValue) -t(targetValue) -f(fileNameFormat) -o(outputPath) -l(languageValue) Sets a target language. Usually a language to process. You can specify more than one. You need to specify at least one. This can be -ddefault and there are special rules when it is 'default'. -t(targetValue) Sets a target tempalte. Usually a file format to process to. You can specify more than one. You need to specify at least one. -f(fileNameFormat) Sets the file name format of the processed file(s). SingleFileDoc - is replaced with article name. default - is replaced with language choice. html - is replaced with file target choice. default is "SingleFileDocdefault.html" -o(outputPath) Path to create the new files in. default is the current directory. Example: zgoddamu -ldefault -lfr -lnld -thtml -trtf -oc:\\gdu Creates HTML and RTF files for default, frence and dutch languages and tosses those files into the folder c:\\gdu
As you can see you can ask GODDAMU to toss out more than one target format as well as more than one target language if there is a call for either. It's touched on very lightly the variable substitution used by GODDAMU when it talks about the file name format. In GODDAMU anything enclosed in [ and ] is considered a macro. We'll cover macros more completely in a following chapter but I'll just say this; default will be replaced with what ever was given in (languageValue); html will be replaced with what ever was given in (targetValue); SingleFileDoc will be replaced with the GOD's filename minus the ".god" extension.
In a god file the keys are the macro names. The values can contain any number macroes as you need them. So what is a macro? The following are simple macroes that was covered in chapter , .
[article] [language] [target]
These are simple macroes. They are also specific to GODDAMU so you can't use these names in your macroes. What happens here is that these are straight variable substitutions. SingleFileDoc will be replaces with the current article being processed with out the .god extension. The others are replaced with the values provided by the command line -l and -t values.
Anatomy of a macro is as follows
"[" (macroName) [(arguments...)] "]"
(macroName) is the name of the macro. The name is case sensitive. The name could refer to a built in GODDAMU macro or something found in a [target].god file. There is a special [target].god. One for each target file format. This file contains macros for that format. Let's say we have the following.
[title [This is my title]]
The macro in the html.god file could look like.
title .<h1>[1]</h1>
Argument substitution will substitute the arguments in order. Therefore when we see [1], this will be replaced by the first argument of the macro. similarly [2] will be replaced by the second argument and so on.
Now be careful. GODDAMU has no smarts if you do something dumb. It is possible to cause an infinite recursion which will result in GODDAMU to hang or crash. What is infinite recursion? The following is an example.
simpleRecursion .Ha[simpleRecursion] recurseToA.Ho[recurseToB] recurseToB.Ha[recurseToA]
This will cause GODDAMU to create strings that never end and will only stop when the Operating Systems decides that GODDAMU is no longer being nice and kills it or GODDAMU crashes.
In the first chapter we covered briefly the 3 types of files that GODDAMU deals with.
There are no real restrictions on the key values in this file. put what ever you like in these files. One caution, do not include a "publish" key in this file. This will make sense when we get to the other two types of files.
There are special variable files that are of the form [target].god files which hold specific macros for that file format.
This file contains the templates for the target destinations. You will need to provide a key value for each target you plan to support. Meaning, if you are targetting "html" then you will need a key value for "html". Also do not define a "publish" key.
Or otherwise known as Article files. They contain the content of the pages being used. For actual pages that are to be published have a key value in this file of "publish.1". This will tell GODDAMU to process this file and create a resulting target formatted file.
You also need to define a "template" key value. This tells GODDAMU to look for a specific .god file to use a template. This .god file needs to have the target key values set. An optional "filename" key is allowed to allow you to override the command line file name format and use this specific file name format.
This file must have all the language content to be used. "default" can be one of the languages.
[article]
article is used to insert the current article name being processed. This is essentially the same as [ins . ?] but you can't use the ins macro in the the filename portion of the ins macro. This is were [article] can come in. Also used in the command line to define file name format of the output files.
[articlePush (filename)] [articlePop]
articlePush is really an internal function so that the '^' filename for the ins macro can be processed properly. However is someone needs to set this value for any particular reason then it's here for the use. This macro will be replaced with nothing in the output.
[(] [)]
The only way to insert a [ and ] in the output. If these aren't used GODDAMU will most likely complain about undefined macro or related.
[data (filename) (keyname)]
data is used to create an article list of a particular key value pair inside of another article. This is useful to dump a list of releated items in one GOD file instead of spread out over individual GOD files.
(filename) will be the name of the article in the list. Article names should be unique.
(keyname) will the the key in the above GOD article that has the list.
Examples:
GOD file: Gods.god godList Zeus name.Zeus description.Da Big Guy. . Hera name.Hera description.Da Big Guy's Pain in the Neck. . Minerva name.Minerva description.Da Big Guy's Favourite Headache. . . # NOTE: godList should be thought of as a list of GOD files placed # inline. The same rules as layed out before apply with everything # indented by one space. # # NOTE: We didn't really need to give the data unique names like # Zeus # ... # . # Hera # ... # . # ... # We could have all named them the same. However with given names # you can use dataSet if that is important. # # NOTE: No sorting is done on this list. It is read in as it is # seen. So care may be needed if order is important. GOD file: ListGods.god publish.1 default [data Gods godList] [dataLoop + [ [ins : name] is [ins : description] ] ] . The output would be something like... Zeus is Da Big Guy. Hera is Da Big Guy's Pain in the Neck. Minerva is Da Big Guy's Favourite Headache.
[dataLoop (op) [(loop contents)]]
dataLoop is used to iterate over the items in the data list that was previously set up.
(op) can be...
(loop contents) is the data to be copied to the final results for each loop iteration. Use the specific loop "ins" options to gain the data article information.
Examples:
GOD file: Gods.god godList Zeus name.Zeus description.Da Big Guy. . Hera name.Hera description.Da Big Guy's Pain in the Neck. . Minerva name.Minerva description.Da Big Guy's Favourite Headache. . . # NOTE: godList should be thought of as a list of GOD files placed # inline. The same rules as layed out before apply with everything # indented by one space. # # NOTE: We didn't really need to give the data unique names like # Zeus # ... # . # Hera # ... # . # ... # We could have all named them the same. However with given names # you can use dataSet if that is important. # # NOTE: No sorting is done on this list. It is read in as it is # seen. So care may be needed if order is important. GOD file: ListGods.god publish.1 default [data Gods godList] [dataLoop + [ [ins : name] is [ins : description] ] ] . The output would be something like... Zeus is Da Big Guy. Hera is Da Big Guy's Pain in the Neck. Minerva is Da Big Guy's Favourite Headache.
[dataPush] [dataPop]
dataPush and dataPop are used to push the current data list onto a data stack and then at some point later, to pop it off the stack to be reused. This is for those situations where you need to work with multiple data lists and you do not which to destroy the current data list.
[listSet (filename)]
dataSet is used set the pointer to a particlar article in an internal data list of articles.
(filename) will be the name of the article in the list. Article names should be unique.
Examples:
[dataSet Zeus]
[if (op) [(valueA)] [(valueB)] [(trueValue)] [(falueValue)]]
"if" allows you conditionally choose one option over another.
(op) can be...
(valueA) and (valueB) can be anything.
(trueValue) will be the result of the if, if (valueA) (op) (valueB) is true. (falseValue) otherwise. (falseValue) is optional and need not be included. Empty string is used if that is the case. Examples:
[if = [index] [[article]] [Currently processing the index page] [Somthing else.]] Conditional processing of common code. Depending on the article being processed, one string will be used instead of the other.
[ins (filename) (key) (arguments...)]
"ins" is the core of variable substitution or insertion. Inserts the value of the (key) found in file (filename) at the current location using the arguments provided.
(filename) can be...
(key) can be...
(arguments...) are individual parts of text that are enclosed in [, ]. These will replace the representative [1], [2], etc. in the macro value. Examples:
[ins var author]
This will be replaced by the value of key "author" in the var.god file.
[ins . title[language]]
This will be replaced by the value of key "titleen" where
in the currently processed god file. In this case the current language is "en".
[ins . ?]
This will be replaced by "sample" where the current processed file is "sample.god".
[ins . !]
This will be replaced by "asample.html" where the current processed file is
"sample.god" and the current target file format is "html".
[ins vhtml nameAndAlias [Robbert's Home Page] [Zekaric]]
This will be replaced by "Robbert's Home Page (A.K.A.: Zekaric)" where
nameAndAlias is defined as "nameAndAlias.[1] (A.K.A.: [2])" in file
vhtml.god.
[language]
lanugage will be replaced by the current language being processed. This will be one of the languages you provide as part of launching the GODDAMU processor.
[list (op) [(filename_regex)]] [listKey (op) (key) [(value_gregex)]]
list and listKey allow you do defining an internal article list based on a selection of god files. list compares the regular expression to the article name. listKey compares the regular expression to a specific key's value in the article. The list is sorted in alpha order so name your articles well as GODDAMU doesn't know if there is a number in the name of the article.
(op) can be...
(key) is the key to find in the articles and whose values to perform the regular expression on.
(filename_regex) is a sort of regular expression. It doesn't follow any of the know regular expressions.
Regular expressions are made up of pieces enclosed in (, ). The regular expression parts can be. (Note: only ({) and (=string) have been tested. It's probable that a lot of combinations do not work at the moement.)
Examples:
[list + []]
Add all articles to the list.
[list - []]
Flush the list.
[list + [({)(=anews)]]
Add to the internal list all articles which start with "anews"
as part of it's filename.
[listKey - chapter [(=1)]]
Remove all articles which have the key "chapter" equal to "1".
[listLoop (op) [(loop contents)]]
listLoop is used to iterate over the generated internal list of articles and apply each element in that list to the contents of the loop. The format of listLoop follows
(op) can be...
(loop contents) is the data to be copied to the final results for each loop iteration. Use the specific loop "ins" options to gain the list article information.
Examples:
[listLoop + [[ins | ?], ]] Displays all the articles in the list separated by a comma.
[listPush] [listPop]
listPush and listPop are used to push the current article list onto an article list stack and then at some point later, to pop it off the stack to be reused. This is for those situations where you need to work with multiple article lists and you do not which to destroy the current article list.
[listSet (filename)]
listSet is used set the pointer to a particlar article in an internal list of articles.
(filename) will be the name of the article in the list. Article names should be unique.
Examples:
[listSet [ins . ?]] Set the currently processed article as the current article in the article list.
[lsystem (iterations) (argumentCount) (arguments...) (subtitutions...) (final substitutions...) ]
lsystem was something I put in with no real intention of it being useful. It performs a L-System processing. Do an interenet search on L-Systems and what they are used for. This has the potential for use with a program like POV-Ray.
(iterations) will be an integer 1 or larger. The L-System will be iterated this many times.
(argumentCount) will indicate how many arguments follow.
(arguments...) will be the letters used in the L-System. These arguments should only be 1 letter long. If longer, only the first letter is used. There should be (argumentCount) or these. These arguments are enclosed in [, ].
(substitutions...) will match 1 for 1 to the arguments. At each iteration these patterns will be modified by replacing the letter values with their substitutions. These arguments are enclosed in [, ].
(final substitutions...) will match 1 for 1 to the arguments. After the iterations have been performed these values are substituted for the letter values.
WARNING: L-Systems can make a heck of a lot of data. (ins var project) will happily plug away until it crashes due to lack of memory or similar problem.
Examples:
# A Sierpinski Gasget or space filling curve. # 3 iterations # 4 arguments [lsystem 3 4 [f] [g] [+] [-] [f+f-f-f-g+f+f+f-f] [ggg] [+] [-] [move(1);] [jump(1);] [rotate(90);] [rotate(-90);] ]
[target]
target will be replaced by the current target being processed. This will be one of the targets you provide as part of launching the GODDAMU processor.