DAISY 2.02 Validator User Manual

Original Author(s): Markus Gylling

An overview and introduction to the DAISY 2.02 Validator is available in the DAISY 2.02 Validator User Manual Introduction

To validate a DTB, select Candidates from the main menu and select Add single DTB. A file browser dialog will open.

image of an added candidate Locate the directory where the DTB to be validated is located, select the NCC file and then select OK. A branch with an icon looking like a book image of the book icon will now be added to the Validation Report View located at the left part of the main window. See Validation Report View. Select Run from the main menu and click on Run all.

At this point the Validator will start performing the conformance tests on the DTB. At the bottom of the screen, in the Validation Report View, progress information will be displayed. Depending on the size of the book, the validation process will take from 30 seconds up to several minutes. See Validation Report View Progress.

Validation Complete

When the validation job has been completed, the icon of the DTB candidate in the Validation Report View image of the book icon will turned red. The system will also generate a "ping" sound upon completion. See Validation Report View above for the link to the Interface Main Window.

When the DTB candidate item branch is expanded, you will be able to read the results of the validation. (During the validation process, this branch reads "not validated").

image of error branches If a candidate passes all tests without any errors or warnings, the text "no errors" will be displayed in the DTB candidate branch. If one or more tests failed, for each failed test an item will be added to the branch.

Failed Test Categories

There are two subcategories of failed tests: error, and warning. Generally, a critical error means that there is a serious error in the DTB that may negatively affect its readability. Errors are further described as critical and non-critical in the Error View. See Error View for information on the Error View and the Comment Field within the Error View.

A non-critical error is a specification requirement violation, but readability may not be affected in any way. A warning constitutes neither of the above, but rather that a specification recommendation has not been met, or that otherwise defined common practice has not been used.

Selecting one of the failed test items will fill the Error View at the bottom of the main screen with information about the error. For some errors, this will include a suggestion for correction.

Double-clicking or executing ENTER on one of the tests will - if related to a specific file - display that file in the Document Editor window at the right of the screen. Here it is possible to review (and sometimes correct) the error. See Document Editor below to go to the Manual User Interface Main Window.

You may save the report - all test results - for a single candidate to an external xhtml file. The report is structured so that it can easily be printed, viewed in an HTML browser or even loaded back into the validator at a later time. To save the report for a candidate, select that candidate in the Validation Report View, choose File from the main menu and click on Save report.

Candidate Types

It is possible to perform validation on different types of candidates. You may choose to validate a single volume DTB, a Multi Volume DTB, or a single file of any type from a DAISY 2.02 DTB fileset.

Candidate Types Comment
Single DTB graphic used for single DTB Validates the complete DTB. Requires the NCC file as input.
Multi Volume DTB graphic used for multi volume DTB Validates the complete DTB. Requires all NCC files of the multi volume book as input. When the last NCC has been added, select cancel in the file open dialog.
Single File - NCC graphic used for single NCC Validates the NCC file internally, does not check any inter-document relationships.
Single File - SMIL graphic used for single SMIL Validates the .smil file internally, does not check any inter-document relations.
Single File - Master SMIL graphic used for single Master SMIL Validates the Master SMIL file internally, does not check any inter-document relations.
Single File - Content Document graphic used for single Master SMIL Validates the XHTML Content Document internally, does not check any inter-document relations.
Single File - Discinfo graphic used for single discinfo Validates the Discinfo file internally, does not check any inter-document relations.

Reliable Measure of Conformance

The single file validation alternatives will not result in a reliable measure of the conformance state of the DTB, as inter-document relations (such as links between files) are only checked when the Single DTB or Multi Volume DTB alternatives are selected.

To obtain a reliable measure of the conformance state of the DTB, select the Single DTB or Multi Volume DTB candidate alternatives. Never rely on the Single File alternatives for full validity checking - use these only during repair or pre-process stages.

image of the add candidates menu

The Single File - Content Document alternative may be used to validate source documents prior to DTB production.

Candidates are added by selecting the Candidates menu, and then clicking on the wanted alternative. In all cases, a file browser dialog will open, prompting you to point to the location of the candidate.

Validation Modes

The Validator allows three different modes of validation. The default mode is full conformance validation. This is the most demanding in terms of time required to determine DTB validity. It will complete all tests as defined in the Validator Test Map. Details on the Validator Test Map are located in the Validator Developer Manual.

The other two modes are:

image of light mode enabled in the candidate menu

Light Mode
This mode performs only those tests that are critical for DTB functionality. The mode includes file existance, file readability, file DTD validity and inter-file link integrity tests. The mode excludes metadata tests, timing data tests, etc.
Disable Audio Tests Mode
When this mode is enabled, all tests that are related to audio files will be omitted. This is typically used when you only have access to DTB data excluding audio.

The enabling and disabling of these modes is done in the Candidate Menu.

Batch Mode

It is possible to add several candidates at once and validate them in one session. When a large number of DTBs is to be validated, it may be useful to set up a batch queue and let the Validator process the DTBs in thequeue, for example, during the night.

To run the Validator in Batch Mode, simply repeat the "add candidate" command until all wanted DTBs or single files have been added. Then select the run all (CTRL+R) alternative from the Run menu. Run selected (CTRL+E) will only validate the selected candidate in the queue.

Executing the Validation

image of the run menuValidation is executed using either Run Selected (CTRL+E) or Run All (CTRL+R) from the Run menu. Run Selected will only validate the selected (highlighted) candidate in the candidate list. Run All will validate all added candidates.

You can also use the single arrow green button image of the run selected button to run selected, or the double arrow green button image of the run selected button to run all.

Depending on the size of the DTB and other circumstances (number of files, number of audio clips) the validation process will take from 30 seconds to several minutes. During validation, the current progress and status is displayed in the Status Bar at the bottom of the screen.

Interpreting the Result

When the validation is completed, the Validator will generate a "ping" sound, and the previously grey book icon image of the gray book icon will turn red image of the gray book icon.

image of error branches The validation results are obtained by selecting the candidate in the Validation Report View, and expanding the "tree" view (as in a Windows Explorer view) at the left of the screen. If a candidate passes all tests without any errors or warnings, the text "no errors" will be displayed below the DTB candidate. If one or more tests failed, for each failed test an item will be added to the branch.

The failed tests are sorted into two fundamental categories: errors and warnings.

A Warning

While an error in the DTB that should be corrected, a warning may or may not require correction. A warning normally constitutes neither a specification requirement violation, nor a threat to the readability of the book. It is typically issued when the validator cannot find data that is recommended by a specification, that is, it indicates that optional data is not present in the DTB.

It is however, recommended, at the very least, that the warnings be reviewed

There may be information not present that is vital or required by an organisation's internal requirements, even if it is not required by a specification. Some organisations, for example, require that the narrator name be included in the metadata. The metadata element ncc:narrator is recommended but not required by the DAISY 2.02 Specification, and thus if this information is not present the Validator will be reported as a warning.

Customizing Errors and Warnings

It is possible to customize and change the categorization of errors and warnings reported by the Validator by modifying files within the Validator application. For example, a metadata element (that must be present as directed within an organisation's internal specifications) can be set to reported as an error if it is missing or does not follow specific rules. See the sections on VTM and ADTD in the DAISY Validator Developer Manual. This is a highly technical operation. It is not recommended and not advisable to attempt this unless you are experienced working at this level.

The Error

If the Validator results indicate that a failed test is an error, it means that a violation of a requirement within one of the specifications that determines the grammar or structural rules of this file has occured. The specification may be the DAISY 2.02 specification, or one of the W3C specifications that the DAISY 2.02 specification is based upon. As explained in the Error View section of the User Interface Reference below, the error information usually contains a pointer to the specification that has been violated.

Errors are designated as either critical or non-critical in the Error View at the bottom of the page . This distinction is made to allow users who are primarily concerned with the readability aspect of validation to quickly get an overview of the status of the DTB in relation to readability. The Validator attempts to identify those errors which may impact readability in a negative way and designates them as critical errors.

Note however that the readability aspect of a DTB is optimally tested by executing light mode validation to ensure there are no errors whatsoever.

From a conformance testing perspective, the critical and non-critical categories are equally important. A specification requirement violation is always a serious error, regardless of whether the error has an impact on the readability of the book.

An error that may not negatively affect today's reading devices may be fatal to the reading devices of tomorrow. Only through full conformance can the longevity of a DTB be guaranteed.

Result Categories

Icon and name Failure type Failure class Note
image of the pass icon No errors - - All tests passed. The Validator could not find any conformance problems in the candidate.
image of the warning icon Warning Warning - A specification recommendation has not been met.
image of the error icon Error Error Non-critical A specification requirement has been violated. The error may not affect the readability of the DTB with current playback systems.
image of the error icon Error (critical) Error Critical A specification requirement has been violated. The error may affect the readability and longevity of the DTB.

Description of the failure

As you select an error or warning item in the Validation Report View, the Error View at the bottom of the screen will display information about the error. If you press ENTER or doubleclick on the item, the corresponding document (SMIL, XHTML) will be opened in the Document Editor at the right of the screen. If line and column information can be identified the cursor will be positioned at the exact point within the document where the error occurs.

Using the information in the Error View, and the document in the Document Editor, it is possible to identify and correct the problem.

In the Error View, the failed test is described. The failure description provided may be quite technical. Individuals who are not familiar with the DAISY standard and XML may find the manner in which this information is provided extremely technical and difficult to interpret.

Interpreting the Results

If the information provided seems technical and difficult to interpret, one way to understand the meaning of an error report and of the error itself, is to review the specification requirement that has been violated. If the computer is online, follow the link associated with the error. The link will take you to the specification, and sometimes to the relevant paragraph within the specification. This can be done either by a copy and paste of the web address given in the Error View, or by right clicking on the error in the Validation Report View and selecting Goto specification.

For additional assistance, you can send an inquiry to the DAISY Consortium Support email list.

See the Error View section of the User Interface Reference for further information on the content and meaning of a failure description.

Errors Which "Hide" Errors

Note that some errors "hide" other errors. If, for example, the ncc.html file is "malformed" or invalid to the DTD, the validator may not be able to execute any further testing (testing the links between the NCC and SMIL files for example). That is, validation was prematurely aborted due to a critical error in a document, and there may be additional errors in the DTB that simply cannot been discovered because the validation process was aborted.

For this reason, when attempting to correct a problem in a book, it is extremely important to re-execute validation after each manual fix until no further errors are reported. The originally detected problem may be corrected, but other errors that may have been "hidden" may still exist.

Common Questions Regarding Result Interpretation

Q: Why are DTD invalidity reports duplicated?
A: This is because each document except the content document is validated against two DTDs. The first one is the "canonical" DTD (the XHTML 1.0 or SMIL 1.0 DTDs published by the W3C). The second is the "custom" or "subset" DTD created by the developers of the Validator. The "custom" or "subset" DTDs are more finely grained (they find invalidity errors that relate specifically to the DAISY 2.02 specification). A document that is valid to the "canonical" DTD may be invalid to the "custom" DTD. A document that is valid to the "custom" DTD must be valid also to the "canonical" DTD. If this is found to not be the case in any instance, it should be reported to the developers.
Q: What does "attribute pair error" mean?
A: Reports including the text "attribute pair error" almost always relate to missing or erroneous metadata. The validator looks at <meta/> elements, and compares the values in the name and content attributes of these elements. The name and content attributes constitute the "attribute pair".

The Report Document

The Validator Report can be saved as an XHTML formatted document. This report contains a list of all of the errors and warnings found in the validated book. Each item in the list contains the same information as the information given in the Error View. Note that the Validator does not automatically save the Report Document. This is done manually by selecting Save report in the File menu.

image of the save report menu command The Report Document can also be opened in the Validator. By doing this, you can reinstate the session even if the Validator has been closed or the whole computer has been shut down and restarted. To be able to view the Report document in the Document Editor however, the DTB must placed in the same folder as it was when the validation was run.

Accuracy, Scope, Functionality

Accuracy

The report generated by the Validator is not guaranteed to be 100% accurate for the following two reasons.

  • The Validator may have failed to detect an error.
  • The Validator may have made a miscalculation and reported an error for an occurance that is actually valid.

The report from the Validator should be regarded as an indication of the state of the DTB. As the computational algorithms in the Validator improve over time, the indication will become more and more accurate, but the report can never be taken as a final and true statement.

Scope

The following items are not a part of the Validator testing scope.

Audio - Text Synchronization accuracy
The Validator does not check the accuracy of links, only the technical validity of them. For example, if an NCC item that textually represents page 5 actually points to the audio representing page 6, the Validator will not identify this as being incorrect.
Audio quality
Inferior sonic quality may result in a DTB which is "unreadable". The Validator does not analyze the quality of the audio (noise and signal levels, etc).
Real World References
Errors such as misspellings, mispronunciations and other erroneous references to the real world are not checked by the Validator.

Functionality

The following items are currently not a part of the Validator testing functionality.

PDTB
The Validator does currently not validate protected DTBs (PDTBs).
Given and Actual Encoding
The Validator currently does not validate given versus actual encodings. Nor does it verify consistency between different encoding information values in the same document.
Non-local resources
The Validator does not attempt to check the accuracy of pointers to non-local resources, for example on the Internet (http, ftp). It will check the validity of the URI syntax, but not whether the URI actually resolves.
ADPCM2
If the audio files of the DTB are encoded in the proprietary ADPCM2 format, all testing of audio file integrity except existance is disabled.
Skippability
DTBs that include skippable structures are tested regarding general DTD validity and link integrity, but the accuracy of the semantics is not tested. For example, the Validator will not determine if the skippable part of a SMIL file is actually referencing a producer note in the text document. See the DAISY 2.02 Skippable Structures Recommendation, referenced in "Read More" at the end of this document.

The Main Window

The main window of the Validator consists of four parts: the Validation Report View, the Document Editor, the Error View and the Status Bar.

image of the main window

The Validation Report View

The Validation Report View is a tree view that contains the DTBs selected for validation (referred to as 'candidates'(. The results of the validation are displayed as a sub-branch of each candidate.

Selecting or left-clicking on an error item in the Validation Report View will show its properties in the Error View at the bottom of the screen.

image of the properties popup dialogRight-clicking on an error presented in the tree view will display a pop up menu with two options: 'Properties' and 'Goto specification'. Selecting 'Properties' will open a dialog box with all of the information available on the test. 'Goto specification' will open an Internet browser and go to that specification, if the error is associated with a specification, and if the computer is connected to the Internet.

Double clicking or hitting ENTER on an error will (if the error is related to a file) display the file in which the error occurs in the Document Editor and, whenever possible, position the cursor on the line and column where the error occurred.

The Error View

The Error View shows information for the error selected in the Validation Report View. The information displayed includes failure type (error or warning), the directory path and filename of the file, line and column in the file (if existing), a longer error description than that given in the Validation Report View, a comment or suggestion, and in some instances a link to the associated specification.

For technical information on this topic, see the DAISY 2.02 Developer Manual (VTM).

The comment field is often used to suggest a correction for the error. In the screen shot example below, the comment is used to provide a suggested value for the ncc:kByteSize in the metadata.

//www.daisy.org/publications/specifications/daisy_202.html#tnkbs'

Note that the information in this window will vary depending on the currently selected test.

The Document Editor

image of the Document EditorThe Document Editor shows the currently active document. When you double click or hit ENTER with the focus on a certain error item, and if a certain document (XHTML or SMIL) is associated with the error, it will be displayed here.

Also, if the error occurs on a certain line and/or column within the document, the cursor will be positioned at that particular point.

If no line and column information is provided with the error item, the line and column information for this error item will read [-1:-1]. This will happen for example when the Validator reports that a certain information chunk is missing. Something that does not exist cannot be associated with a position within the document.

Editing

In addition to providing a view of the document, the Document Editor also allows you to modify the content of document as would be done in a common text editor. The On Screen Buttons section below contains a list of related functions.

Manually editing the content of the XML Document requires extensive technical knowledge. You should always take precaution when doing this, and always revalidate a DTB or single file that has been manually edited. Even individuals with a great deal of skill can make mistakes when editing a document.

Saving

When the document is saved, the Validator will automatically make an incremental backup of the file previous to the "save command". If the saved and edited file was named 'ncc.html", the the backup version will be called 'ncc_.html'; (an underscore symbol is added before the file extension). Each time the document is saved, a new backup is made. Thus you can review or revert through the edit history. In this file list example,


ncc_.html
ncc__.html
ncc___.html

the file with the most underscores is the one most recently saved.

The backup files will be placed in the directory "val_bkp", an automatically generated subdirectory located in the directory in which the DTB resides.

If the document opened is encoded in Unicode, the Document Editor will not allow editing of the document. The text "READ ONLY" will appear in the Status Bar. This is because the Windows™ text control used in the user interface of the Validator does not support Unicode. If the DTB is encoded using Unicode and you need to edit the document, choose an external editor that supports Unicode.

The Status Bar

The Status Bar at the bottom of the main screen has eight cells. The first cell shows the current status of the Validator: 'idle' or 'validating'. The second and third cells show total tests passed and total tests failed.

The fourth and fifth cells will display the text "LIGHT MODE ON" and "AUDIO TESTS OFF" if these modes are activated.

The sixth and seventh cells show current line and column numbers in the currently open document in the Document Editor.

The eighth cell will display the text "READ ONLY" if the opened document is encoded in Unicode. See the notice on unicode editing restrictions above.

image of the Status Bar

On-Screen Buttons of the Main Window

Button Hotkey Explanation
Validate all icon Validate all CTRL+R Validates all candidates in the validation candidates list
Validate selected icon Validate selected CTRL+E Validates the selected candidate in the validation candidates list
Abort validation icon Abort CTRL+A Aborts all queued validation jobs
Save file icon Save file CTRL+S Saves changes in the currently open document in the Document Editor
Search/Replace icon Search/Replace CTRL+F Performs search/replace operations within the currently open document in the Document Editor
Go back icon Go back CTRL+B Returns to the previous document (works only if a document has previously been opened with follow link)
follow link icon Follow link CTRL+K Follows the link of the first found <a> or <text> element after the cursor position in the open document

The Candidate List

image of the candidate list The candidate list provides a somewhat more flexible way of managing the validation candidates than the main window, especially when handling large batch queues of validation candidates. The following table explains the functionality within this screen.

Menu name Description

- Add -

Add candidates

Add single DTB

Add single DTB to candidates list

Add multivolume DTB

Add multivolume DTB to candidates list

Add single file(s)

Add single file(s) to candidates list

Ncc

Adds a single NCC file to the validation candidates list

Smil

Adds a single SMIL file to the validation candidates list

Master smil

Adds a single master SMIL file to the validation candidates list

Content doc

Adds a single content document file to the validation candidates list

Discinfo

Adds a single Discinfo file to the validation candidates list

Light Mode

Performs only those tests that are critical for DTB functionality. Includes file existance, file readability, file DTD validity and inter-file link integrity tests.

- Run -

Run validation

Run checked

Run validation on checked candidates

Run all

Run validation on all candidates

- Remove -

Remove candidates

Remove checked

Remove checked candidates

Remove unchecked

Remove unchecked candidates

Remove all

Remove all candidates

The Document Paths Dialog

image of the paths dialog The document paths dialog contains text input fields for setting the locations of the files needed by the validator. Under normal circumstances you do not need to edit these, but if you do so, make sure to enter directories as absolute paths, for example D:myFilesmyDirectory.

Name Description
DTD/ADTD The location of the document type definition (DTD) and attribute document type definition (ADTD) files. This path defaults to the 'externals' directory found in the validator install directory.
Default report save path The default directory where validation reports are saved.
Temporary path A non-writeprotected location where the validator can save temporary files.

The General Settings Dialog

image of the settings dialog The General Settings dialog contains the following two options:

Allowed time fluctuation
This slider control determines how much deviation is permitted during time value validation. If the value is set to 500, all discrepancies in time values below 500 milliseconds will be disregarded (not reported) by the Validator. This setting defaults to zero. For full conformance checking, it should remain set to zero. When set to zero all discrepancies will be reported.
Show advanced ADTD information
This setting determines if the validation report will include 'advanced' information about errors. When this option is turned off the report will include somewhat less information on those tests performed by the ADTD engine, however, the report will be more compact and may be easier to read. Details on the ADTD engine are given in the Validator Developer Manual.

Hotkey Reference

key function
CTRL + I Save report
CTRL + J Load report
CTRL + Q Exit program
CTRL + D Add single DTB to candidates list
CTRL + M Add multi volume DTB to candidates list
CTRL + L View candidate list
CTRL + E Validate selected candidate
CTRL + R Validate all candidates
CTRL + A Aborts all qued validations
CTRL + S Save document (Document Editor)
CTRL + F Search / Replace (Document Editor)
CTRL + K Follow link (Document Editor)
CTRL + B Go back (Document Editor)
CTRL + P Open document paths dialog
F1 Open help

Menu Reference

menu item function

- File -

File menu

Save report

Saves the report for the selected validation candidate in the Validation Report View

Load report

Loads a previously saved report

Exit

Exits the program

- Candidates -

Candidates menu

Add single DTB

Adds a DTB to the validation candidates list

Add multivolume DTB

Adds a multivolume DTB to the validation candidates list

Add single file(s)

Adds a single file to the validation candidates list

Ncc

Adds a single NCC file to the validation candidates list

Smil

Adds a single SMIL file to the validation candidates list

Master smil

Adds a single master SMIL file to the validation candidates list

Content doc

Adds a single content document file to the validation candidates list

Discinfo

Adds a single Discinfo file to the validation candidates list

Light Mode

Enables/Disables Light Mode

Disable All Audio tests

Enables/Disables Disable Audio Tests Mode

View candidates list

Opens the candidates list dialog

Clear all added

Removes all candidates from the validation candidates list

- Run -

Run menu

Run selected

Validates the selected validation candidate in the validate report view

Run all

Validates all validation candidates in the validation candidates list

Abort validation

Aborts all validations in the candidates list

- Editor -

Editor menu

Save document

Saves changes in the currently open document in the Document Editor

Search / Replace

Searches or replaces words or sentences within the currently open document in the Document Editor

Follow link

Follows the link of the first found <a> or <text> element after the cursor position in the open document

Go back

Returns to the previous document (only works if a document has been opened with "Follow link")

- Settings -

Settings menu

Document paths

Opens the Document Paths dialog

General settings

Opens the General Settings dialog

- Help -

Help menu

Open User Manual

Opens the User Manual in the mime connected html browser

Open Developer Manual

Opens the Developer Manual in the mime connected html browser

Error Log

Opens the Error Log dialog

About

Opens the About dialog

Screen Reader Use

All graphical items on the screen have hotkeys and menu equivalents.

The Validation Report View is a TreeView Control. To expand and collapse the branches use the arrow keys. While in the TreeView, to open a document associated with an error in the Document Editor, use ENTER. Cursor position is, if possible, set to the exact point where the error occurs. To go from the Validation Report View to the Error View, use TAB.

When moving around in a document in the Document Editor, the Status Bar contains current line and column information.

See the menu reference and the hotkey reference for further information.

An overview and introduction to the DAISY 2.02 Validator is available in the DAISY 2.02 Validator User Manual Introduction

To validate a DTB, select Candidates from the main menu and select Add single DTB. A file browser dialog will open.

image of an added candidate Locate the directory where the DTB to be validated is located, select the NCC file and then select OK. A branch with an icon looking like a book image of the book icon will now be added to the Validation Report View located at the left part of the main window. See Validation Report View. Select Run from the main menu and click on Run all.

At this point the Validator will start performing the conformance tests on the DTB. At the bottom of the screen, in the Validation Report View, progress information will be displayed. Depending on the size of the book, the validation process will take from 30 seconds up to several minutes. See Validation Report View Progress.

Validation Complete

When the validation job has been completed, the icon of the DTB candidate in the Validation Report View image of the book icon will turned red. The system will also generate a "ping" sound upon completion. See Validation Report View above for the link to the Interface Main Window.

When the DTB candidate item branch is expanded, you will be able to read the results of the validation. (During the validation process, this branch reads "not validated").

image of error branches If a candidate passes all tests without any errors or warnings, the text "no errors" will be displayed in the DTB candidate branch. If one or more tests failed, for each failed test an item will be added to the branch.

Failed Test Categories

There are two subcategories of failed tests: error, and warning. Generally, a critical error means that there is a serious error in the DTB that may negatively affect its readability. Errors are further described as critical and non-critical in the Error View. See Error View for information on the Error View and the Comment Field within the Error View.

A non-critical error is a specification requirement violation, but readability may not be affected in any way. A warning constitutes neither of the above, but rather that a specification recommendation has not been met, or that otherwise defined common practice has not been used.

Selecting one of the failed test items will fill the Error View at the bottom of the main screen with information about the error. For some errors, this will include a suggestion for correction.

Double-clicking or executing ENTER on one of the tests will - if related to a specific file - display that file in the Document Editor window at the right of the screen. Here it is possible to review (and sometimes correct) the error. See Document Editor below to go to the Manual User Interface Main Window.

You may save the report - all test results - for a single candidate to an external xhtml file. The report is structured so that it can easily be printed, viewed in an HTML browser or even loaded back into the validator at a later time. To save the report for a candidate, select that candidate in the Validation Report View, choose File from the main menu and click on Save report.

Candidate Types

It is possible to perform validation on different types of candidates. You may choose to validate a single volume DTB, a Multi Volume DTB, or a single file of any type from a DAISY 2.02 DTB fileset.

Candidate Types Comment
Single DTB graphic used for single DTB Validates the complete DTB. Requires the NCC file as input.
Multi Volume DTB graphic used for multi volume DTB Validates the complete DTB. Requires all NCC files of the multi volume book as input. When the last NCC has been added, select cancel in the file open dialog.
Single File - NCC graphic used for single NCC Validates the NCC file internally, does not check any inter-document relationships.
Single File - SMIL graphic used for single SMIL Validates the .smil file internally, does not check any inter-document relations.
Single File - Master SMIL graphic used for single Master SMIL Validates the Master SMIL file internally, does not check any inter-document relations.
Single File - Content Document graphic used for single Master SMIL Validates the XHTML Content Document internally, does not check any inter-document relations.
Single File - Discinfo graphic used for single discinfo Validates the Discinfo file internally, does not check any inter-document relations.

Reliable Measure of Conformance

The single file validation alternatives will not result in a reliable measure of the conformance state of the DTB, as inter-document relations (such as links between files) are only checked when the Single DTB or Multi Volume DTB alternatives are selected.

To obtain a reliable measure of the conformance state of the DTB, select the Single DTB or Multi Volume DTB candidate alternatives. Never rely on the Single File alternatives for full validity checking - use these only during repair or pre-process stages.

image of the add candidates menu

The Single File - Content Document alternative may be used to validate source documents prior to DTB production.

Candidates are added by selecting the Candidates menu, and then clicking on the wanted alternative. In all cases, a file browser dialog will open, prompting you to point to the location of the candidate.

Validation Modes

The Validator allows three different modes of validation. The default mode is full conformance validation. This is the most demanding in terms of time required to determine DTB validity. It will complete all tests as defined in the Validator Test Map. Details on the Validator Test Map are located in the Validator Developer Manual.

The other two modes are:

image of light mode enabled in the candidate menu

Light Mode
This mode performs only those tests that are critical for DTB functionality. The mode includes file existance, file readability, file DTD validity and inter-file link integrity tests. The mode excludes metadata tests, timing data tests, etc.
Disable Audio Tests Mode
When this mode is enabled, all tests that are related to audio files will be omitted. This is typically used when you only have access to DTB data excluding audio.

The enabling and disabling of these modes is done in the Candidate Menu.

Batch Mode

It is possible to add several candidates at once and validate them in one session. When a large number of DTBs is to be validated, it may be useful to set up a batch queue and let the Validator process the DTBs in thequeue, for example, during the night.

To run the Validator in Batch Mode, simply repeat the "add candidate" command until all wanted DTBs or single files have been added. Then select the run all (CTRL+R) alternative from the Run menu. Run selected (CTRL+E) will only validate the selected candidate in the queue.

Executing the Validation

image of the run menuValidation is executed using either Run Selected (CTRL+E) or Run All (CTRL+R) from the Run menu. Run Selected will only validate the selected (highlighted) candidate in the candidate list. Run All will validate all added candidates.

You can also use the single arrow green button image of the run selected button to run selected, or the double arrow green button image of the run selected button to run all.

Depending on the size of the DTB and other circumstances (number of files, number of audio clips) the validation process will take from 30 seconds to several minutes. During validation, the current progress and status is displayed in the Status Bar at the bottom of the screen.

Interpreting the Result

When the validation is completed, the Validator will generate a "ping" sound, and the previously grey book icon image of the gray book icon will turn red image of the gray book icon.

image of error branches The validation results are obtained by selecting the candidate in the Validation Report View, and expanding the "tree" view (as in a Windows Explorer view) at the left of the screen. If a candidate passes all tests without any errors or warnings, the text "no errors" will be displayed below the DTB candidate. If one or more tests failed, for each failed test an item will be added to the branch.

The failed tests are sorted into two fundamental categories: errors and warnings.

A Warning

While an error in the DTB that should be corrected, a warning may or may not require correction. A warning normally constitutes neither a specification requirement violation, nor a threat to the readability of the book. It is typically issued when the validator cannot find data that is recommended by a specification, that is, it indicates that optional data is not present in the DTB.

It is however, recommended, at the very least, that the warnings be reviewed

There may be information not present that is vital or required by an organisation's internal requirements, even if it is not required by a specification. Some organisations, for example, require that the narrator name be included in the metadata. The metadata element ncc:narrator is recommended but not required by the DAISY 2.02 Specification, and thus if this information is not present the Validator will be reported as a warning.

Customizing Errors and Warnings
It is possible to customize and change the categorization of errors and warnings reported by the Validator by modifying files within the Validator application. For example, a metadata element (that must be present as directed within an organisation,s internal specifications) can be set to reported as an error if it is missing or does not follow specific rules. See the sections on VTM and ADTD in the DAISY Validator Developer Manual. This is a highly technical operation. It is not recommended and not advisable to attempt this unless you are experienced working at this level.

The Error

If the Validator results indicate that a failed test is an error, it means that a violation of a requirement within one of the specifications that determines the grammar or structural rules of this file has occured. The specification may be the DAISY 2.02 specification, or one of the W3C specifications that the DAISY 2.02 specification is based upon. As explained in the Error View section of the User Interface Reference below, the error information usually contains a pointer to the specification that has been violated.

Errors are designated as either critical or non-critical in the Error View at the bottom of the page . This distinction is made to allow users who are primarily concerned with the readability aspect of validation to quickly get an overview of the status of the DTB in relation to readability. The Validator attempts to identify those errors which may impact readability in a negative way and designates them as critical errors.

Note however that the readability aspect of a DTB is optimally tested by executing light mode validation to ensure there are no errors whatsoever.

From a conformance testing perspective, the critical and non-critical categories are equally important. A specification requirement violation is always a serious error, regardless of whether the error has an impact on the readability of the book.

An error that may not negatively affect today's reading devices may be fatal to the reading devices of tomorrow. Only through full conformance can the longevity of a DTB be guaranteed.

Result Categories

Icon and name Failure type Failure class Note
image of the pass icon No errors - - All tests passed. The Validator could not find any conformance problems in the candidate.
image of the warning icon Warning Warning - A specification recommendation has not been met.
image of the error icon Error Error Non-critical A specification requirement has been violated. The error may not affect the readability of the DTB with current playback systems.
image of the error icon Error (critical) Error Critical A specification requirement has been violated. The error may affect the readability and longevity of the DTB.

Description of the failure

As you select an error or warning item in the Validation Report View, the Error View at the bottom of the screen will display information about the error. If you press ENTER or doubleclick on the item, the corresponding document (SMIL, XHTML) will be opened in the Document Editor at the right of the screen. If line and column information can be identified the cursor will be positioned at the exact point within the document where the error occurs.

Using the information in the Error View, and the document in the Document Editor, it is possible to identify and correct the problem.

In the Error View, the failed test is described. The failure description provided may be quite technical. Individuals who are not familiar with the DAISY standard and XML may find the manner in which this information is provided extremely technical and difficult to interpret.

Interpreting the Results

If the information provided seems technical and difficult to interpret, one way to understand the meaning of an error report and of the error itself, is to review the specification requirement that has been violated. If the computer is online, follow the link associated with the error. The link will take you to the specification, and sometimes to the relevant paragraph within the specification. This can be done either by a copy and paste of the web address given in the Error View, or by right clicking on the error in the Validation Report View and selecting Goto specification.

For additional assistance, you can send an inquiry to the DAISY Consortium Support email list.

See the Error View section of the User Interface Reference for further information on the content and meaning of a failure description.

Errors Which "Hide" Errors

Note that some errors "hide" other errors. If, for example, the ncc.html file is "malformed" or invalid to the DTD, the validator may not be able to execute any further testing (testing the links between the NCC and SMIL files for example). That is, validation was prematurely aborted due to a critical error in a document, and there may be additional errors in the DTB that simply cannot been discovered because the validation process was aborted.

For this reason, when attempting to correct a problem in a book, it is extremely important to re-execute validation after each manual fix until no further errors are reported. The originally detected problem may be corrected, but other errors that may have been "hidden" may still exist.

Common Questions Regarding Result Interpretation

Q: Why are DTD invalidity reports duplicated?
A: This is because each document except the content document is validated against two DTDs. The first one is the "canonical" DTD (the XHTML 1.0 or SMIL 1.0 DTDs published by the W3C). The second is the "custom" or "subset" DTD created by the developers of the Validator. The "custom" or "subset" DTDs are more finely grained (they find invalidity errors that relate specifically to the DAISY 2.02 specification). A document that is valid to the "canonical" DTD may be invalid to the "custom" DTD. A document that is valid to the "custom" DTD must be valid also to the "canonical" DTD. If this is found to not be the case in any instance, it should be reported to the developers.
Q: What does "attribute pair error" mean?
A: Reports including the text "attribute pair error" almost always relate to missing or erroneous metadata. The validator looks at <meta/> elements, and compares the values in the name and content attributes of these elements. The name and content attributes constitute the "attribute pair".

The Report Document

The Validator Report can be saved as an XHTML formatted document. This report contains a list of all of the errors and warnings found in the validated book. Each item in the list contains the same information as the information given in the Error View. Note that the Validator does not automatically save the Report Document. This is done manually by selecting Save report in the File menu.

image of the save report menu command The Report Document can also be opened in the Validator. By doing this, you can reinstate the session even if the Validator has been closed or the whole computer has been shut down and restarted. To be able to view the Report document in the Document Editor however, the DTB must placed in the same folder as it was when the validation was run.

Accuracy, Scope, Functionality

Accuracy

The report generated by the Validator is not guaranteed to be 100% accurate for the following two reasons.

  • The Validator may have failed to detect an error.
  • The Validator may have made a miscalculation and reported an error for an occurance that is actually valid.

The report from the Validator should be regarded as an indication of the state of the DTB. As the computational algorithms in the Validator improve over time, the indication will become more and more accurate, but the report can never be taken as a final and true statement.

Scope

The following items are not a part of the Validator testing scope.

Audio - Text Synchronization accuracy
The Validator does not check the accuracy of links, only the technical validity of them. For example, if an NCC item that textually represents page 5 actually points to the audio representing page 6, the Validator will not identify this as being incorrect.
Audio quality
Inferior sonic quality may result in a DTB which is "unreadable". The Validator does not analyze the quality of the audio (noise and signal levels, etc).
Real World References
Errors such as misspellings, mispronunciations and other erroneous references to the real world are not checked by the Validator.
Functionality

The following items are currently not a part of the Validator testing functionality.

PDTB
The Validator does currently not validate protected DTBs (PDTBs).
Given and Actual Encoding
The Validator currently does not validate given versus actual encodings. Nor does it verify consistency between different encoding information values in the same document.
Non-local resources
The Validator does not attempt to check the accuracy of pointers to non-local resources, for example on the Internet (http, ftp). It will check the validity of the URI syntax, but not whether the URI actually resolves.
ADPCM2
If the audio files of the DTB are encoded in the proprietary ADPCM2 format, all testing of audio file integrity except existance is disabled.
Skippability
DTBs that include skippable structures are tested regarding general DTD validity and link integrity, but the accuracy of the semantics is not tested. For example, the Validator will not determine if the skippable part of a SMIL file is actually referencing a producer note in the text document. See the DAISY 2.02 Skippable Structures Recommendation, referenced in "Read More" at the end of this document.

The Main Window

The main window of the Validator consists of four parts: the Validation Report View, the Document Editor, the Error View and the Status Bar.

image of the main window

The Validation Report View

The Validation Report View is a tree view that contains the DTBs selected for validation (referred to as 'candidates'(. The results of the validation are displayed as a sub-branch of each candidate.

Selecting or left-clicking on an error item in the Validation Report View will show its properties in the Error View at the bottom of the screen.

image of the properties popup dialogRight-clicking on an error presented in the tree view will display a pop up menu with two options: 'Properties' and 'Goto specification'. Selecting 'Properties' will open a dialog box with all of the information available on the test. 'Goto specification' will open an Internet browser and go to that specification, if the error is associated with a specification, and if the computer is connected to the Internet.

Double clicking or hitting ENTER on an error will (if the error is related to a file) display the file in which the error occurs in the Document Editor and, whenever possible, position the cursor on the line and column where the error occurred.

The Error View

The Error View shows information for the error selected in the Validation Report View. The information displayed includes failure type (error or warning), the directory path and filename of the file, line and column in the file (if existing), a longer error description than that given in the Validation Report View, a comment or suggestion, and in some instances a link to the associated specification.

For technical information on this topic, see the DAISY 2.02 Developer Manual (VTM).

The comment field is often used to suggest a correction for the error. In the screen shot example below, the comment is used to provide a suggested value for the ncc:kByteSize in the metadata.

//www.daisy.org/publications/specifications/daisy_202.html#tnkbs'

Note that the information in this window will vary depending on the currently selected test.

The Document Editor

image of the Document EditorThe Document Editor shows the currently active document. When you double click or hit ENTER with the focus on a certain error item, and if a certain document (XHTML or SMIL) is associated with the error, it will be displayed here.

Also, if the error occurs on a certain line and/or column within the document, the cursor will be positioned at that particular point.

If no line and column information is provided with the error item, the line and column information for this error item will read [-1:-1]. This will happen for example when the Validator reports that a certain information chunk is missing. Something that does not exist cannot be associated with a position within the document.

Editing

In addition to providing a view of the document, the Document Editor also allows you to modify the content of document as would be done in a common text editor. The On Screen Buttons section below contains a list of related functions.

Manually editing the content of the XML Document requires extensive technical knowledge. You should always take precaution when doing this, and always revalidate a DTB or single file that has been manually edited. Even individuals with a great deal of skill can make mistakes when editing a document.
Saving

When the document is saved, the Validator will automatically make an incremental backup of the file previous to the "save command". If the saved and edited file was named 'ncc.html", the the backup version will be called 'ncc_.html'; (an underscore symbol is added before the file extension). Each time the document is saved, a new backup is made. Thus you can review or revert through the edit history. In this file list example,


ncc_.html
ncc__.html
ncc___.html

the file with the most underscores is the one most recently saved.

The backup files will be placed in the directory "val_bkp", an automatically generated subdirectory located in the directory in which the DTB resides.

If the document opened is encoded in Unicode, the Document Editor will not allow editing of the document. The text "READ ONLY" will appear in the Status Bar. This is because the Windows™ text control used in the user interface of the Validator does not support Unicode. If the DTB is encoded using Unicode and you need to edit the document, choose an external editor that supports Unicode.

The Status Bar

The Status Bar at the bottom of the main screen has eight cells. The first cell shows the current status of the Validator: 'idle' or 'validating'. The second and third cells show total tests passed and total tests failed.

The fourth and fifth cells will display the text "LIGHT MODE ON" and "AUDIO TESTS OFF" if these modes are activated.

The sixth and seventh cells show current line and column numbers in the currently open document in the Document Editor.

The eighth cell will display the text "READ ONLY" if the opened document is encoded in Unicode. See the notice on unicode editing restrictions above.

image of the Status Bar

On-Screen Buttons of the Main Window

Button Hotkey Explanation
Validate all icon Validate all CTRL+R Validates all candidates in the validation candidates list
Validate selected icon Validate selected CTRL+E Validates the selected candidate in the validation candidates list
Abort validation icon Abort CTRL+A Aborts all queued validation jobs
Save file icon Save file CTRL+S Saves changes in the currently open document in the Document Editor
Search/Replace icon Search/Replace CTRL+F Performs search/replace operations within the currently open document in the Document Editor
Go back icon Go back CTRL+B Returns to the previous document (works only if a document has previously been opened with follow link)
follow link icon Follow link CTRL+K Follows the link of the first found <a> or <text> element after the cursor position in the open document

The Candidate List

image of the candidate list The candidate list provides a somewhat more flexible way of managing the validation candidates than the main window, especially when handling large batch queues of validation candidates. The following table explains the functionality within this screen.

Menu name Description

- Add -

Add candidates

Add single DTB

Add single DTB to candidates list

Add multivolume DTB

Add multivolume DTB to candidates list

Add single file(s)

Add single file(s) to candidates list

Ncc

Adds a single NCC file to the validation candidates list

Smil

Adds a single SMIL file to the validation candidates list

Master smil

Adds a single master SMIL file to the validation candidates list

Content doc

Adds a single content document file to the validation candidates list

Discinfo

Adds a single Discinfo file to the validation candidates list

Light Mode

Performs only those tests that are critical for DTB functionality. Includes file existance, file readability, file DTD validity and inter-file link integrity tests.

- Run -

Run validation

Run checked

Run validation on checked candidates

Run all

Run validation on all candidates

- Remove -

Remove candidates

Remove checked

Remove checked candidates

Remove unchecked

Remove unchecked candidates

Remove all

Remove all candidates

The Document Paths Dialog

image of the paths dialog The document paths dialog contains text input fields for setting the locations of the files needed by the validator. Under normal circumstances you do not need to edit these, but if you do so, make sure to enter directories as absolute paths, for example D:myFilesmyDirectory.

Name Description
DTD/ADTD The location of the document type definition (DTD) and attribute document type definition (ADTD) files. This path defaults to the 'externals' directory found in the validator install directory.
Default report save path The default directory where validation reports are saved.
Temporary path A non-writeprotected location where the validator can save temporary files.

The General Settings Dialog

image of the settings dialog The General Settings dialog contains the following two options:

Allowed time fluctuation
This slider control determines how much deviation is permitted during time value validation. If the value is set to 500, all discrepancies in time values below 500 milliseconds will be disregarded (not reported) by the Validator. This setting defaults to zero. For full conformance checking, it should remain set to zero. When set to zero all discrepancies will be reported.
Show advanced ADTD information
This setting determines if the validation report will include 'advanced' information about errors. When this option is turned off the report will include somewhat less information on those tests performed by the ADTD engine, however, the report will be more compact and may be easier to read. Details on the ADTD engine are given in the Validator Developer Manual.

Hotkey Reference

key function
CTRL + I Save report
CTRL + J Load report
CTRL + Q Exit program
CTRL + D Add single DTB to candidates list
CTRL + M Add multi volume DTB to candidates list
CTRL + L View candidate list
CTRL + E Validate selected candidate
CTRL + R Validate all candidates
CTRL + A Aborts all qued validations
CTRL + S Save document (Document Editor)
CTRL + F Search / Replace (Document Editor)
CTRL + K Follow link (Document Editor)
CTRL + B Go back (Document Editor)
CTRL + P Open document paths dialog
F1 Open help

Menu Reference

menu item function

- File -

File menu

Save report

Saves the report for the selected validation candidate in the Validation Report View

Load report

Loads a previously saved report

Exit

Exits the program

- Candidates -

Candidates menu

Add single DTB

Adds a DTB to the validation candidates list

Add multivolume DTB

Adds a multivolume DTB to the validation candidates list

Add single file(s)

Adds a single file to the validation candidates list

Ncc

Adds a single NCC file to the validation candidates list

Smil

Adds a single SMIL file to the validation candidates list

Master smil

Adds a single master SMIL file to the validation candidates list

Content doc

Adds a single content document file to the validation candidates list

Discinfo

Adds a single Discinfo file to the validation candidates list

Light Mode

Enables/Disables Light Mode

Disable All Audio tests

Enables/Disables Disable Audio Tests Mode

View candidates list

Opens the candidates list dialog

Clear all added

Removes all candidates from the validation candidates list

- Run -

Run menu

Run selected

Validates the selected validation candidate in the validate report view

Run all

Validates all validation candidates in the validation candidates list

Abort validation

Aborts all validations in the candidates list

- Editor -

Editor menu

Save document

Saves changes in the currently open document in the Document Editor

Search / Replace

Searches or replaces words or sentences within the currently open document in the Document Editor

Follow link

Follows the link of the first found <a> or <text> element after the cursor position in the open document

Go back

Returns to the previous document (only works if a document has been opened with "Follow link")

- Settings -

Settings menu

Document paths

Opens the Document Paths dialog

General settings

Opens the General Settings dialog

- Help -

Help menu

Open User Manual

Opens the User Manual in the mime connected html browser

Open Developer Manual

Opens the Developer Manual in the mime connected html browser

Error Log

Opens the Error Log dialog

About

Opens the About dialog

Screen Reader Use

All graphical items on the screen have hotkeys and menu equivalents.

The Validation Report View is a TreeView Control. To expand and collapse the branches use the arrow keys. While in the TreeView, to open a document associated with an error in the Document Editor, use ENTER. Cursor position is, if possible, set to the exact point where the error occurs. To go from the Validation Report View to the Error View, use TAB.

When moving around in a document in the Document Editor, the Status Bar contains current line and column information.

See the menu reference and the hotkey reference for further information.

DAISYpedia Categories: 


This page was last edited by DAISY1 on Friday, February 8, 2013 02:07
Text is available under the terms of the DAISY Consortium Intellectual Property Policy, Licensing, and Working Group Process.