A. The CD-ROM ~ll complete!' said the Toad triumphantly, pulling open a locker. 'You see ... everything you can possibly want...you'll find that nothing whatever has been forgotten ... ' Kenneth Grahame, The Wind in the Willows The disk that accompanies this book contains software and documenta­ tion for systems designed for use with SGML, and also for some which are more general-purpose but have some specific SGML applications. Although I have tried to make the documentation as obvious as pos­ sible, I have avoided starting on the bottom rung of trying to teach the use of the keyboard, the mouse, and the operating system (see the assumptions alluded to earlier, which are in section 1.3). Not all the programs described in the book are on the disk, as many of them are regular commercial products for which no free or demo version exists. By the same token, not all the programs on the disk are necessarily described in the book, as I have tried to make the disk as up to date as possible, and the lead-time for printing is longer than that for making the disk. If you don't have access to MS-Windows to use the Synex ViewPort browser provided (see next section), you can read the same information by using your regular Web browser to open the INDEX. HTM file on the CD-ROM. The disk is written in ISO 9660 format, so that it is usable on Macs, PCs, and Unix systems. 384 Peter Flynn A.1. BrOwsing the CD-ROM: using SyneX/lnso ViewPort Synex, makers of the ViewPort SGML browser engine for MS-Windows, have kindly provided a copy of their demonstration browser for you to use with this CD-ROM. It's not marketed as a separate product, because they license it to people who want to embed the browser technology in their own products, but this is the latest version and it provides a useful way of seeing what's what and using SGML to do so. If you're not running MS-Windows, you can use any regular (HTML) Web browser to view the same information in HTML files. MS-Windows users can run the browser directly off the CD-ROM using the browse. bat file. If you wish, you can copy the browser instal­ lation (the SYNEX folder) to your hard disk (for example to c: \Program Fi 1es \Synex), but you will need to update the configuration file SY.INI in the c: \wi ndows directory to reflect the correct hard disk letter. A.2. Words of warning about the software Two small warnings are needed: 1. The conditions in which you use the software, the nature of your data, and the configuration of your computer are outside my con­ trol, so please ask the manufacturer or the software author if you need further details about a product or the way it works, not me or my publisher. 2. All the programs on the disk have been obtained from reliable sources, either from the manufacturers themselves (in the case of commercial software), or from a trusted archive or the original author (in the case of public domain software). Where facilities exist the executables have been virus-checked, but as neither I nor my publisher wrote the programs, we cannot be held responsible for their contents, nor their effect on your system or data. A.3. How does It work? The CD-ROM is written in plain ISO 9660 format, so you can use it on Apple Macs, PCs (MS-DOS and MS-Windows), and Unix workstations Understanding SGML and XML Tools 385 which support the CD File System, but on older computers you may need to update your CD-ROM driver software (consult your supplier for details). CD-ROM format and filenames The ISO 9660 CD-ROM format (sometimes called a 'multisession' CD-ROM) can be used on multiple platforms because it restricts two aspects of the file system: • the file names and folder names are all UPPER CASE; • no folders can nest more than eight deep. For this reason, all software is kept in the following archive or compressed formats which contain the applications with preserved mixed-case filenames within them: • ZIP files (DOS/Windows and VMS): unwrap with UNZIP; • HQX files (Macs): unwrap with UnStufflt; • TAZ files (Unix): unwrap with gunzip then tar; In most cases there is a self-installing SETUP or make program which you run to install the application. In a few cases the setup is manual, and the software author has provided instructions in a README or INSTALL file. Unzipping and other public decompression tools are in the UT I LS folder in each platform directory. I have not modified any of the software in any way, so if there are instal­ lation problems, inquiries should be directed to the software author; please, not to me. Apart from the software, some of which is specific to certain platforms, there are DTDs, stylesheets, and SGML documentation which can be used on all systems (see section A.S below). Most of the examples and illustrations have been taken from MS-Windows versions of the software because that was the closest to hand at the time of writing, but the principles apply equally to all platforms. The top-level (root) directory of the CD-ROM has folders for the various platforms and one for the ViewPort browser (an application for MS-Windows to let you browse the SGML documentation on the disk): 386 Peter Flynn [j :J :J :J :J wi BfCl wnr mae '": soml ~ :.J'ims CATALOG' II Ra~ 8.htm fII] Rudme.Jom Ra~dm. _txt The SGML folder contains DTDs and reference documentation and has a different structure to the platform-specific folders. The PC folder is subdivided into DOS and Windows (I am not aware of any SGML software exclusively for Windows NT alone yet: 32-bit software for Windows is typically written to execute on Windows 95 as well as NT). Within the platform folders, the structure follows (where possible) the life-cycle approach of the chapters of the book: x fOe (dO _ I!oO> ~ :J :J :J .:J .::J a,<w"" d.v,101) edit CI~choes IUIrn OM! .:J ~ ....J 'wi! ~ ,w .n~ • .hU'n1 ,.,dme,soml """. """'H l!ffii~@ 12 ..).db) '1-"" Each of the upper-level folders has a plaintext INFO file containing information in unmarked text, so you can read it in any simple editor or word processor even if you haven't started using SGML yet. The same information is in two other files, an SGML README which you can use with the ViewPort demonstration browser supplied on the disk, and a HTML I NDEX file which you can read with any standard Web browser such as Opera, Netscape Navigator, or Microsoft Internet Explorer. In the SGML folder, the DTDS subfolder contains zipped copies of all the Document Type Descriptions covered in section 1.5.1.5, and the ENTITIES folder contains zipped copies of the standard ISO character entity files which are referred to by DTDs to specify symbols and ac­ cented characters. These are all plaintext files, so they are usable on all systems. There is a master CATALOG file in standard OASIS (SGML Open) format at the top level of the CD-ROM directory structure, which gives the equivalences between the file names for all the DTDs (and the character entity files) and their Formal Public Identifiers (explained in sections page 145 and page 153) . You can install all these files on your hard disk by using the setup program if you use a PC, or by copying them manually on other systems. The following folder names are rec­ ommended for installation, with 'dtds' and 'entities' subdirectories within them: Understanding SGML and XML Tools 387 Platform Disk prefix Directory name PC c: \sgml Mac Hard Disk :sgml Unix [none] /usr/local/lib/sgml VMS SYS$LOGIN: [.sgml] On shared system such as VMS and Unix, you may not have access to the root directory or the system disk, so you may have to install the folders by hand elsewhere withing your personal directory structure and make the relevant changes to the catalog file. In the other folders, the software is supplied either as self-extracting installation programs (. SEA files for Macs; . EXE files for PCs) or as plain compressed files (.ZIP, .GZ, or .SIT archives). The Unix software is in . TAR. GZ format. The dearchiving and uncompressing programs needed to handle these are in the UT I LS folders for Macs and PCs (Unix systems come with copies themselves already). If a program has installation instructions supplied by the author, these are included in each program subdirectory without change; sometimes in a file with a name such as INSTALL. If there were no separate instructions, I have provided some in a file of that name. Most of the self-installing software must be copied to your hard disk before trying to run the self-installer, because it needs to create temporary files, and this is not possible on a CD-ROM. I am told that there is a small amount of SGML software for the Atari and Amiga, which are still popular and useful machines, but I have been unable to track it down, even after many requests. Regrettably, there is still very little SGML-specific software available for VMS or Macs by comparison with the PC or Unix world. Despite two decades of proving its worth, the Mac is still regarded by many software developers as a niche machine for artists.