Murphy's law: big chances for mistakes
In this chapter we focus on mistakes: the megazine.mz3 file is built again, but this time with some typical mistakes:
- A missing hyphen, i.e. pagewidth=720 instead of pagewidth="720"
- incorrect spelling: missing or wrong characters
- incorrect structure, i.e. tags out of place
- incorrect or unknown values.
Everything that is formally defined in the dtd file can be found by validation.
In case you use notepad++, the separate and also free tool available at Validome gives tremendous help! Generally all mistakes in the structure and syntax of the megazine.mz3 file are found and reported precisely.
The built in validation feature of XMLBlueprint does at the end the same job, but without the need of an online internet connection.
If the images do not show up, in most cases the name or path of the image is mis-spelled. Check it against the folder where the files are located. You will find out yourselves over time how many options there are to make mistakes!
And in case you move your book to a server, you must remember that on a Linux system capital and lower case words and path names are not the same! Also the orientation of the slash is of importance:
On Windows systems is is a back slash "\", on other systems it the standard "/" as folder - subfolder delimiter.
The console, a window popping up at the header line, will point out what files couldn't be find. The console must be declared as plugin, and the errorlevel must be set appropriately, e.g. to "WARNING".
Please watch the video carefully, it will give you a lot of suggestions how to debug and find the problems. Do not give up, there will be a solution. But usually not the obvious one (remember Murphy's law ;-)
Video: Typical Mistakes
Sooner or later you'll have a typo in your XML definitions and spelled something incorrectly. THen it is important to identify the root cause as fast as possible.
THere are a couple of tools and methods that will support you in this:
- Validome
This Online service accepts a copy of your full XML data in the source window. On a click the code is validated against the DTD definition as defined in the megazine.dtd file (that's what the link at the beginning of the megazine.mz3 file serves for).
Reminder: the megazine.dtd describes all defined tags, elements and parameters, and also where what elements are allowed. Incorrect elements (wrong spelling, wrong position, tags missing) are reported with a detailed description of what seems to be wrong.
It it not a bad idea to check the content of the megazine.mz3 file after every (bigger) change. - Porwerful XML Editors
An Editor knowing the valid XML definintions will provide suggestions for valid elements after the first character entered ("code completion"). You can pick the element of choice or enter more characters to more precisely specify what you need and shorten the list. Picking the element guarantees a correct spelling. Also entering the same parameter twice (not allowed!) will be avoided.
The validation isperformed offline within the editor; an online connection to the internet is not needed.. - Console
Megazine3 offers a built-in debugging tool: the console.
This plugin reports errors and warnings (if "errorlevel" is set correctly) when you hit the "#" key.
Very helpful identifying incorrect path and file names.
Examples of incorrect spelling, used in the video:
- pagewidth=720 instead of pagewidth="720": hyphen characters missing
- keepar="TRUE" instead of keepar="true": value must be in lower case letters; not capital letters
- imgages/ instead of images/ : incorrect path name
MZ3 Console
Another common mistake is to mess up the XML structure. There are several chances to do so, like:
- forget the closing tag, e.g. the </page> that concludes a <page>
- put an element like an image <img> outside of a <page> ... </page> tag
These errors also will be found during the validation process, and often the error messages and hints give exact guidance. But there can be mistakes where those hints are not as helpful as desired.
Then a closer look into the xml data will help. If you use a context sensitive editor like notepad++. Then the color coded text will help to find segments that are looking "strange" or "out of context". If e.g. your text is all greyed out (the color depends on your color schema of choice) from a certain position down, then probably the closing comment characters are missing or incorrect.
Notepad++ also gives support in identifying related tags: clicking into one tag, that tag and the corresponding opening or closing tag are colored identically.
Tags also can be collapsed or expanded, i.e. the tag and the content (like images within a page) are collapsed to one single line. A similar concept as with folders and subfolders in the file browser. A "+" sign indicates, that the line can be expanded.
Reducing a complex XML file to the minimum structure elements (i.e. collapse all) also helps to identify unintended structures.
Example used in the video:
The line defining the image was copied after a closing page tag </page>, and not positioned within a <page> <img /> </page> bracket.
XML structure
If e.g. buttons are missing or an expected functionality is not supported, in most cases the corresponding plugin is missing.
Examples:
- navigationbar - no "bubbles"/thumbnails, no page numbers, no page navigation support
- keyboardnavigation - the arrow right, left, up and down arrows do not flip the pages, the mouse wheel does not zoom
- console - the console does not pop up when hitting the #-key.
If messages are missing, check the value defined for the "errorlevel" parameter; set it to WARNING - slideshow - adds a start/stop button to control an automatic, time based page flip
- print - once added to the list of plugins, the print plugin will show a button that supports printing selected pages
List of Plugins
Wiki
If your book looks different than expected, and you already checked the spelling and validated the XML file, check your definitions/values. You might have made a wrong assumption!
- Did you "normalize" you images to make them all the same height (or width), so you easily can make them fit on a page?
- Did you calculate the size of the page correctly?
- Have you verified the maximum dimensions of your photos? How big should the border be?
- Is everything at the correct location? Did you copy the images to the folder referred to in the megazine.mz3 file?
- Did you by mistake deleted lines (e.g. the dtd link)?
