The content of Manuals Machine Volumes, which often contain hundreds or thousands of viewable pages, can be classified into a few distinct types of component files:
XML pages that conform to the Standard Document Type have three internal elements at the top-level.
The identification element is provided for use in control of documentation production. It includes details of author, versioning, change control and similar. Use of this element is optional, as organisations may prefer to use their own existing arrangements for source control.
The visiblecontent element is the container for the Blocks and Elements of the Standard Document Type.
The indexing element is crucial to the organisation of the Volume, and includes details such as:
The indexing element can also used to manage other types of content, such as PDFs and image files. These can be provided with 'Carrier Pages' that are a subset of the Standard Document Type. These need not have any visible content, but do have a complete indexing element, which includes a link to the PDF or other type of content file that it manages.
By creating a Carrier Page and providing Titles, TOC and Index details, any type of content can be seamlessly integrated into the Volume. The TOC and Index entries for this content point to the Carrier Pages, not to the actual content page files. The Manuals Machine Reader uses the carrier data to correctly present the underlying content page whenever it is selected from the a TOC or Index listing. There is no restriction on the type of Content Page that can be integrated in this way: they can be HTML, text files, any XML document type, TIFF files (for faxes), or any other file type that can be rendered by Internet Explorer or an installed plug-in.
Carrier Pages can optionally include visible content using the normal Block/Element viewable structures of the Standard Document Type. Where this exists the user is alerted via an indicator on the Control Panel and the user can display if wished. This mechanism enables notes on the source of the managed content to be carried along with it. For example:
Carrier Pages for images can include scaling rules, that enable the image to be resized when displayed.
The Manuals Machine Administration Package includes a Content File Importer that can process a batch of files (such as a set of photos from a digital camera) and automatically generate Carrier Pages for them with preliminary TOC and Index details.
With all the various types of content, and the possibility that individual pages could require many supporting image files, the Volume could become large and difficult to manage. The Manuals Machine allows arbitrary organisations of subfolders to be established as a framework for keeping things organised - the same practice as commonly employed for websites.
The root folder for the Volume is where the TOC and Index files are located. It is a requirement that any pages that are to be listed in TOC or Alpha Index must be placed in the root folder. Other volume content including the subjects of Carrier Pages or internal page components such as inline images or sound clips may be organised into subfolders is wished.
The Manuals Machine Reader is told the locations of all Volumes that it may be used for, by a file called LibraryConfig.xml which is prepared by the system administrator. If this configuration file is not available when the Reader instance is started, it will attempt to locate a configuration file on The Manuals Machine Website and use this to open the Library of Manuals Machine reference documentation.
The TOC for any Volume can extend to any number of chapter and subchapters, up to four levels deep. Note that for this purpose components such as Appendices and Prefaces are chapters - though the chapter titles could be 'Appendix A', Appendix B' etc.
The roadmap for this structure is contained in a single Master TOC File, which is located via the LibraryConfig.xml file. This sets out the complete logical TOC structure and instructions for generating the physical files. The Master TOC is established and maintained by the Volume Administrator. TOC files for the chapters and subchapters are generated by the Admin Package Compilers as the Volume contents are developed. The roadmap and the physical structure can be revised at any time using the Admin Package tools.
Content Pages are positioned in chapters by specifying, in their indexing element, the chapter-id of all chapters in which they are to be listed and their 'rank' in this listing - usually a simple ordinal but could be any collatable string value. The complete TOC for a Volume can be rebuilt at any time by running the TOC Compiler, which:
The TOC Compiler is one of several Administration Package tools for building and maintaining TOC structures. Some Author/Editor functions also operate on the TOC files, for example if a page is updated to specify that it belongs to a different chapter the change is applied immediately without requiring a compiler run.
The Alpha Index and other indexes are prepared by a similar method - edit the Content Pages (or Carrier Pages) to specify their indexing rules, and when all pages are ready run the required Index Compiler.