Internet Publisher's Toolbox 1.0

home *** CD-ROM | disk | FTP | other *** search

/ Internet Publisher's Toolbox 1.0 / Image.iso / toolbox / panorama / manual.z / PANOFUG.SGM < prev next >

Wrap

Text File | 1995-03-08 | 119.3 KB | 3,320 lines

<!DOCTYPE BOOK PUBLIC "-//Synex Information AB//DTD Manual Version 1.3//EN"[ <!ENTITY % PRO "IGNORE" -- for marked sections, relevance only for the PRO version --> <!ENTITY % windows "INCLUDE" -- for marked sections, relevance under Windows -- > <!ENTITY % mac "IGNORE" -- for marked sections, relevance under Macintosh --> <!ENTITY % motif "IGNORE" -- for marked sections, relevance under Motif --> <!ENTITY sp "SoftQuad Panorama"> <!ENTITY p "Panorama"> <!ENTITY lt "<"> <!ENTITY gt ">"> <!NOTATION GIF SYSTEM> <!ENTITY #DEFAULT SYSTEM NDATA GIF> <!NOTATION SGML PUBLIC "+//ISO 8879:1986//NOTATION STANDARD GENERALIZED MARKUP LANGUAGE//EN"> <!ENTITY panotr SYSTEM "PANOFTR.SGM" NDATA SGML -- The Tech Ref --> <![ %windows; [ <!ENTITY DocVer "&sp; for Microsoft Windows"> <!ENTITY platform "Windows"> ]]> <?TAGLINK URL URI> <![ %motif; [ <!ENTITY DocVer "&sp; for Unix/Motif"> <!ENTITY platform "Motif"> ]]> <![ %mac; [ <!ENTITY DocVer "&sp; for Macintosh"> <!ENTITY platform "Macintosh"> ]]> <!NOTATION SGML PUBLIC "+//ISO 8879:1986//NOTATION STANDARD GENERALIZED MARKUP LANGUAGE//EN"> ]> <BOOK> <FRONT> <TITLEGRP> <TITLE>&sp; <![ %PRO; [PRO ]]>User's Guide</TITLE> </TITLEGRP> <AUTHGRP> <CORPAUTH><ORGNAME>Developed by Synex Information AB, Sweden</ORGNAME></CORPAUTH> </AUTHGRP> <PUBFRONT> <INFOGRP> <DEFLIST> <TERM>Standard Identification</TERM> <DD>&sp; is an SGML System Conforming to International Standard ISO 8879—Standard Generalized Markup Language.</DD> <TERM>Published by</TERM> <DD><ORGADDR><ORGNAME>SoftQuad Inc.</ORGNAME> <STREET>56 Aberfoyle Crescent, Suite 810</STREET> <CITY>Toronto, </CITY><COUNTRY>Canada </COUNTRY><POSTCODE>M8X 2W4</POSTCODE> <PHONE>(416) 239–4801</PHONE> <FAX>(416) 239–7105</FAX> <EMAIL>Internet: mail@sq.com</EMAIL> <![ %PRO; [ <EMAIL>Technical Support: panorama-support@sq.com</EMAIL> ]]> </ORGADDR></DD> <![ %PRO; [ <TERM>Developed by</TERM> <DD><ORGADDR><ORGNAME>Synex Information AB</ORGNAME> <STREET>Kallforsvägen 24</STREET> <CITY>Bandhagen, </CITY><COUNTRY>Sweden </COUNTRY><POSTCODE>S-124 32</POSTCODE> </ORGADDR></DD> ]]> <TERM>Document version</TERM> <DD>&DocVer; First Edition (March 1995) Synex Information AB makes no warranty of any kind with respect to the completeness or accuracy of this document. Synex Information AB may make improvements and/or changes to the product(s) and/or programs described herein at any time and without notice. </DD> <TERM>Copyrights and Trademarks</TERM><DD> <CPYRT><DATE>© 1994-95</DATE> <CPYRTNME><ORGNAME> by Synex Information Aktiebolag, </ORGNAME> <COUNTRY>Sweden.</COUNTRY> </CPYRTNME> </CPYRT> <BO>All rights reserved.</BO> No part of this document may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means—electronic, mechanical, recording, or otherwise—without the prior written consent of Synex Information Aktiebolag, excepting its legal use as part of the &sp; software and brief quotes used in connection with reviews written specifically for inclusion in a magazine or newspaper. &sp; is a trademark of SoftQuad Inc. Other mentioned brand or product names are trademarks or registered trademarks of their respective holders. </DD> <TERM>Notice</TERM><DD>Agencies of the United States Government please note: <SC>RESTRICTED RIGHTS LEGEND:</SC> Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at <SC>DFARS 52.227–7013</SC> and in similar clauses in the <SC>FAR</SC> and <SC>NASA FAR</SC> Supplement.  <NAMELOC ID="TR-MAN"> <NMLIST NAMETYPE="ENTITY">panotr</NMLIST> </NAMELOC> <NAMELOC ID="TR-SSHS"> <NMLIST NAMETYPE="ELEMENT" DOCORSUB="panotr">SSHSEL</NMLIST> </NAMELOC>  </DD> </DEFLIST> </INFOGRP> </PUBFRONT> </FRONT> <BODY> <CHAPTER ID="WELCOME"><TITLE>Welcome to &sp;<![%PRO;[ PRO]]>!</TITLE> &p; is the first of a new breed of document browsers that improve access to large and highly structured documents, by state-of-the-art navigational aids. It is a browser that reads SGML directly. Building on the solid foundation of an international document standard (<XREF RID="CONCEPTS">ISO 8879 SGML</XREF>), it is truly in a class of its own…crisp and responsive! A short list of features: <LIST> <ITEM>Display of documents using a variety of styles.</ITEM> <ITEM>Display of dynamic table of contents (navigators).</ITEM> <ITEM>Inline or iconized graphics that can be teared off and zoomed into.</ITEM> <ITEM>Support for iconized inline elements, tables, and math.</ITEM> <ITEM>A graphical <XREF RID="OPTODD">occurrence density display</XREF> to highlight string search results.</ITEM> <ITEM>Contextual searches, where you use the structure of the document to define what parts are to be searched.</ITEM> <ITEM>Out-of-the-box support for hyperlinking based on HyTime, the international standard for hypertext.</ITEM> </LIST> The PRO version of &p; also supports: <LIST> <ITEM><XREF RID="WEBS">Layered HyTime-based Webs</XREF> to enrich your documents with user-defined links and annotations.</ITEM> <ITEM>Links to and from selected portions of graphics.</ITEM> <ITEM>A built-in editor for the design of style files.</ITEM> <ITEM>A built-in editor for defining dynamic table of contents—so-called navigators.</ITEM> <ITEM>Formatted printing of entire documents, or of selections only.</ITEM> </LIST> You may also be interested in the excellent SGML support: More precisely, &p; supports minimal SGML, the core syntax with some useful extensions such as long identifiers (extended <TT>NAMELEN</TT>), the shorttag feature, marked sections, full entity support, and parsing of the local declaration subset. <SECTION ID="ABOUT"><TITLE>About this manual</TITLE> This manual consists of: <LIST> <ITEM><XREF RID="WELCOME">Welcome to &sp;<![%PRO;[ PRO]]>!</XREF>, a short introduction to &p; features.</ITEM> <ITEM><XREF RID="INIT">Getting Started: A short tour of &p;</XREF></ITEM> <ITEM><XREF RID="CONCEPTS">Basic SGML Concepts</XREF></ITEM> <ITEM><XREF RID="MENUS">The &p; Menus</XREF></ITEM> <ITEM><XREF RID="SSHEDIT">Editing Style Sheets</XREF></ITEM> <ITEM><XREF RID="NAVEDIT">Editing Navigators</XREF></ITEM> </LIST> <![ %PRO; [The manual documents both the commercial &sp; PRO, and the free, unsupported version.]]> This version of the manual displays documentation <![ %PRO; [(including PRO features) ]]>relevant for the following platform(s): <![ %windows; [ MS Windows]]><![ %mac; [, Macintosh]]><![ %motif; [, Unix/Motif]]>. </SECTION> <SECTION ID="SUGGEST"><TITLE>Your suggestions</TITLE> We welcome your comments and suggestions on this documentation and on the program. These will be carefully considered for future versions. You can send e-mail to <TT>panorama@sq.com</TT>. </SECTION> </CHAPTER> <CHAPTER ID="INIT"><TITLE>Getting Started: A short tour of &p;</TITLE> This chapter gives you a quick review of central &p; features such as: <LIST> <ITEM>Browsing of files using navigators.</ITEM> <ITEM>String searching documents using markup and the occurrence density display.</ITEM> <ITEM>Switching style sheets.</ITEM> <ITEM>Exploring web functionality.</ITEM> </LIST> In addition, it describes very briefly some SGML concepts. <SECTION ID="BROWSER"><TITLE>Browsing SGML documents</TITLE> &sp; is a document browser that works in conjunction with NCSA Mosaic or Spyglass Mosaic, document browsers for the World Wide Web (WWW). &p; exists in two flavors: a freely available and non-supported version, and a supported, enhanced PRO version. <![ %PRO; [ This manual includes documentation on features relevant to the PRO version.]]> Using Mosaic, you can open any SGML file, and with the proper configuration, Mosaic will launch and display the SGML document using &p;. In the PRO version, this can be done directly from within the &p; application. <![ %PRO; [ To browse an SGML document directly with &p;, you can either select <MENU>Open File</MENU> from the menu <MENU>File</MENU>, or click the corresponding tool bar icon: &openfile.gif; ]]> <FIGGRP> <FIG NAME="PANODEMO.GIF"> <TITLE>&p; displays documents in a resizable window—the document contents wrap to fit. Optionally, the left part of the window contains a dynamic table of contents (a so-called navigator) or tree view of the document structure.</TITLE> </FIGGRP> <SUBSECT1><TITLE>Selecting a style sheet</TITLE> &p; style sheets are separately stored formatting rules that specify how the contents of SGML documents are to be displayed on screen <![ %PRO; [(or printed)]]> by the application. <![ %PRO; [<XREF RID="ATTCH">]]>Currently attached<![ %PRO; [</XREF>]]> styles (for the particular class of documents that the document belongs to) are listed at the top of the <MENU>Styles</MENU> menu. Selecting any of these styles updates the browser window to the selected style. The current style is indicated with a checkmark prefix. </SUBSECT1> <SUBSECT1><TITLE>Navigating SGML Documents</TITLE> Normally, the left part of the &p; application window looks like a table of contents, containing headings extracted from the document. This portion of the window is called a navigator and is separated from the document contents by a vertical divider bar. The document appears to the right of the bar. The width of the navigator can be changed by dragging this bar horizontally; dragging the bar far to the left removes the navigator display entirely. <FIGGRP><FIG NAME="NAVPM.GIF"> <TITLE>The navigator is used to position the browser window. Each entry is extracted from the document. Entries prefixed with a plus icon sign contain subitems which are revealed by clicking on the icon. The arrow shows your current location in the document.</TITLE> </FIGGRP> The navigator window is used to scroll the browser window to the location of each corresponding navigator entry. The contents of the navigators are taken from the document, so the navigator can be regarded as a subset of the document, used for navigation. In the navigator, some of the entries are prefixed with a plus sign, while others are prefixed with a minus sign. The plus sign indicates that there are sub-items contained by the navigator entry, and that these items can be revealed by clicking the plus icon; the navigator will expand and display the contained entries. Correspondingly, a minus sign indicates that the entry has been fully expanded but can be collapsed back again. Finally, some navigator entries are prefixed with a square dot. These items cannot be expanded or collapsed, as they are entries that are at the bottom of the navigator hierarchy. A yellow arrow icon designates the current location in the document. To position the browser contents at a navigator entry, click on the navigator text itself (not the icon that prefixes it). <BO>Try out the navigator to see how it works!</BO> Return to this location by clicking the backtrack button in the tool bar: &backtrck.gif;. This will become active as soon as you've scrolled the browser using the navigator. Equivalently, click on the corresponding navigator entry (the line with the title Navigating SGML Documents). <SUBSECT2><TITLE>Switching to an alternative navigator</TITLE> The menu <MENU>Navigator</MENU> displays all of the currently attached navigators. If there is some other navigator available, just pick its name from the list displayed in this menu. To hide the navigator and only display the document, select the menu <MENU>None</MENU>. Equivalently, drag the divider bar far to the left. </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>String searching</TITLE> String searching will be covered in detail later. Two valuable string searching features will be covered below. To do a string search in the document: <LIST> <ITEM>From the <MENU>Edit</MENU> menu, select the item <MENU>Search&hellip</MENU>.</ITEM> <ITEM>A dialog will be displayed for entering the search string.</ITEM> <ITEM>Click the button <BUTTON>OK</BUTTON>.</ITEM> </LIST> The search dialog is dismissed as the results of the search are highlighted in the browser. <SUBSECT2 ID="OPTODD"><TITLE>Occurrence Density Display</TITLE> When you perform a string search, a column may appear to the left of the scroll bar; this is the graphical occurrence density display. For each hit in the document, there is a thin line at the corresponding position. The usefulness of this simple graphical display is striking: at a glance, you locate all of the occurrences, and immediately see if there is a concentration in some part(s) of the document. Positioning the mouse cursor in the occurrence density display and clicking scrolls the browser to the position represented by the line nearest to the cursor. This graphical aid is optional as its display can be suppressed by toggling the corresponding setting in the <MENU>Options</MENU> menu. <FIGGRP> <FIG NAME="SEARCH.GIF"> <TITLE>The <TT>Search</TT> dialog is used to enter strings to be sought. At the far right of the window, next to the scroll bar, is &p;'s occurrence density display.</TITLE> </FIGGRP> </SUBSECT2> <SUBSECT2><TITLE>Contextual Searching</TITLE> At times, the graphical feedback provided by the occurrence density display may not be enough; this is the case when searching for a word that is extremely prevalent. (As an example, think of searching for the word <Q>ignition</Q> in a manual on the ignition system of an engine). Fortunately, the SGML methodology of structuring documents hierarchically can be put to good use: you can restrict string searching to any portion of the document (naming any structural component—an element in SGML parlance). The subject of contextual searches will be covered in depth later. As an example of what you can do, it is possible to restrict string searching to only headings, say, at the topmost level. Because &p; lets you restrict searching to any element, you are only limited by the granularity of the document <XREF RID="markup">markup</XREF>! </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Viewing graphics</TITLE> Graphics can be presented either inline—intermixed with the document content—or tucked away behind an icon; clicking the icon opens up a separate window. In both cases, the graphics can be zoomed into. The choice of presentation (inline vs. behind icons) is simply a style sheet setting. <SUBSECT2><TITLE>Tearing off graphics</TITLE> When graphics are presented inline, you may want to keep a copy on-screen, in a separate window, as you scroll on. To do this: <LIST> <ITEM>Place the cursor over the graphics.</ITEM> <ITEM>Select the pop-up menu item <MENU>Tear Off…</MENU> displayed by <![ %windows; [clicking the right mouse button.]]> <![ %motif; [clicking the right mouse button.]]> <![ %mac; [Alt-clicking.]]></ITEM> </LIST> <![ %windows;[ <FIGGRP> <FIG NAME="GRRBMENU.GIF"> <TITLE>A copy of an inline graphic is displayed in a separate window by positioning the cursor over the graphics and selecting <MENU>Tear Off…</MENU>from the right mouse button popup menu.</TITLE> </FIGGRP> ]]> </SUBSECT2> <SUBSECT2><TITLE>Graphics Hot Spots</TITLE> In addition, you can link to and from graphics, e.g. to create a hyperlink from a document that describes some object to a graphics that depicts it. </SUBSECT2> </SUBSECT1> <SUBSECT1 ID="WEBS"><TITLE>Webs</TITLE> Webs are containers for user-defined information—such as annotations, links, and bookmarks. Because &p; works in a multi-user, networked environment, it distinguishes between merely using a web (displaying its contents), vs. being able to modify its contents—to edit it. An open web (that is active and whose contents are displayed) is defined as being mounted. Web files use the file suffix <TT>.WEB</TT> by convention. They are text files with SGML/HyTime markup and can thus be browsed by &p; just like any other SGML document. <SUBSECT2 ID="WEBOPEN"><TITLE>Opening and Creating Webs</TITLE> To open an existing web, or to create a new web, do as follows: <LIST> <ITEM>Select <MENU>Web Manager…</MENU> from the menu <MENU>Webs</MENU>.</ITEM> <ITEM>In the Web Manager dialog that appears, pick the button <BUTTON>Mount…</BUTTON> and select the web to open if it already exists. </ITEM> <ITEM>If you want to create a new web, enter its filename in the editing window. &p; will then prompt you for a symbolic name used for display in the <MENU>Webs</MENU> menu. </ITEM> <ITEM>Once the web has been mounted, its symbolic name will appear in the list of mounted webs in the Web Manager. </ITEM> <ITEM>Click on the <BUTTON>OK</BUTTON> button to dismiss the Web Manager dialog.</ITEM> </LIST> The symbolic name of the web will now also appear in the <MENU>Webs</MENU> menu. &p; remembers what webs were open and automatically makes them active again when you launch &p;. This information is stored in the settings file <TT>PANORAMA.INI</TT> in the main Windows directory. </SUBSECT2> <SUBSECT2 ID="WEBEDIT"><TITLE>Editing a Web</TITLE> To edit a web, select its name from the <MENU>Webs</MENU> menu. A checkmark prefix by the web shows that it is editable. You can only edit one web at a time, but you can have any number of webs open (active and mounted). </SUBSECT2> <SUBSECT2><TITLE>Web Anchors</TITLE> The information that is stored in webs is always attached to a contiguous selection called an anchor. The location of the anchor within the document is stored using SGML and HyTime. This is done automatically by &p;. Even though your initial selection may designate only portions of words, &p; will transform it so that only whole words are addressed. (This is due to the way the corresponding location is stored using HyTime). </SUBSECT2> <SUBSECT2><TITLE>Creating Annotations</TITLE> To create an annotation: <LIST> <ITEM>Highlight part of the document.</ITEM> <ITEM>Select the item <MENU>Annotate…</MENU> from the menu <MENU>Webs</MENU>. Alternatively, select the corresponding tool bar icon: &annotbut.gif; A dialog appears that lets you enter your annotation. </ITEM> <ITEM>In the annotation dialog, you may optionally enter a name describing the annotation. This note text defaults to the first words of the highlighted text portion.</ITEM> <ITEM>After entering the annotation text, click the <BUTTON>OK</BUTTON> button. An icon appears to indicate the presence of your annotation.</ITEM> </LIST> <SUBSECT3><TITLE>Naming Web Anchors</TITLE> The naming of web anchors is potentially useful for making semantic distinctions, or to clarify the reason behind an annotation. By combining named anchors with the &p; feature of multiple simultaneous webs, you can qualify the web information being added to the document. An example could be reviewers' comments—each supplying one or more webs—and using the naming feature to distinguish between various kinds of critique or comments. <NOTE>In the DTD used by &p; for webs, annotations are encapsulated by the <TT>note</TT> tag and the name by a <TT>head</TT> tag.</NOTE> </SUBSECT3> </SUBSECT2> <SUBSECT2><TITLE>Creating Bookmarks</TITLE> Bookmarks are initially created in exactly the same way as annotations. <LIST> <ITEM>Once the annotation dialog appears, just click in the <TT>Bookmark</TT> checkbox.</ITEM> <ITEM>You may optionally enter a note describing the bookmark (naming the bookmark).</ITEM> </LIST>The bookmark will subsequently appear in the <MENU>Bookmarks</MENU> menu. Picking a bookmark from the menu scrolls the browser to the corresponding location. <NOTE>Note that the bookmark remains available as long as the web remains open—even when you are browsing some other document.</NOTE> </SUBSECT2> <SUBSECT2><TITLE>Creating Links</TITLE> You can create hyperlinks between selections in any SGML files, where the selections can be either text or graphics.<![ %PRO; [<XREF RID="HOTSPOT"> Links in graphics</XREF> will be covered below.]]> <SUBSECT3><TITLE>Begin Link</TITLE> To create a link: <LIST> <ITEM>Highlight a portion and select <MENU>Begin Link…</MENU> from the menu <MENU>Webs</MENU>. Alternatively, select the corresponding tool bar icon: &beglink.gif; </ITEM> </LIST> One of the link endpoints—the source anchor—has now been defined. This needs to be connected to a target anchor. </SUBSECT3> <SUBSECT3><TITLE>Connect Link</TITLE> To complete the link, make a selection as endpoint and: <LIST> <ITEM>Select <MENU>Connect Link…</MENU> from the menu <MENU>Webs</MENU>. Alternatively, select the corresponding tool bar icon: &conlink.gif;</ITEM> </LIST> A dialog appears that lets you optionally name the link source and target anchors. </SUBSECT3> </SUBSECT2> <SUBSECT2><TITLE>Deleting Web Objects</TITLE> Annotations, bookmarks, and link endpoints are all deleted in the same way. There are two ways of removing them: <LIST> <ITEM>Position the cursor over the icon of the web object.</ITEM> <ITEM>Press down the <![ %windows; [the right]]> mouse button and select <MENU>Delete Anchor</MENU> from the popup menu that appears.</ITEM> </LIST> Note that in the case of a link, the other link endpoint is not removed, but its icon changes into an annotation icon. Alternatively, select <MENU>Web Manager</MENU> from the <MENU>Webs</MENU> menu: <LIST> <ITEM>Select the anchor to delete in the Web Manager dialog.</ITEM> <ITEM>Press the <BUTTON>Remove</BUTTON> button.</ITEM> </LIST> </SUBSECT2> <SUBSECT2><TITLE>Closing the Web</TITLE> When you are done editing a web, select it from the menu <MENU>Webs</MENU>: it is the web with the checkmark prefix. If you choose to close the web altogether so that its contents (annotations, bookmarks, or links) are not displayed, select <MENU>Web Manager</MENU> from the <MENU>Webs</MENU> menu. In the Web Manager dialog, select the web and press the button <BUTTON>Dismount</BUTTON>. </SUBSECT2> </SUBSECT1> </SECTION> <SECTION ID="STYLES"><TITLE>Style Sheets</TITLE> The notion of style sheets has already been mentioned in passing a few times. As SGML creates a structure upon documents, the tags normally reflect some logical ordering of the information contained in the document. One could also represent layout information directly using tags, but this is not the norm (an exception perhaps being low-level emphasis tags to indicate <BO>bold</BO> or <IT>italicized</IT> text). <SUBSECT1><TITLE>Content-oriented vs. structure-oriented tagging</TITLE> Because this document follows rather closely the tag set of an existing DTD (the ISO 12083 BOOK DTD), most of the tags in this document are structure-oriented: they identify concepts such as headings, footnotes, and paragraphs. In comparison, a content-oriented tagging approach captures the meaning of the tagged information. As an example, rather than represent a sequence of steps as a list, a content-oriented approach could break the information down into pre-conditions, a sequence of steps, post-conditions, and a result. Irrespective of the tagging approach, the information must eventually be formatted. Publishing practices have been refined over centuries for publishing on paper; adequate representations for on-line media are gradually being developed. </SUBSECT1> <SUBSECT1><TITLE>Mapping of elements to styles</TITLE> Style sheets are one way to define the formatting to take place when processing an element; this is the approach being used in &p;. As style sheets are stored separately from the document, you can have any number of them. Also, because the style definitions are based on elements derived from a DTD, every document based on that same DTD can share the same set of style sheets. <SUBSECT2><TITLE>Style sheet processing</TITLE> There is an entire chapter devoted to style sheet formatting. Here is just a short list to give an indication of what is possible to achieve using &p; style sheets. <LIST> <ITEM>Display element contents using any available font.</ITEM> <ITEM>Show graphics in-line.</ITEM> <ITEM>Insertion of text, attribute values, or environment variables before and/or after elements.</ITEM> <ITEM>Conditional processing of elements, using criteria on attribute values, or on environment variables.</ITEM> <ITEM>Hiding elements behind icons, so that the contents are displayed in a separate window when the icon is clicked</ITEM> <ITEM>Optionally, suppressing the display of elements entirely.</ITEM> <ITEM>Indentation relative to parent elements (useful for lists, e.g.).</ITEM> <ITEM>Format engineering math and tables.</ITEM> </LIST> </SUBSECT2> </SUBSECT1> </SECTION> <SECTION ID="HTMLSGML"><TITLE>The relationship between HTML and SGML</TITLE> HTML is the acronym for the HyperText Markup Language, and consists of a set of tags originally developed at the European laboratory for particle physics CERN. The original HTML was only loosely based on SGML, but the web community is slowly adapting HTML towards SGML. A quick plug in passing: The SoftQuad HoTMetaL editor is an example of that effort. The main distinction between HTML and SGML is that the former can be considered an application of the latter: HTML can be expressed using SGML. The virtue of HTML is its simplicity, allowing for an impressive growth in the number of documents that can be reached across the Web. Its simplicity is however also one of the reasons why various software houses have begun creating their own flavor of WWW browsers, e.g. to accomodate user demands regarding better layout support. Sadly, this trend is counter to the portability of documents, as HTML documents now are gradually becoming dependent on specific browsers. Fortunately, the SGML standard lets you design and encode your documents freely while retaining complete portability. In addition, SGML documents are checked for validity regarding their syntax according to the SGML standard, while many existing HTML documents have been authored with the only requirement that they will display nicely in a World Wide Web browser. In practice, HTML documents are often not valid SGML. This will probably change over time, as more SGML-capable authoring tools become generally available. There is certainly a place for both to fill in the Web community. </SECTION> </CHAPTER> <CHAPTER ID="CONCEPTS"><TITLE>Basic SGML Concepts</TITLE> &p; is a browser for displaying SGML documents. SGML, the Standard Generalized Markup Language, is an international standard (ISO/IEC 8879) and defines rules by which to encode documents in a neutral manner, so that documents become independent of hardware and software. Typically, an SGML document's technical lifetime will outlast the computer system on which it has been authored. In essence, SGML is all about modeling information, of imposing structure upon data. The data can be—quite literally—anything, as SGML has ways of handling <BO>any</BO> kind of data. As an illustration of that statement, the only international standard for hypermedia (HyTime) is an application of SGML. Below is a short introduction to SGML concepts and terminology. <SECTION ID="MARKUP"><TITLE>Generalized Markup</TITLE> The information modeling is achieved by markup, special codes inside the file that indicate where various data items begin and end; the markup is wrapped around the content it describes. An SGML document thus consists of structure and contents. The markup is inserted using tags, which are identifiers surrounded by pointy (angle) brackets. By itself, SGML is entirely neutral, and says nothing about why you would want to tag certain data, nor what you would call the corresponding element. (In contrast, HyTime adds to the SGML methodology a meaning (semantics) to certain constructs that are useful when dealing with hypermedia). This tagging scheme is called <BO>generalized markup</BO> because it lets you identify the logical structure of your document, instead of directly specifying its layout. The presentation issues can be addressed e.g. by using style sheets that define the presentation of elements. </SECTION> <SECTION ID="ELEMS"><TITLE>The Scoop on Elements</TITLE> The tags surround contents—which in turn is normally also marked up using tags down to a certain granularity. What you choose to define (i.e. to mark up using tags), and what you call the corresponding element is up to you. SGML provides the formalism by which you structure the information. As an example out of the blue, assume you were tagging information about cars: While labeling a car as an <TT>automobile</TT> is correct, this is a rather coarse measure of information. Additional data—such as the car's make, color, and mileage—could be contained by the <TT>automobile</TT> tag, but you'd probably want to structure your information object into additional pieces. Elements thus provide a way of breaking up information objects into components and sub-components. It is up to the information provider to distinguish what is meaningful to tag. If you are curious about the tag density of this document, you can have the element encapsulation displayed by toggling <XREF RID="STAGS">Show Tags</XREF> in the <MENU>Options</MENU> menu).</SECTION> <SECTION ID="ATTRS"><TITLE>Attributes</TITLE> In SGML, you also have the option of adding information to elements using attributes. The attributes are written inside the tags and do not form part of the document contents—an attribute is a piece of information about the element. Examples of attribute uses are: <LIST> <ITEM>Assigning an element a unique identifier (so that the element can be cross-referenced)</ITEM> <ITEM>As a placeholder for a text string used in indexing (generated by some processing step)</ITEM> <ITEM>A reference to an image file.</ITEM> <ITEM>As an information repository that provides meta-information about the element itself: a scholar could e.g. put in some degree of certainty, readability index or whatever, that in some way pertains to the contents of the element.</ITEM> </LIST> Just like elements, attributes are also named by using identifiers. </SECTION> </CHAPTER> <CHAPTER ID="MENUS"><TITLE>The &p; Menus</TITLE> &p; has a main menu and immediately below it, a tool bar that contains icons for often used commands. At the bottom of the screen is a status bar that echoes application activities. In addition, &p; displays a menu whose contents depend on the location of the cursor when <![ %windows; [the right mouse button is]]> <![ %motif; [the right mouse button is]]> <![ %mac; [the <TT>alt</TT> key and the mouse button are simultaneously]]> depressed. In the text that follows, there are mentions of system configuration files such as <TT>ENTITYRC</TT> and <TT>CATALOG</TT>. Disregard those references for the time being, as they are not important in day-to-day work. <SECTION ID="FILEMENU"><TITLE>The File Menu</TITLE> The File menu contains commands for opening, closing, and printing SGML files. The corresponding menu items will be covered in the next subsections. When you open an SGML file, a certain amount of processing happens. This activity is reflected in the application status bar at the bottom of the screen: While &p; is processing, the status bar displays the various steps in bringing an SGML document fully formatted and navigable onto the screen: <LIST> <ITEM>The document instance is fetched, and the corresponding DTD is identified (from the document's so-called <TT>DOCTYPE</TT> declaration). &p; supports the use of the document type declaration subset, so any such declarations are processed first; subsequently, the DTD is parsed.</ITEM> <ITEM>Once the DTD structure is known, &p; reads the document itself and builds up the document structure in memory.</ITEM> <ITEM>Finally, the style sheet associated with the DTD, and normally a navigator definition as well, are applied in creating the formatted presentation that is displayed on-screen.</ITEM> </LIST> The DTD and the files it may include by reference, the style sheet and navigator definition, and the document itself, are fetched through the web server or from the local file system, should they be available. <![ %PRO; [ <SUBSECT1><TITLE>Open File</TITLE> The <MENU>Open File…</MENU> command lets you select any SGML file for display with &p; PRO—which thus works as a stand-alone SGML document browser in addition to its companion role to Mosaic. </SUBSECT1> ]]> <SUBSECT1><TITLE>Open URL</TITLE> The <MENU>Open URL…</MENU> command lets you access any URL on the WWW, for display with &p; or Mosaic. </SUBSECT1> <SUBSECT1><TITLE>Close</TITLE> The <MENU>Close</MENU> command closes the current document. Previously parsed and displayed documents are maintained (if possible) in a cache, to speed up a subsequent return to the document during the session. </SUBSECT1> <SUBSECT1><TITLE>Reload</TITLE> The <MENU>Reload</MENU> command forces &p; to reparse the document, by-passing a possible pre-parsed copy of the document in the application document cache. The main reason for issuing this command would be viewing documents that have been edited since first being opened by &p;—a previously parsed copy would not reflect the changes. This capability of immediately browsing an SGML file is a key feature of &p;. </SUBSECT1> <![ %PRO; [ <SUBSECT1><TITLE>Print</TITLE> The <MENU>Print…</MENU> command lets you print the document being browsed, including one or more navigators, to get page-numbered table of contents, lists of figures, etc. <FIGGRP> <FIG NAME="PRINTDLG.GIF"> <TITLE>The Print dialog is used to set various options when printing a document. The hard copy is based on any of the available style sheets, along with optional navigators. In addition, settings such as printing of page numbering, current date, and suppressing of cross-reference resolution on hard copy are available as well.</TITLE> </FIGGRP> <SUBSECT2><TITLE>The Print Dialog</TITLE> The topmost line of the Print dialog displays the currently selected printer, and the document title (if designated) is displayed on the next line. Beneath are two lists displaying available style sheets and navigators for the current document. Any style sheet can be selected for printing, in addition to one or more navigators as well. The following printing options can be set using check boxes in the print dialog: <DEFLIST REND="TABLE"> <TERM>Print Selection Only</TERM> <DD>This check box is automatically selected when there are <XREF RID="PRINTSEL">navigator entries</XREF> that have been selected for printing. In addition to printing the corresponding selected portions of the document, direct navigator entry ancestors will also be printed, so that the context of the item being printed is preserved.</DD> <TERM>Indent Navigator</TERM> <DD>This setting indents the printed navigator entries so that the indentation reflects the hierarchy level.</DD> <TERM>Top Border</TERM> <DD>This check box activates printing of a horizontal rule at the top of each page.</DD> <TERM>Bottom Border</TERM> <DD>This check box activates printing of a horizontal rule at the bottom of each page.</DD> <TERM>Page Number</TERM> <DD>This pull-down menu lets you select the placement, if any, of the page number: in the header or footer, with a choice of justification (left, centered, or right).</DD> <TERM>Date</TERM> <DD>This pull-down menu lets you select the placement, if any, of the current date: in the header or footer, with a choice of justification (left, centered, or right).</DD> <![ %windows; [ <TERM><BUTTON>Setup</BUTTON> </TERM> <DD>This button lets you adjust the Windows printer settings.</DD> ]]> <TERM><BUTTON>Cancel</BUTTON> </TERM> <DD>This button lets you exit the dialog without printing the document.</DD> <TERM><BUTTON>Print</BUTTON> </TERM> <DD>Pressing this button will print the document according to the current settings.</DD> </DEFLIST> </SUBSECT2> <SUBSECT2><TITLE>Specifying a background label for printed pages</TITLE> To add a background label to hard copy output, you have to add an entity named <TT>PrnBG</TT> (case is significant) to the style sheet. This is done by editing the style sheet file directly. <NOTE>Make sure that the file you are editing is the intended style sheet. To understand &p;'s handling of style sheets, see the section <XREF RID="TR-SSHS">Style Sheet Selection</XREF> in the <XREF RID="TR-MAN">&p; Technical Reference</XREF>.</NOTE> A style sheet definition begins with a <TT>DOCTYPE</TT> declaration such as: <LIT> <!DOCTYPE STYLESHEET PUBLIC "-//Synex Information AB//DTD Stylesheet Explorer//EN"> </LIT> The background label is declared in the local declaration subset, such as: <LIT> <!DOCTYPE STYLESHEET PUBLIC "-//Synex Information AB//DTD Stylesheet Explorer//EN" [ <!ENTITY PrnBG "PRELIMINARY! ** DO NOT REDISTRIBUTE **"> ]> </LIT> The label is printed across the page, from the left bottom to the right top. The angle of the baseline is calculated as a function of the output page height and width. </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Printer Setup</TITLE> The <MENU>Printer Setup…</MENU> menu lets you adjust the Windows printer settings. </SUBSECT1> ]]> <SUBSECT1><TITLE>Exit</TITLE> The <MENU>Exit</MENU> command terminates the application. </SUBSECT1> <![ %mac; [ <SUBSECT1><TITLE>Page Setup</TITLE> The <MENU>Page Setup…</MENU> command lets you adjust the printer settings. </SUBSECT1> <SUBSECT1><TITLE>Quit</TITLE> The <MENU>Quit</MENU> command terminates the application. </SUBSECT1> ]]> <FIGGRP ID="PRINTSEL"> <FIG NAME="PRINTSEL.GIF"> <TITLE>Particular portions of a document can be selected for printing through the navigator display. The hard copy output will contain both the contents of the selected items and direct parent navigator entries.</TITLE> </FIGGRP> </SECTION> <SECTION ID="SEARMENU"><TITLE>The Edit Menu</TITLE> <SUBSECT1><TITLE>Edit</TITLE> The <MENU>Edit</MENU> menu lets you copy the current selection into the clipboard. </SUBSECT1> <SUBSECT1><TITLE>Search</TITLE> String searching within a document can be done in either full-text or by restricting the search to specified elements (so-called contextual search). The <MENU>Search…</MENU> command brings up a dialog box for entering a search string. When you click on the <BUTTON>OK</BUTTON> button, the dialog is dismissed and the search results are displayed. The search string can optionally be treated as case sensitive, meaning that capitalized and lower case letters must match exactly as entered. The button at the far right of the dialog is a pull-down menu for selecting a previously entered search string. <SUBSECT2><TITLE ID="SRFEEDB">Search Result Feedback</TITLE> Occurrences of the sought string are shown highlighted in the document window. If the option <MENU>Occurrence Density Display</MENU> is selected, the far right of the window will contain a graphical display of matches. &p;'s occurrence density display corresponds to a scroll bar where each hit is displayed with a horizontal line at the corresponding position. It lets you directly locate the relative position and density of search hits. Placing the cursor over the display and pressing the <![ %windows; [left]]><![ %motif; [left]]> mouse button will scroll the window to that occurrence. </SUBSECT2> <SUBSECT2><TITLE>Contextual Searches</TITLE> &p; lets you perform contextual searches using a simple query language. To restrict searches to a specified tag, specify the keyword <TT>in</TT> followed by the tag, enclosed by angle brackets, e.g. <LIT> ignition in <ST> </LIT>will search for occurrences of the word <Q>ignition</Q> within the tag <TT>ST</TT>. It does not matter whether tags are visible or not (see <MENU><XREF RID="STAGS">Show Tags</XREF></MENU> in the <MENU>Options</MENU> menu). The full syntax and possibilities of the query language are defined in the next section. <SUBSECT3><TITLE>The &p; Query Language</TITLE> The symbol <TT>::=</TT> represents the expression <Q>is defined as</Q>. Formally, the syntax of the query language is: <TABLE REND="nogrid"> <TBODY> <ROW> <CELL>QueryExpression</CELL> <CELL>::=</CELL> <CELL>QueryTerm ( AND | OR ) QueryExpression</CELL> </ROW> <ROW> <CELL>QueryTerm</CELL> <CELL>::=</CELL> <CELL>QueryFactor ( IN | CONT ) QueryExpression</CELL> </ROW> <ROW> <CELL>QueryFactor</CELL> <CELL>::=</CELL> <CELL>TextSpecification | TagSpecification | ( QueryExpression )</CELL> </ROW> <ROW> <CELL>TextSpecification</CELL> <CELL>::=</CELL> <CELL>( char+ | literal )+</CELL> </ROW> <ROW> <CELL>TagSpecification</CELL> <CELL>::=</CELL> <CELL>< tagname ></CELL> </ROW> <ROW> <CELL>char</CELL> <CELL>::=</CELL> <CELL>any characters except the keywords <TT>AND OR IN CONT</TT> or the characters <TT>"</TT> and <TT>'</TT>. </CELL> </ROW> <ROW> <CELL>literal</CELL> <CELL>::=</CELL> <CELL>any characters delimited by <TT>'</TT> or <TT>"</TT>.</CELL> </ROW> <ROW> <CELL>tagname</CELL> <CELL>::=</CELL> <CELL>a name string, i.e. a generic identifier (GI) of the form <TT>[A-Za-z0-9]+</TT></CELL> </ROW> </TBODY> </TABLE> This permits the formulation of queries like:<FOOTNOTE>It also allows (a bit surprisingly) for strange queries such as <TT> <IT> in "the wonderful &p; Application"</TT> i.e. find all italics in strings equaling "the wonderful &p; Application". Perhaps some linguist will find a use for this <Q>feature</Q>?</FOOTNOTE> <TABLE REND="NOGRID"> <TBODY> <ROW> <CELL><![ CDATA [<title> in (<chapter> or <section>)]]></CELL> <CELL>Find all titles within chapters or sections.</CELL> </ROW> <ROW> <CELL><![ CDATA [John Doe in <footnote>]]></CELL> <CELL>Find the string <Q>John Doe</Q> in footnotes.</CELL> </ROW> <ROW> <CELL><![ CDATA [ cont <footnote>]]></CELL> <CELL>Find all elements p that contain footnote element(s).</CELL> </ROW> </TBODY> </TABLE> </SUBSECT3> <SUBSECT3><TITLE>Searching for elements with attribute values</TITLE> The <TT>TagSpecification</TT> description is actually a bit more complex, as you can enter one or more attribute values in the search specification: <LIT> John Doe in <person type=programmer> </LIT>Listing multiple attribute name and attribute value pairs such as <LIT> John Doe in <person type=programmer compiler=borland></LIT> will search for elements where all conditions are met (a logical AND). </SUBSECT3> </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>First</TITLE> The <MENU>First</MENU> command scrolls the window to the first place it occurs in the document. </SUBSECT1> <SUBSECT1><TITLE>Previous</TITLE> The <MENU>Previous</MENU> command scrolls the window to the previous (undisplayed) occurrence of the sought string. </SUBSECT1> <SUBSECT1><TITLE>Next</TITLE> The <MENU>Next</MENU> command scrolls the window to the next (undisplayed) occurrence of the sought string. </SUBSECT1> <SUBSECT1><TITLE>Last</TITLE> The <MENU>Last</MENU> command scrolls the window to the last occurrence of the sought string. </SUBSECT1> <SUBSECT1><TITLE>Back</TITLE> The <MENU>Back</MENU> command lets you go back to places you were just at: this is useful for retracing your steps after exploring one or several documents. </SUBSECT1> <SUBSECT1><TITLE>Forward</TITLE> The <MENU>Forward</MENU> command is used to cycle along a trail of positions that have been backtracked. It undoes the effect of backtracking. </SUBSECT1> </SECTION> <SECTION ID="OPTSMENU"><TITLE>Options</TITLE> The <MENU>Options</MENU> menu groups the toggling of settings that modify the application's behavior and appearance such as the display of the tool bar (the row of icons at the top of the screen), the display of the status bar (used to echo the application status and general information), and the display of the default navigator for each document window. The options are automatically saved between sessions, and are stored in the settings file <TT>PANORAMA.INI</TT> in the main Windows directory. <SUBSECT1><TITLE>Show Tool bar</TITLE> The application tool bar is displayed when <MENU>Show Tool Bar</MENU> is checked. The tool bar groups frequently used commands into a graphical, point-and-click set of buttons. Some buttons are dimmed when they are not applicable: as an example, you cannot create annotations if you have no editable web open, as the annotations are stored in web files. For the same reason, the <BUTTON>Forward</BUTTON> button is dimmed until you <BUTTON>Backtrack</BUTTON>. <SUBSECT2><TITLE ID="TBAR">Tool Bar Buttons</TITLE> Going from left to right, the tool bar buttons are shortcuts for the following functions. <DEFLIST REND="TABLE"> <TERM>&openurl.gif; <BUTTON>Open URL…</BUTTON> </TERM> <DD>This button brings up a dialog that lets you enter a URL. &p; will display the corresponding file if it resolves to an SGML document.</DD> <![ %PRO; [ <TERM>&openfile.gif; <BUTTON>Open File…</BUTTON> </TERM> <DD>This command lets you select an SGML file on the local file system for display with &p;—which thus works as a stand-alone SGML document browser in addition to its companion role to Mosaic.</DD> ]]> <TERM>&backtrck.gif; <BUTTON>Backtrack</BUTTON> </TERM> <DD>This button lets you return to a previous position, taking into consideration movements within the current file as well as other files reviewed during the session. The trail of saved positions totals 100 locations.</DD> <TERM>&forward.gif; <BUTTON>Forward</BUTTON> </TERM> <DD> The Forward command is used to cycle along a trail of positions that have been backtracked. In practice, this button undoes the effect of the backtrack button.</DD> <TERM>&tbsearch.gif; <BUTTON>Search</BUTTON> </TERM> <DD>This button brings up a dialog to enter a search string.</DD> <TERM>&srchbwd.gif; <BUTTON>Previous Hit</BUTTON> </TERM> <DD>This button scrolls the document window so that the previous undisplayed search hit is brought to the top of the window.</DD> <TERM>&srchfwd.gif; <BUTTON>Search Forward</BUTTON> </TERM> <DD>This button scrolls the document window so that the next undisplayed search hit is brought to the top of the window.</DD> <![ %PRO; [ <TERM>&annotbut.gif; <BUTTON>Annotate…</BUTTON> </TERM> <DD>The annotation button is used to create annotations or bookmarks to a document. This button is dimmed until there is both an editable web and a selection.</DD> <TERM>&beglink.gif; <BUTTON>Begin Link…</BUTTON> </TERM> <DD>The begin link button is used to create user-defined hyperlinks to a document. This button is dimmed until there is both an editable web and a selection.</DD> <TERM>&conlink.gif; <BUTTON>Connect Link…</BUTTON> </TERM> <DD>The connect link button is used to to establish a connection with a previously defined link source. This button is dimmed until there is a selection and a source anchor.</DD> ]]> <TERM>©sel.gif; <BUTTON>Copy Selection…</BUTTON> </TERM> <DD>This button lets you copy a contiguous, highlighted selection into the clipboard.</DD> <TERM>&printdoc.gif; <BUTTON>Print Document…</BUTTON> </TERM> <DD>This button lets you print the document or just selected portions of it.</DD> <TERM>&about.gif; <BUTTON>About…</BUTTON> </TERM> <DD>This button brings up a dialog box displaying the name of the application.</DD> </DEFLIST> </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Show Status bar</TITLE> Toggling the display of the status bar either reveals or hides the application echo area at the bottom of the main window. This is used to echo the application status (such as the currently open web) and general information during parsing. As an example, the right corner of the status bar displays the number of hits after a string search. </SUBSECT1> <SUBSECT1><TITLE>Launch Subviews</TITLE> The <MENU>Launch Subviews</MENU> setting changes &p;'s mode of operation when displaying elements which are hidden behind icons. When this option is checked, iconized elements are displayed in a window of their own. In the reverse setting, the elements are shown at the top of the browser screen, replacing the screen contents. You can use thus use &p; for presentations in the style of slide shows. </SUBSECT1> <SUBSECT1><TITLE>Use Default Navigator</TITLE> There are normally one or several navigators defined for each DTD. By enabling this option, &p; automatically brings up the default navigator along with the document. </SUBSECT1> <SUBSECT1><TITLE>Occurrence Density Display</TITLE> When this option is checked, a string search result will be displayed graphically as well, with a vertical shaft next to the scroll bar. See the section <XREF RID="SRFEEDB">Search Result Feedback</XREF>. </SUBSECT1> <SUBSECT1><TITLE>Autoshrink Graphics</TITLE> Whenever window contents cannot be displayed due to a narrow window size, a horizontal scroll bar appears. However, when the option <MENU>Autoshrink Graphics</MENU> is selected, graphics that are shown inline are always resized to fit the current browser window size. </SUBSECT1> <SUBSECT1><TITLE>Prevent Flicker</TITLE> The option <MENU>Prevent Flicker</MENU> toggles the method of updating the screen. When the option is enabled, the screen contents are first created in an off-screen buffer (in RAM), and then copied onto the window. This operation is perceived by users as being faster than the alternative of drawing directly onto the screen, which may create a noticeable flicker on slower systems. The latter approach however has the pro of using less application memory. </SUBSECT1> <SUBSECT1><TITLE ID="STAGS">Show Tags</TITLE> The command <MENU>Show Tags</MENU> displays the tag structure of the displayed SGML document. The tags are symbolized by markup icons surrounding the corresponding elements. <SUBSECT2><TITLE>Selection Copying with Show Tags Enabled</TITLE> <NOTE>Note that copying a selection into the clipboard when tags are displayed will incorporate the SGML markup into the copy.</NOTE> </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Show Hot Spots</TITLE> Hot Spots are clickable web anchors in graphics. When the option <MENU>Show Hot Spots</MENU> is checked, hot spots have a subtle border to indicate their location (regardless of whether the hot spot represents an annotation, link, or bookmark). When the cursor is placed over a hot spot, the cursor appearance changes from the regular arrow to a pointing finger. Toggling this setting using the keyboard shortcut <TT>Ctrl+H</TT> is an efficient way of identifying anchors in complex graphics. </SUBSECT1> <SUBSECT1><TITLE>Mosaic</TITLE> This menu setting is for selecting the HTML browser that &p; will communicate with. Currently supported browsers are NCSA Mosaic and Enhanced Mosaic from Spyglass. </SUBSECT1> </SECTION> <SECTION ID="VIEWMENU"><TITLE>The Styles Menu</TITLE> The <MENU>Styles</MENU> menu is used to select style sheets and to create or remove bindings between a DTD and a style sheet definition. As the DTD defines a class of similar documents, which all share a basic logical structure and set of tags, it makes sense to associate style sheets to the DTD. All documents based on a particular DTD can thus share style sheets; &p; lets you select also designate a specific style sheet from within the document using a <XREF RID="TR-SSHS">processing instruction</XREF> to accomodate layout needs of particular documents. The contents of this menu are dimmed when no document is being browsed. <![ %PRO; [ <SUBSECT1 ID="ATTCH"><TITLE>Attach Style Sheet</TITLE> The <MENU>Attach Style Sheet…</MENU> command lets you select a style sheet file (normally with the suffix <TT>.SSH</TT>) to be associated with the DTD of the current document. Attaching style sheets updates the <TT>ENTITYRC</TT> catalog, and the application menu will list the name of the style in its menu list of available styles. <NOTE>This menu item is dimmed when the DTD of the browsed file has been declared without reference to a corresponding public identifier. When this situation arises the style sheet selection is resolved by a <XREF RID="TR-SSHS">fallback scheme</XREF>.</NOTE> </SUBSECT1> <SUBSECT1><TITLE>Creating a New Style Sheet</TITLE> To create a new style sheet, select the command <MENU>Attach Style Sheet…</MENU> from the menu <MENU>Styles</MENU>. <LIST> <ITEM>Enter a new filename for the style sheet in the file selection dialog that appears.</ITEM> <ITEM>&p; will query you for a symbolic style sheet name. The symbolic name is displayed in the <MENU>Styles</MENU> menu.</ITEM> </LIST> When you create a new style sheet, the browser window contents will appear without any formatting except for line breaks before and after each element. You can then proceed to edit the style sheet using the built-in, interactive style sheet editor in the PRO version of &p;. <NOTE>If you want to have a head start on the style sheet design, you can copy and rename an existing style file before you attach it.</NOTE> The style sheet editor can be summoned from pop-up menus in the browser and SGML Tree Window. Because the styles support inheritance, general defaults can be set to the topmost element; only elements for whom special formatting rules need to be applied—such as titles, footnotes, tables, or graphics—remain to specify. With some experience, designing a style sheet for a structure-oriented DTD is done in a matter of minutes. </SUBSECT1> <SUBSECT1><TITLE>Detach Style Sheet</TITLE> This command removes the binding between the current style sheet and the corresponding DTD. The style sheet's symbolic name is removed from the <MENU>Styles</MENU> menu and the <TT>ENTITYRC</TT> catalog is automatically updated. The style sheet file is not deleted. </SUBSECT1> ]]> <SUBSECT1><TITLE>Available Style Sheets</TITLE> Style sheets that have been attached to the current DTD are listed at the top of the <MENU>Styles</MENU> menu; the name that appears in the menu is taken from the corresponding entry in the <TT>ENTITYRC</TT> catalog<![ %PRO; [ (and is identical to the symbolic name entered when the style sheet was created)]]>. Selecting one of the listed styles reformats the browser window according to that style sheet. </SUBSECT1> </SECTION> <SECTION ID="NAVMENU"><TITLE>The Navigator Menu</TITLE> Navigators are powerful generalized table of contents: any element can be displayed in a navigator; clicking a navigator entry scrolls the browsed document to the corresponding position. The navigator entries will automatically reflect the hierarchical structure of the elements selected for display in the navigator, such as titles at the levels of chapters, sections, and subsections. The contents of this menu are dimmed when no document is being browsed. <SUBSECT1><TITLE>Available Navigators</TITLE> In the <MENU>Navigator</MENU> menu, available navigators are listed at the top of the menu. The menu item <MENU>None</MENU>, removes the display of the navigator from the document window and expands the document to fill the size of the entire window. Removing the navigator display is also achieved by dragging the vertical divider bar far to the left, until the bar disappears. </SUBSECT1> <SUBSECT1><TITLE>Popup Menu Commands</TITLE> Clicking on the <![ %windows; [right ]]><![ %motif; [right ]]> mouse button within the full-text portion of the browser window displays a popup menu. <SUBSECT2><TITLE>Locate in Navigator</TITLE> &p; continuously updates the navigator to display what part of the document that is displayed, indicating the current location with a bright yellow arrow icon that prefixes the nearest open navigator entry. The navigator window will however not scroll its content should you scroll outside of the range currently being presented in the navigator. Selecting the <MENU>Locate in Navigator</MENU> command scrolls the navigator entry that is closest to the cursor position to the top of the navigator. This command is dimmed when no navigator is displayed. </SUBSECT2> <![ %PRO; [ <SUBSECT2><TITLE>Navigator Entry</TITLE> The <MENU>Navigator Entry</MENU> command launches the Navigator Editor, which is part of the features specific to the PRO version of &p;. This editor allows for the interactive definition of navigator elements. The element to be used for navigation is designated by the cursor position when the command is issued in the full-text browser. </SUBSECT2> ]]> </SUBSECT1> <![ %PRO; [ <SUBSECT1 ID="ATTCHNAV"><TITLE>Attach Navigator</TITLE> The <MENU>Attach Navigator…</MENU> command lets you select a navigator definition file (normally with the suffix <TT>.NAV</TT>) to be associated with the DTD of the current document. Attaching a navigator updates the <TT>ENTITYRC</TT> catalog. </SUBSECT1> <SUBSECT1 ID="CREATNAV"><TITLE>Creating a New Navigator</TITLE> To create a new navigator, select the command <MENU>Attach Navigator…</MENU> from the menu <MENU>Navigator</MENU>. <LIST> <ITEM>Enter a new filename for the navigator in the file selection dialog that appears.</ITEM> <ITEM>&p; will query you for a symbolic navigator name. The symbolic name is displayed in the <MENU>Navigator</MENU> menu.</ITEM> </LIST> When you create a new navigator, the navigator portion of the application window will initially be empty. As you proceed to interactively define the navigator entries, the navigator fills up with the selected elements. Navigator definition files use the file suffix <TT>.NAV</TT> by default. This command updates the <TT>ENTITYRC</TT> catalog. </SUBSECT1> <SUBSECT1><TITLE>Detach Navigator</TITLE> The <MENU>Detach Navigator</MENU> command is used to remove the connection between a DTD and the current navigator definition, so that the navigator no longer appears in the <MENU>Navigator</MENU> menu. The navigator definition file is not deleted. This command updates the <TT>ENTITYRC</TT> catalog. </SUBSECT1> <SUBSECT1><TITLE>Edit Navigator</TITLE> The <MENU>Edit Navigator…</MENU> command brings up the Navigator Editor, to review and edit the list of elements that have been selected as navigator entries. See the section <XREF RID="NAVEDIT">Editing Navigators</XREF>. </SUBSECT1> ]]> <SUBSECT1><TITLE>SGML Tree</TITLE> Due to the hierarchical nature of SGML markup, every element is either contained or disjunct with respect to other elements. The corresponding structure can be represented as a tree, the root element being the topmost (doctype) element. The <MENU>SGML Tree</MENU> command brings up a graphical, interactive structure view of the document instance in the navigator portion of the application window. Just like a regular navigator, you can use this window to position the document by clicking on the elements. <SUBSECT2><TITLE>SGML Tree Functionality</TITLE> Besides using the scroll bars of the SGML Tree, you can also click and drag the window contents. When the cursor is over an element: <LIST> <ITEM>Clicking the left part of the element box toggles the display of contained subelements.</ITEM> <ITEM>Clicking anywhere else within the element scrolls the browser to that location, and</ITEM> <ITEM>Highlights the corresponding element contents.</ITEM> </LIST> </SUBSECT2> </SUBSECT1> </SECTION> <SECTION ID="WEBSMENU"><TITLE>The Webs Menu</TITLE> Webs are &p;'s file containers for user-defined additions: bookmarks, annotations, or links between text or graphics. The web documents are encoded automatically by the application in SGML, and use <BO>HyTime</BO> addressing to hyperlink the web information to the corresponding documents. The webs are only available in the PRO version of &p; and should not be confused with the term <Q>web</Q> as used in e.g. the expression <Q>World Wide Web</Q>. <SUBSECT1><TITLE>Granularity of Web Objects</TITLE> Web objects are always connected to a contiguous selection, to which the user-defined information is attached. This allows for a granularity that transcends the markup for the corresponding document, to pinpoint document contents down to the word level or to a rectangular area within a graphic. Such selections are referred to as <BO>anchors.</BO> </SUBSECT1> <SUBSECT1><TITLE>Web Persistence</TITLE> Webs permit annotating documents to which you may not have write access, and thanks to the HyTime addressing capabilities, have excellent chances of coping even with documents whose contents have been edited since the user-defined additions were made. This is especially important in a distributed, multi-user environment. Webs are also an excellent means by which to share information on a set of common documents—e.g. as part of a review process. </SUBSECT1> <![ %PRO; [ <SUBSECT1><TITLE>Mounting a Web</TITLE> The <MENU>Mount Web…</MENU> command makes &p; aware of the contents of a web. Once the web has been mounted, the application will read the web data it contains and display it. The reason for separating web data (such as annotations and links) is that you may have many different kinds of webs on the same set of documents, and each web contains information tailored for different recipients. Also, more than one web can be in use simultaneously. Webs are stored and automatically reloaded between &p; sessions. <FOOTNOTE>The concept of separate webs stems from the (now sadly defunct) Intermedia hypertext system, developed at Brown University in Providence, RI. The designers behind &p; have improved on this original web notion in several important ways, such as providing HyTime adressing and concurrent web layers.</FOOTNOTE> <SUBSECT2><TITLE>Editing a Web</TITLE> When a web has been mounted, its name appears in the <MENU>Webs</MENU> menu. Even though its contents are now accessible, it is not editable. To make the web editable, select the web name from the <MENU>Webs</MENU> menu. The status of the web as being editable will be reflected in two ways: the name of the web is echoed in the status bar, and a checkmark prefix appears by the web name in the <MENU>Webs</MENU> menu. </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Deactivating a Web</TITLE> Select <MENU>Web Manager…</MENU> from the <MENU>Webs</MENU> menu to close a web so that its contents are no longer shown, . In the dialog that appears, select the web and press the <BUTTON>Dismount</BUTTON> button. The web file is not deleted. </SUBSECT1> <SUBSECT1><TITLE ID="ANNOTDLG">Annotate</TITLE> The <MENU>Annotate…</MENU> command is used to create an annotation or a bookmark. These are the steps that you need to perform to create an annotation: <LIST> <ITEM>Make sure that you have an editable web. The web name is displayed with a checkmark prefix in <MENU>Webs</MENU> menu, and its name is displayed in the status bar.</ITEM> <ITEM>Highlight a portion of text or of a graphic. The <BUTTON>Annotate…</BUTTON>, <BUTTON>Begin Link…</BUTTON>, and <BUTTON>Copy Selection</BUTTON> tool bar buttons and the corresponding menu items will become available.</ITEM> <ITEM>Click on the annotation icon in the application tool bar or select <MENU>Annotate…</MENU> from the menu <MENU>Webs</MENU>. The dialog below will appear.</ITEM> <FIGGRP> <FIG NAME="ANNOTDLG.GIF"> <TITLE>This is the annotation dialog. It is used for displaying and creating annotations, as well as for creating bookmarks.</TITLE> </FIGGRP> <ITEM>In the annotation dialog, enter your annotation in the large editable text field below <TT>Note</TT>.</ITEM> <ITEM>Optionally, assign the annotation a symbolic name. The purpose of this text field is to provide a space in which you can qualify your annotation in some manner. By default, the name consists of the first words of the selected text.</ITEM> <ITEM>Optionally, click in the <TT>Bookmark</TT> check box to register the annotation as a <XREF RID="BOOKMRKS">bookmark</XREF> as well.</ITEM> </LIST> The annotation is shown as an icon in the text, and selecting the icon highlights the corresponding selection—so that you can tell precisely what has been annotated. Anchors in graphics are indicated by a subtle border, that flashes when the anchor is selected. </SUBSECT1> <SUBSECT1><TITLE>Begin Link…</TITLE> &p; links can go between any two addressable SGML/HyTime documents. Below are the steps you need to perform to create user-defined hyperlinks. <SUBSECT2><TITLE>Creating a link from text</TITLE> To create a link that whose endpoint is text, you must: <LIST> <ITEM>Select a portion of text as a starting or source anchor.</ITEM> <ITEM>Click on the &beglink.gif; icon in the application tool bar or select <MENU>Begin Link…</MENU> from the menu <MENU>Webs</MENU>.</ITEM> <ITEM>Highlight the text you want to link to—the target of your link.</ITEM> <ITEM>Select the menu item <MENU>Connect Link…</MENU> or press the equivalent tool bar button &conlink.gif;.</ITEM> <ITEM>A dialog will now be displayed, prompting you to optionally name the source and target anchors. By default, the anchor names are the initial portion of the selected text of each anchor. Named anchors can be used e.g. to explain the reason behind the link connection. </ITEM> </LIST> Even though the link creation dialog uses the terms <Q>source</Q> and <Q>target</Q>, links are bi-directional: they are displayed with in-line icons at both endpoints. As HyTime is an application of SGML, you may want to view the web document in &p;; web documents normally use the file suffix <TT>.WEB</TT>. You will note that the HyTime used for addressing into documents will make the web contents hyperlinked to the corresponding document anchors. </SUBSECT2> <SUBSECT2><TITLE ID="HOTSPOT">Creating a link from graphics</TITLE> To create a link that whose endpoint is a graphic hot spot, you select a source anchor and a target anchor. <LIST> <ITEM>Select a portion of a graphic (or text) as a source anchor.</ITEM> <ITEM>Click on the &beglink.gif; icon in the application tool bar or select the <MENU>Begin Link…</MENU> from the menu <MENU>Webs</MENU>. When the graphic is displayed in a separate window the command <MENU>Begin Link…</MENU> is available from the <MENU>Anchor</MENU> menu in the window caption. </ITEM> <ITEM>Select the target of the link.</ITEM> <ITEM>Select the menu item <MENU>Connect Link…</MENU></ITEM> <ITEM>A dialog will now be displayed, prompting you to optionally name the source and target anchors. By default, the anchor names are called <TT>HOT SPOT</TT>. In addition, you may specify an optional zoom factor of <TT>Inherit</TT>, <TT>100</TT>, <TT>200</TT>, <TT>400</TT>, or <TT>800</TT> percent. When the zoom factor is set to inherit, the graphics will be kept at its current setting. Any other zoom factor will make &p; display the graphics in a separate window when the hot spot is accessed, and zoom the graphics according to the chosen zoom factor. </ITEM> </LIST> Links in graphics are shown with a subtle border that flashes when the hot spot is selected. Links are by default bi-directional. <FIGGRP> <FIG NAME="ANCHNAME.GIF"> <TITLE>The <TT>Anchor Names</TT> dialog is displayed when you specify the endpoint of links. The zooming factor is only available for hot spots.</TITLE> </FIGGRP> </SUBSECT2> </SUBSECT1> </SECTION> <SECTION ID="BOOKMRKS"><TITLE>The Bookmarks Menu</TITLE> Bookmarks are markers that you can leave in documents, for instant return to the selected spot. The bookmarks are stored in webs and become available from the <MENU>Bookmarks</MENU> menu as soon as the corresponding web is mounted. The menu does not appear when there are no bookmarks. <SUBSECT1><TITLE>Creating bookmarks</TITLE> Bookmarks are created from the dialog used for annotations. As bookmarks are stored in webs, there must be an editable web in which to store the bookmark. These are the steps you need to perform to create a bookmark: <LIST> <ITEM>Check that you have an open web—you can just glance at the right part of the status bar (at the bottom of the window), as it displays the currently editable web. Alternatively, select the menu <MENU>Webs</MENU> to see what web is checkmarked. Selecting a web toggles its status of being checkmarked and editable vs. being available as a read-only object. If there are no webs currently available, see the section <XREF RID="WEBOPEN">Opening and Creating Webs</XREF>. </ITEM> <ITEM>Make a selection by clicking and dragging a contiguous area in either text (or a graphic, if you want a hot spot).</ITEM> <ITEM>From the <MENU>Webs</MENU> menu, select <MENU>Annotate…</MENU> , or just click the corresponding tool bar button: &annotbut.gif;.</ITEM> <ITEM>In the annotation dialog, click on the check box marked <TT>Bookmark</TT>.</ITEM> <ITEM>Optionally, name the bookmark by editing the <TT>Name:</TT> text field above the check box. By default, the bookmark is named by the first portion of the selection (or <TT>HOT SPOT</TT>, in the case of hot spots). Naming a bookmark may be useful when you later access it from the <MENU>Webs</MENU> menu.</ITEM> </LIST> </SUBSECT1> ]]> </SECTION> </CHAPTER> <CHAPTER ID="SSHEDIT"><TITLE>Editing Style Sheets</TITLE> &sp; PRO includes a style sheet editor that lets you interactively edit style sheets by positioning the cursor over the element whose formatting is to be edited. You can launch the editor either from the formatted browser window or from the SGML Tree navigator; all changes can be previewed before the changes are made permanent. <![ %PRO; [ <SECTION ID="SS-EDIT"><TITLE>The Style Sheet Editor</TITLE> <FIGGRP> <FIG NAME="INHRCONT.GIF"> <TITLE>The style sheet editor displays the current element (possibly qualified by a tag context) in the <TT>Element</TT> pull-down list at the very top of the window. The upper right hand corner button (denoted with a <TT>P</TT> for Parent) is used for rapid traversal of ancestor elements. The <BUTTON>Preview</BUTTON> button is used to redisplay the browser contents according to current settings. Pressing <BUTTON>OK</BUTTON> commits the editing changes, while pressing <BUTTON>Cancel</BUTTON> restores the style sheet to the state it was prior to the editing session.</TITLE> </FIGGRP> The style sheet editor is used to edit the style of any element. <LIST> <ITEM>In the SGML Tree, position the cursor over an element and select <MENU>Edit Style</MENU> from the <![ %windows; [right mouse button]]><![ %mac; [Alt-click]]> popup menu. </ITEM> <ITEM>In the the document browser window, position the cursor over the text whose appearance you want to change and select <MENU>Edit Style</MENU> from the <![ %windows; [right mouse button]]><![ %mac; [Alt-click]]> popup menu.</ITEM> </LIST> The pull-down list <TT>Property</TT> selects one of the five categories (<TT>Content</TT>, <TT>Paragraph</TT>, <TT>Before</TT>,<TT>After</TT> or <TT>Misc</TT>). Current formatting properties are displayed in the main list. Select a setting in order to edit it. &p; displays a popup menu with possible values to choose from, or an editing field to enter strings or a numeric argument as needed. The <TT>Occurrence</TT> pull-down menu is used to specify formatting that is to take effect only on certain occurrences of an element, such as the first, last, or the complement of these possibilities. <NOTE>Modifying the formatting settings does not have any effect until either the <BUTTON>Preview</BUTTON> or <BUTTON>OK</BUTTON> button is pressed. The former will re-format the browser window contents, while the latter will re-format the browser window contents and commit the editing changes to the style sheet. Pressing <BUTTON>Cancel</BUTTON> restores the original settings and ends the editing session, while pressing <BUTTON>Clear</BUTTON> resets the settings without exiting the editor.</NOTE> <SUBSECT1><TITLE>Style Sheet Editing</TITLE> <FIGGRP> <FIG NAME="CONTENT.GIF"> <TITLE>The <TT>Property</TT> pull-down menu is used to address various formatting aspects: how to display element contents, what should happen when opening or closing an element, how space should be created around it, etc.</TITLE> </FIGGRP> In the style sheet editor, there are five categories of formatting properties that can be set: <LIST> <ITEM>Content: mainly text properties (such as font family, font size, font slant, etc).</ITEM> <ITEM>Paragraph: spacing around the element (such as line breaking and margins).</ITEM> <ITEM>Before: actions to do, or text to add, when opening the element.</ITEM> <ITEM>After: action to do, or text to add, when closing the element.</ITEM> <ITEM>Miscellaneous: Esoteric formatting properties, such as table handling, math, iconizing elements, and auto numbering.</ITEM> </LIST> <SUBSECT2><TITLE>Inheritance and containment</TITLE> Generally speaking, most formatting aspects can be inherited from parent elements: Selecting a suitable general style for the topmost (root) element and fine-tuning the style sheet for headings, footnotes, and similar elements is the recommended approach. Inheritance reduces the effort of creating a new style sheet to a minimum as the inheritance chain goes all the way up to the top element. </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Content</TITLE> In the content dialog, one defines formatting for the display of the <BO>element contents</BO>. Normally, suitable defaults are set for the top element, with adjustements for the presentation of elements such as footnotes, headings, tables, and the like. <DEFLIST> <TERM> <TT>Font Family</TT> </TERM> <DD> Clicking this property displays a list of all available fonts on the system.</DD> <TERM> <TT>Font Size</TT> </TERM> <DD> Sets the font size in pixels.</DD> <TERM> <TT>Font Slant</TT> </TERM> <DD> The slant can be set to <TT>roman</TT>, <TT>italic</TT>, or <TT>emphasis</TT>. Emphasized text will toggle the current setting: if the text is displayed in roman style, it is italicized, and vice-versa. This last setting is handy when you have embedded elements that inherit the slant setting.</DD> <TERM> <TT>Font Weight</TT> </TERM> <DD> The weight can be <TT>Medium</TT> or <TT>Bold</TT>.</DD> <TERM> <TT>Font Color</TT> </TERM> <DD> This sets the foreground text color. The color can be specified as an RGB value in hexadecimal notation up to 24 bits wide (<TT>#FFFFFF</TT>). In addition, the predefined &platform; colors are: <![ %windows; [ <LIST> <ITEM>aqua</ITEM> <ITEM>black</ITEM> <ITEM>blue</ITEM> <ITEM>fuschia</ITEM> <ITEM>gray</ITEM> <ITEM>green</ITEM> <ITEM>lime</ITEM> <ITEM>maroon</ITEM> <ITEM>navy</ITEM> <ITEM>olive</ITEM> <ITEM>purple</ITEM> <ITEM>red</ITEM> <ITEM>silver</ITEM> <ITEM>teal</ITEM> <ITEM>white</ITEM> <ITEM>yellow</ITEM> </LIST> </DD> ]]> <![ %mac; [ <LIT> ************************************ * COPY NEEDS TO BE ADDED FOR MAC * ************************************ </LIT> </DD>]]> <![ %motif; [ <LIT> ************************************** * COPY NEEDS TO BE ADDED FOR MOTIF * ************************************** </LIT> </DD>]]> <TERM> <TT>Font Scale</TT> </TERM> <DD> The scale of the font is entered as a percentage; a figure greater than 100 produces a magnification, less than 100 shrinks the scale. This setting is useful for uniform size transformation, say for a demo, or to create a style sheet specifically for certain printing requirements. Note that the setting will affect elements whose font sizes are expressed absolutely (in pixels) as well as elements whose size is expressed relative the current setting using <TT>Font Scale</TT>.</DD> <TERM><TT>Position</TT> </TERM> <DD>The contents of the element are normally displayed on the current baseline. If needed, they can be offset +/-70% (expressed in the current font) from the baseline. The offset is set in increments of 10% as picked from the pop-up list.</DD> <TERM><TT>Visibility</TT> </TERM> <DD>You can either hide or show the element and its subelements. The usefulness of this setting is somewhat dependent on the DTD being used. Some document types contain a lot of information of an administrative nature not meant to be read by an end-user.</DD> </DEFLIST> </SUBSECT1> <SUBSECT1> <TITLE>Paragraph</TITLE> <FIGGRP> <FIG NAME="PARAPROP.GIF"> <TITLE>The <TT>Paragraph</TT> setting affects mainly spacing and justification of the element.</TITLE> </FIGGRP> The paragraph properties affect primarily spacing and justification. <DEFLIST> <TERM> <TT>Justify</TT> </TERM> <DD> The justification of the element contents can be set to <TT>left</TT>, <TT>center</TT> , and <TT>right</TT>.</DD> <TERM><TT>Leading</TT> </TERM> <DD> &p; handles the baseline spacing automatically. The leading is expressed as the number of pixels to add to the baseline offset, in addition to whatever is currently required with current font size settings.</DD> <TERM> <TT>Break</TT> </TERM> <DD> This property specifies whether the element should cause a line break before and/or after the display of its contents. It has four settings: <DEFLIST> <TERM> <TT>Block</TT> </TERM> <DD> Creates a line break before and after the element.</DD> <TERM> <TT>Before</TT> </TERM> <DD> Creates a line break before the element.</DD> <TERM> <TT>After</TT> </TERM> <DD> Creates a line break after the element.</DD> <TERM> <TT>Inline</TT> </TERM> <DD> No line breaks, thus the element is displayed in the normal flow of text.</DD></DEFLIST></DD> <TERM> <TT>Space Above</TT> </TERM> <DD> Additional spacing above the element, e.g. to create space between headings or paragraphs.</DD> <TERM> <TT>Space Left</TT> </TERM> <DD> Space to the left margin. The value can be absolute (from the margin) or relative the parent element; the latter is useful when creating indented lists within lists.</DD> <TERM> <TT>Space Indent</TT> </TERM> <DD> This setting handles the indentation of the first line of the element.</DD> <TERM> <TT>Space Below</TT> </TERM> <DD> Additional spacing below the element, e.g. to create space between headings or paragraphs.</DD> </DEFLIST> <NOTE>A hint: Setting spacing on all sides of the topmost element will create nice margins in the browser window.</NOTE> </SUBSECT1> <SUBSECT1><TITLE>Text Before/After property functions</TITLE> &p; has the following sets of property functions to insert text in the style sheet property <TT>Text Before</TT> and <TT>Text After</TT>.<FOOTNOTE>The SGML application SoftQuad Explorer (also developed by Synex Information AB) currently has a somewhat different notation—both formats will be supported in both applications.</FOOTNOTE> <SUBSECT2><TITLE>Generated text</TITLE> Many DTDs use attributes in which to store document information. &p; lets you extract the contents of attributes and environment variables, combining the ultimate presentation with contextual requirements. In addition to accessing these values and inserting them before or after elements, you can insert text strings, tab characters, and line breaks. </SUBSECT2> <SUBSECT2><TITLE>Before and After</TITLE> The <TT>Before</TT> and <TT>After</TT> settings affect formatting that is to take place when opening and closing elements, respectively. Everything that can be inserted before can be inserted after an element as well, so the description below applies to both of these settings. <DEFLIST> <TERM> <EMPH TYPE="5">Text</EMPH> </TERM> <DD>A string of text to insert before/after the content of the element, as a prefix/suffix, respectively. More advanced text insertion can also be done by extracting attribute values and environment variables by specifying a string with a special syntax, described in the table below. <DEFLIST REND="TABLE"> <TERM><TT>\n</TT></TERM> <DD>the line break character</DD> <TERM><TT>\tab</TT></TERM> <DD>the tab character</DD> <TERM><TT>\[0-9]+</TT></TERM> <DD>the character with the corresponding ordinal value</DD> <TERM><TT>\att(attribute)</TT></TERM> <DD>the textual value of the attribute</DD> <TERM><TT>\env(envvar)</TT></TERM> <DD>the textual value of the environment variable <TT>envvar</TT></DD> </DEFLIST> The variables <TT>\n</TT> or <TT>\tab</TT> should be separated from the text that follows by any other character than a lower-case letter of the english alphabet, such as a blank. In the rare case that this would be a problem, you can insert a semi-colon after the variable. The semi-colon will be suppressed in the output. <LIST> <ITEM><TT>first line\n;and the second line follows</TT></ITEM> <ITEM><TT>\tab;</TT></ITEM> </LIST> The inserted text can also be subject to conditional processing through the following functions: <SQTABLE> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=1 rowspan=1><TT>\ifatt(attribute)</TT></SQCELL> <SQCELL colstart=2 colspan=1 rowstart=1 rowspan=1>Check if attribute is assigned a value.</SQCELL> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=2 rowspan=1><TT>\ifatt(attribute=val)</TT></SQCELL> <SQCELL colstart=2 colspan=1 rowstart=2 rowspan=1>Check if attribute is equal the value <TT>val</TT>.</SQCELL> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=3 rowspan=1><TT>\ifenv(envar)</TT></SQCELL> <SQCELL colstart=2 colspan=1 rowstart=3 rowspan=1>Check if the environment variable <TT>envar</TT> is set.</SQCELL> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=4 rowspan=1><TT>\ifenv(envar=val)</TT></SQCELL> <SQCELL colstart=2 colspan=1 rowstart=4 rowspan=1>Check if the environment variable <TT>val</TT> equals the value <TT>val</TT>.</SQCELL> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=5 rowspan=1><TT>\else</TT></SQCELL> <SQCELL colstart=2 colspan=1 rowstart=5 rowspan=1>The else branch in a conditional processing statement. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=6 rowspan=1><TT>\endif</TT></SQCELL> <SQCELL colstart=2 colspan=1 rowstart=6 rowspan=1>Closes a conditional processing statement</SQCELL> </SQROW> </SQTABLE> A few examples of the kinds of possible statements are: <LIT> \ifatt(label)\att(label)\endif \ifatt(label)\att(label)\else Figure\endif \ifatt(sec=ts)TOP SECRET\else ifatt(sec=s) SECRET\else Open\endif\endif </LIT> <NOTE>The style sheet editor will dim the <MENU>Edit Style</MENU> entry when the cursor is positioned over text that has been inserted before or after an element.</NOTE> <DEFLIST> <TERM> <EMPH TYPE="5">Font Family</EMPH> </TERM> <DD> The name of the font in which the inserted text is to be shown.</DD> <TERM> <EMPH TYPE="5">Font Size</EMPH> </TERM> <DD> Size of the inserted text, in pixels.</DD> <TERM> <EMPH TYPE="5">Font Slant</EMPH> </TERM> <DD> The slant of the inserted text can be set to <TT>roman</TT>, <TT>italic</TT>, or <TT>emphasis</TT>.</DD> <TERM> <TT>Font Weight</TT> </TERM> <DD> The weight of the inserted text can be <TT>Medium</TT> or <TT>Bold</TT>.</DD> <TERM> <TT>Font Color</TT> </TERM> <DD> This sets the foreground color of the inserted text. The color can be specified as an RGB value in hexadecimal notation up to 24 bits wide (<TT>#FFFFFF</TT>). In addition, the predefined &platform; colors are: <![ %windows; [ <LIST> <ITEM>aqua</ITEM> <ITEM>black</ITEM> <ITEM>blue</ITEM> <ITEM>fuschia</ITEM> <ITEM>gray</ITEM> <ITEM>green</ITEM> <ITEM>lime</ITEM> <ITEM>maroon</ITEM> <ITEM>navy</ITEM> <ITEM>olive</ITEM> <ITEM>purple</ITEM> <ITEM>red</ITEM> <ITEM>silver</ITEM> <ITEM>teal</ITEM> <ITEM>white</ITEM> <ITEM>yellow</ITEM> </LIST> </DD>]]> <![ %mac; [ <LIT> ************************************ * COPY NEEDS TO BE ADDED FOR MAC * ************************************ </LIT> </DD>]]> <![ %motif; [ <LIT> ************************************** * COPY NEEDS TO BE ADDED FOR MOTIF * ************************************** </LIT> </DD>]]> <TERM> <TT>Position</TT> </TERM> <DD> The inserted string is normally displayed on the current baseline. If needed, it can be offset +/-70% (expressed in the current font) from the baseline. The offset is set in increments of 10%.</DD> <TERM><TT>Rule</TT></TERM> <DD> This setting is used to create a horizontal rule at the location offset specified by applying the values of <TT>Space Above</TT> and <TT>Space Below</TT> (respectively). The number specified in the rule setting is additional spacing from the rule, expressed in pixels. The position of the rule is thus padded by settings from each sides.</DD></DEFLIST> </DD> </DEFLIST> </SUBSECT2> </SUBSECT1> <SUBSECT1 ID="MISCSSH"><TITLE>Miscellaneous</TITLE> The <TT>Misc</TT> setting is used for formatting that does not fit in any of the categories above. <DEFLIST> <TERM ID="ICON"><TT>Icon</TT> </TERM> <DD>Selecting an icon will display the element with an inline icon. Clicking the icon displays the element contents in a separate window. (See also the <XREF RID="BKGDCOLR"><TT>Background Color</TT></XREF> setting below). This revelatory style sheet behavior is suitable for elements such as footnotes, tables, or similar elements. </DD> <TERM ID="AUTONUMB"><TT>Autonumber</TT> </TERM><DD>This property specifies whether the element should be numbered automatically, and in what style. It has four settings: <DEFLIST> <TERM> <TT>Linear</TT> </TERM> <DD> Numbers the element in order (linearly) throughout the document.</DD> <TERM> <TT>Hierarchical Begin</TT> </TERM> <DD> Resets the counter of this element when the element is opened.</DD> <TERM> <TT>Hierarchical Block</TT> </TERM> <DD> Assigns a counter at this hierarchical level.</DD> <TERM> <TT>Hierarchical Item</TT> </TERM> <DD> Numbers the element within a block. Hierarchical items are thus enclosed by elements that are assigned a style sheet setting of hierarchical blocks.</DD> </DEFLIST> A hint: To better understand how autonumbering is accomplished in e.g. this manual, do as follows: <LIST> <ITEM>Place the cursor over an autonumbered heading nested deep in the document, to have several layers.</ITEM> <ITEM>Select <TT>Locate in SGML Tree</TT> from the <![ %windows; [right mouse button]]><![ %mac; [Alt-click]]> popup menu.</ITEM> <ITEM>From the same menu, select <TT>Edit Style</TT> when the cursor is over an autonumbered heading</ITEM> <ITEM>In the style sheet editor, pick the <TT>Misc</TT> property and look at the <TT>Autonumber</TT> setting.</ITEM> <ITEM>Press the parent button (<BUTTON>P</BUTTON>) to visit parent elements in turn, and note how the style sheet setting toggles between <TT>Hierarchical Item</TT> and <TT>Hierarchical Block</TT> as you traverse the SGML Tree.</ITEM> </LIST> </DD> <TERM> <TT>Number Type</TT> </TERM> <DD> This setting specifies the style of autonumbering: arabic, roman, or alphabetic, where the two last options can be in upper or lower case. <NOTE>This setting has no effect unless <TT>Autonumber</TT> has one of the values <TT>Linear</TT>, <TT>Hierarchical Begin</TT>, or <TT>Hierarchical Block</TT>. </NOTE></DD> <TERM ID="BKGDCOLR"> <TT>Background Color</TT> </TERM> <DD>This setting affects the background color for elements displayed in a window of their own, i.e. elements whose contents has been hidden behind an <XREF RID="ICON">icon</XREF>. Other elements will inherit the value of the background color, regardless of their background color setting. The predefined &platform; colors are: <![ %windows; [ <LIST> <ITEM>aqua</ITEM> <ITEM>black</ITEM> <ITEM>blue</ITEM> <ITEM>fuschia</ITEM> <ITEM>gray</ITEM> <ITEM>green</ITEM> <ITEM>lime</ITEM> <ITEM>maroon</ITEM> <ITEM>navy</ITEM> <ITEM>olive</ITEM> <ITEM>purple</ITEM> <ITEM>red</ITEM> <ITEM>silver</ITEM> <ITEM>teal</ITEM> <ITEM>white</ITEM> <ITEM>yellow</ITEM> </LIST> The color can be specified as an RGB value in hexadecimal notation up to 24 bits wide (<TT>#FFFFFF</TT>). </DD>]]> <![ %mac; [ <LIT> ************************************ * COPY NEEDS TO BE ADDED FOR MAC * ************************************ </LIT> </DD>]]> <![ %motif; [ <LIT> ************************************** * COPY NEEDS TO BE ADDED FOR MOTIF * ************************************** </LIT> </DD>]]> <TERM><TT>Table Item</TT></TERM> <DD>&p; has a canonical formatting interface for handling row-oriented tables and tables whose cells follow SoftQuad's table model. Row-oriented tables are formatted by combining twelve settings:</DD> <TERM> <TT>Table</TT> </TERM> <DD> The element represents a table, and the cell are to be separated by a grid.</DD> <TERM> <TT>Table (No Grid)</TT></TERM> <DD> The element represents a table, but no grid is drawn. This formatting feature is useful for creating a tabular display that may not be marked up as a table.</DD> <TERM> <TT>Row</TT> </TERM> <DD> The element starts a row in the table.</DD> <TERM> <TT>Cell(*)</TT> </TERM> <DD> The element is a cell that can span several columns.</DD> <TERM> <TT>Cell(1)-Cell(7)</TT> </TERM> <DD> The element is a cell that spans from 1 to 7 columns, depending on the value within parenthesis. </DD> <TERM> <TT>SQ-Cell</TT> </TERM> <DD> As an alternative to the row-oriented approach, you may use attributes that define the cell placement. An SQ-Cell has four attributes (<TT>COLSTART</TT>, <TT>COLSPAN</TT>, <TT>ROWSTART</TT> and <TT>ROWSPAN</TT>) that declare the starting column, the number of spanned columns, the starting row, and the number of spanned rows (respectively).</DD> <TERM> <TT>Math Item</TT></TERM> <DD>A canonical formatting interface for mathematics. Formulae can be formatted by combining these settings: <LIST> <ITEM>Fraction</ITEM> <ITEM>Radical</ITEM> <ITEM>Radix</ITEM> <ITEM>Superior</ITEM> <ITEM>Inferior</ITEM> <ITEM>Above</ITEM> <ITEM>Below</ITEM> </LIST> </DD> <TERM><TT>Link Source</TT></TERM> <DD>By default, &p; will automatically generate a hyperlink for markup-based cross-references. If you do not want the link source to be displayed as a link (as underlined text), set this setting to <TT>Hide</TT>.</DD> <TERM><TT>Link Destination</TT></TERM> <DD>By default, &p; will automatically generate a hyperlink for markup-based cross-references. If you do not want the link target to be displayed as a link (as underlined text), set this setting to <TT>Suppress</TT>.</DD> <TERM><TT>Line</TT></TERM> <DD>This setting has three possible values: <TT>Below</TT>, <TT>Over</TT>, and <TT>Trough</TT>. The effect of these settings is <UL>underlined text</UL>, <OL>overlined text</OL> (useful if you are writing logic expressions or are working in the semi-conductor industry), and striked-through text, e.g. to show that text that has been <SO>deleted</SO> in a revision. Underlined text should be used very restrictively—if at all—as it has become somewhat of a convention to denote hyperlinks in many applications, including &p;.</DD> <FIGGRP> <FIG NAME="LINE.GIF"> <TITLE>Examples of setting the <TT>Line</TT> property to <TT>Below</TT>, <TT>Over</TT>, and <TT>Through</TT>.</TITLE> </FIGGRP> <TERM><TT>Change Bar</TT></TERM> <DD>If this setting is set to <TT>Yes</TT>, the left margin will have a vertical rule as a revision marker for the extent of the element contents.</DD> <TERM><TT>Printer Page Feed</TT></TERM> <DD>If this setting is set to <TT>Yes</TT>, a new page is generated before printing the contents of the element. This setting can be used beneficially for major divisions of a document, such as chapter elements.</DD> <TERM><TT>Printer Headers</TT></TERM> <DD>This setting is used to create running headers or footers, where the contents are taken from the most recent occurrence of the element. The contents can be placed flush left, flush right, or centered. A common use of this feature would be to place e.g. chapter titles as running heads.</DD> </DEFLIST> </SUBSECT1> <SUBSECT1 ID="VERBATIM"><TITLE>Verbatim formatting</TITLE> Some elements need to be formatted the same way as they appear in the SGML source file (verbatim), including so-called white space such as tabs and line breaks. This is however not a style sheet option because the decision to keep white space must be made prior to the parsing of the document contents: an on-line viewer such as &p; (which formats the contents to fit the window size) has no concept of a page! There are two ways of specifying verbatim processing. You can specify: <LIT> VERBATIM "gi1 gi2 gi3..." </LIT> in the <TT>ENTITYRC</TT> file at the corresponding DTD entry, where the <TT>gi</TT> is the identifier for the element whose contents are to displayed verbatim. Alternatively, you can specify a processing instruction of the form: <LIT> <?VERBATIM "gi1 gi2 gi3..."> </LIT> prior to the document instance. </SUBSECT1> <SUBSECT1> <TITLE>Qualifying Elements</TITLE> Qualifying an element allows &p; to treat the same element differently depending on its <LIST TYPE="4"> <ITEM> SGML ancestry (such as ancestor or sibling elements)</ITEM> <ITEM> Relative position (such as first or last)</ITEM> <ITEM> SGML attributes</ITEM></LIST> The changes in style will only apply to the elements matching the specified conditions. <SUBSECT2> <TITLE>Qualified Formatting</TITLE> In &p;, you can specify contextual formatting qualified on ancestor (parent, grandparent, etc.) and sibling elements. Contextual conditions can be specified for element names (GIs), attributes, and environment variables. There is a small qualifier language for this task. The qualifier language has the following primitives: <TT>and</TT>, <TT>or</TT>, <TT>not</TT>, <TT>par</TT>, <TT>prev</TT>, <TT>next</TT> and <TT>child</TT>. A qualifier can contain subqualifiers (connected by <TT>and</TT> or <TT>or</TT>), grouped by parentheses. Attribute values are retrieved by surrounding the attribute name with square brackets (<TT>[]</TT>). It is possible to quote strings with either double or single quote pairs. The token for comparing primitives is the equal sign. The qualifying language operates on strings, i.e. everything is computed into strings: <DEFLIST> <TERM> <TT>"par"</TT> </TERM> <DD> returns the GI of the current element's parent.</DD> <TERM> <TT>"prev"</TT> </TERM> <DD> returns the GI of the current element's previous sibling.</DD> <TERM> <TT>"next" </TT> </TERM> <DD> returns the GI of the current element's next sibling.</DD> <TERM> <TT>"child"</TT> </TERM> <DD> returns the GI of the current element's first child.</DD> <TERM> <TT>"[att]"</TT> </TERM> <DD> returns the value of the attribute "att".</DD> </DEFLIST> These operators can be combined by a forward slash, e.g.: <DEFLIST> <TERM> <TT>"par/next"</TT> </TERM> <DD> returns the GI of the next sibling of the parent.</DD> <TERM> <TT>"par[att]"</TT> </TERM> <DD> returns the value of the attribute "att" of the parent.</DD> </DEFLIST> <TT>FALSE</TT> is returned if an expression cannot be computed (say, if the current element doesn't have a parent and the context is specified using <TT>par</TT>). Strings are compared using the equality operator (<TT>=</TT>), and the resulting boolean values are combined using the operators <TT>and</TT>, <TT>or</TT> or <TT>not</TT>. A string comparison is a boolean expression. In addition, a string expression evaluates to <TT>TRUE</TT> if it is specified, and to <TT>FALSE</TT> otherwise. <SUBSECT3><TITLE>Some Examples</TITLE> <TABLE> <TBODY> <ROW> <CELL><TT>[type] = "ordered"</TT></CELL> <CELL>This expression is <TT>TRUE</TT> if the current element has an attribute <Q>type</Q> with the value <Q>ordered</Q>.</CELL> </ROW> <ROW> <CELL><TT>par = "CHP"</TT></CELL> <CELL>This expression is <TT>TRUE</TT> if the current element has a parent named <Q>CHP</Q>. <FOOTNOTE>(If the current element were <Q>CT</Q>, this expression would essentially be equal to qualifying the style for <TT>CT</TT> as <TT>CHP,CT</TT>.</FOOTNOTE></CELL> </ROW> <ROW> <CELL><TT>not (par = "CHP")</TT></CELL> <CELL>This expression is <TT>TRUE</TT> when the parent is not a <Q>CHP</Q> element or when the current element is the topmost element (as the topmost element has no parent). </CELL> </ROW> <ROW> <CELL><TT>next = "P" and prev = "Q"</TT></CELL> <CELL>This expression is <TT>TRUE</TT> if the current element's previous sibling is a <TT>P</TT> element and the next sibling is a <TT>Q</TT> element. </CELL> </ROW> <ROW> <CELL><TT>par = child</TT></CELL> <CELL>This expression tests whether the parent and the first child has the same GI. It would also yield <TT>TRUE</TT> in the unusual case of a document consisting of a single element: if there is no parent and there is no child, the expression is evaluated as the comparison <TT>FALSE = FALSE</TT>, which is <TT>TRUE</TT>. </CELL> </ROW> <ROW> <CELL><TT>par[tag] = prev</TT> </CELL> <CELL>This expression evaluates to <TT>TRUE</TT> when the value of the attribute <Q>tag</Q> of the parent is equal to the GI of the previous sibling. There are in addition some unusual conditions where this expression yields <TT>TRUE</TT>, such as <LIST> <ITEM>there is no parent, or</ITEM> <ITEM>the parent doesn't have an attribute named <Q>tag</Q>, or</ITEM> <ITEM>the attribute <TT>tag</TT> is unspecified</ITEM> </LIST> <BO>and</BO> there is no previous sibling. </CELL> </ROW> <ROW> <CELL><TT>child</TT></CELL> <CELL> This expression is <TT>TRUE</TT> if the current element has (at least) one child element. </CELL> </ROW> </TBODY> </TABLE> </SUBSECT3> <SUBSECT3><TITLE>Correspondence between &p; and Explorer formatting</TITLE> &p; reads the SoftQuad Explorer (also developed and maintained by Synex Information AB) attribute qualifications and transforms them into &p; qualifications on-the-fly. For your information, here's how Explorer attribute qualifing styles are translated: <LIST> <ITEM><TT>"att=Implied"</TT> is translated as <TT>"not [att]"</TT></ITEM> <ITEM><TT>"att=Not Implied"</TT> is translated as <TT>"[att]"</TT></ITEM> <ITEM><TT>"att=val"</TT> is translated as <TT>"[att]=val"</TT></ITEM> </LIST> </SUBSECT3> </SUBSECT2> <SUBSECT2><TITLE>Copying styles between elements</TITLE> The <TT>Update</TT> and <TT>Copy</TT> buttons are used to copy style sheet settings from one element to another, as a convenience in style sheet editing. <LIST TYPE="1"> <ITEM>Select the element whose style you want to modify, using the <MENU>Edit Style</MENU> command from the browser (or the SGML Tree) popup menu.</ITEM> <ITEM>Click on the <BUTTON>>></BUTTON> beside the <TT>Property</TT> field to unfold the style sheet editor window to its full extent.</ITEM> <ITEM>Select the element whose style you want to copy from the <TT>Defined Elements</TT> list. Pressing the <BUTTON>Copy</BUTTON> will copy the style settings to the current element. Picking an element from the <TT>Defined Elements</TT> list and pressing the <BUTTON>Update</BUTTON> makes the selected element the current element. This is useful when you want to directly edit the settings of a previously defined element.</ITEM> </LIST> </SUBSECT2> </SUBSECT1> </SECTION> <SECTION ID="TIPS"><TITLE>Style Sheet Design Tips</TITLE> Here are a few style sheet design tips to help you get started. <LIST TYPE="2"> <ITEM>Assign a suitable document font and margin settings (using <TT>Space Left</TT>, <TT>Space Above</TT>, <TT>Space Below</TT> and <TT>Space Right</TT>, respectively) to the top element. The top element is easily reached by clicking the button marked <TT>P</TT> in the style sheet dialog.</ITEM> <ITEM>Apply the <TT>Preview</TT> preview button before committing your editing changes.</ITEM> <ITEM>Use element qualification to assign formatting contexts.</ITEM> <ITEM>Open up the SGML Tree to visualize the structure of the document instance, and work your way from top to bottom in the element hierarchy.</ITEM> <ITEM>When creating spacing around an element, strive for consistency. Also, think of the adjacency of elements: The <TT>Space Below</TT> of one element may be too much if the next one also specifies <TT>Space Above</TT>. Spacing is perhaps best used in conjunction with the style sheet <TT>Occurrence</TT> qualifier.</ITEM> <ITEM>Apply inheritance whenever possible, including setting of values relative parent elements. An example: let lists inherit their font, but set the <TT>Space Left</TT> value relative the parent—this is useful for nested lists.</ITEM> <ITEM>For portability, choose standard &platform; fonts whenever possible, keeping your choice of fonts to a strict minimum that mix well.</ITEM> <ITEM>Navigators usually look better when their contents is shrunk somewhat, with reasonable <XREF RID="EDITFUNC">minimum and maximum</XREF> settings.</ITEM> </LIST> </SECTION> ]]> </CHAPTER> <CHAPTER ID="NAVEDIT"><TITLE>Editing Navigators</TITLE> Navigators are based on extraction criteria that describe what elements to display in the navigator window. The PRO version of &sp; includes a navigator editor for easy, interactive editing of navigators. Navigator entries can be displayed according to contextual criteria on immediate ancestors, and their contents formatted according to separate style specifications. Navigator definition files normally use the suffix <TT>.NAV</TT>. Their contents is straightforward SGML, consisting of a doctype element called <TT>TOC-DEF</TT>, which contains <TT>TOC</TT> elements. All relevant information is contained in attributes: <SQTABLE> <SQROW> <SQHEAD colstart=1 colspan=1 rowstart=1 rowspan=1> Element </SQHEAD> <SQHEAD colstart=2 colspan=1 rowstart=1 rowspan=1> Attribute </SQHEAD> <SQHEAD colstart=3 colspan=1 rowstart=1 rowspan=1> Purpose </SQHEAD> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=2 rowspan=6> <TT>TOC-DEF</TT> </SQCELL> <SQCELL colstart=2 colspan=1 rowstart=2 rowspan=1> <TT>DTD</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=2 rowspan=1> Contains the public identifier of the DTD to which the navigator applies. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=2 colspan=1 rowstart=3 rowspan=1> <TT>NAME</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=3 rowspan=1> Contains the symbolic name of the navigator, to be displayed in the <MENU>Navigator</MENU> menu. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=2 colspan=1 rowstart=4 rowspan=1> <TT>SCALE</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=4 rowspan=1> Defines the scaling of the font size (as a percentage) for textual navigator entries. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=2 colspan=1 rowstart=5 rowspan=1> <TT>MIN</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=5 rowspan=1> Defines the minimum permitted font size (in pixels) for textual navigator entries. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=2 colspan=1 rowstart=6 rowspan=1> <TT>MAX</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=6 rowspan=1> Defines the maximum permitted font size (in pixels) for textual navigator entries. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=1 colspan=1 rowstart=7 rowspan=2> <TT>TOC</TT> </SQCELL> <SQCELL colstart=2 colspan=1 rowstart=7 rowspan=1> <TT>BODY</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=7 rowspan=1> The element body for which the navigator entry applies. </SQCELL> </SQROW> <SQROW> <SQCELL colstart=2 colspan=1 rowstart=8 rowspan=1> <TT>TITLE</TT> </SQCELL> <SQCELL colstart=3 colspan=1 rowstart=8 rowspan=1> The element containing the title for the navigation block. </SQCELL> </SQROW> </SQTABLE> <![ %PRO; [ <SECTION ID="LAUNCHNA"><TITLE>Launching the Navigator Editor</TITLE> The Navigator Editor is launched by positioning the cursor over the element to include in the navigator and selecting <MENU>Navigator Entry…</MENU> from the browser popup menu displayed when the <![ %windows; [right ]]><![ %motif; [right ]]>mouse button is depressed. You can also launch the editor by selecting <MENU>Edit Navigator…</MENU> from the <MENU>Navigator</MENU> menu. <SUBSECT1 ID="EDITFUNC"><TITLE>Editor Functionality</TITLE> The Navigator Editor presents the element to include in a pull-down menu that displays the element in its current context, to specify a contextual requirement for its inclusion in the navigator. The navigator normally uses the same style sheet as that being used by the browser. As the kind of items often used for navigation are titles at various levels, inserting the elements <Q>as is</Q> would be aesthetically unpleasing due to the large font sizes normally used for titles. For this reason, you can specify a general scaling (as a percentage), as well as minimum and maximum font sizes (in pixels) for the navigator entry font. The <BUTTON>P</BUTTON> button is used to traverse the direct ancestors of the element when you have selected <MENU>Navigator Entry…</MENU> while in the browser window. When the Navigator Editor has been launched from the <MENU>Navigator</MENU> menu, the <BUTTON>P</BUTTON> button is dimmed as there is no well-defined location from where one could traverse the SGML Tree. <SUBSECT2><TITLE>Creating Navigators</TITLE> See the section <XREF RID="CREATNAV">Creating a New Navigator</XREF> on how to create navigators. </SUBSECT2> <SUBSECT2><TITLE>Editing Navigators</TITLE> <SUBSECT3><TITLE>Adding a Navigator Entry</TITLE> To have an element (such as a title or a graphic) displayed in a navigator, position the cursor over the element, and pick <MENU>Navigator Entry</MENU> from the browser popup menu. This will launch the Navigator Editor, with the element in the <TT>Navigator Entry</TT> pull-down menu. The pull-down menu contains the element in context, and you would normally pick the first level of containment, so that your navigators will automatically support the folding behavior derived from the markup hierarchy. Once you have picked the element in context, click on the <BUTTON>Add</BUTTON>. The element will then be placed in the list of <TT>Defined Entries</TT>. Clicking the <BUTTON>OK</BUTTON> button to confirm your editing changes. </SUBSECT3> <SUBSECT3><TITLE>Deleting a Navigator Entry</TITLE> To delete a navigator entry, launch first the Navigator Editor. Select the navigator definition to delete from the list of <TT>Defined Entries</TT> and click the <BUTTON>Remove</BUTTON> button. Finally, click the <BUTTON>OK</BUTTON> button to confirm your editing changes and exit the Navigator Editor. </SUBSECT3> </SUBSECT2> <SUBSECT2><TITLE>The Locate Setting</TITLE> At the bottom of the Editor dialog is a <TT>Locate</TT> checkbox, whose value can be either <TT>Body</TT> or <TT>Title</TT>. This is usually set to the value <TT>Title</TT>: when the navigator entry is clicked upon, the browser scrolls to the location of the item being displayed in the browser. In some circumstances, you may prefer to have the browser scrolled to the <TT>Body</TT> of the element instead. An example will make this clear. Assume that you want to include figure captions in your navigator, and that captions are beneath the figures. With the <TT>Locate</TT> setting set to <TT>Title</TT>, the caption will be topmost when you click upon the corresponding navigator entry, with the figure scrolled out of sight. To keep the figure in sight, you will need a containing element for both the caption and the figure. You would then set the caption element to be contextually qualified by the containing element and set <TT>Locate</TT> to <TT>Body</TT>. </SUBSECT2> </SUBSECT1> <SUBSECT1><TITLE>Specifying an Alternative Style Sheet</TITLE> The navigator normally uses the same style sheet as that being used by the browser. To base a navigator on a specified style sheet (instead of using the style sheet of the fulltext view), you need to add an entity pointing at the style sheet and name this entity <TT>StyleSpec</TT> (case is significant) in the navigator definition. The navigator definition begins with a doctype declaration such as: <LIT> <!DOCTYPE TOC-DEF PUBLIC "-//Synex Information AB//DTD Navigator Explorer//EN"> </LIT> Assuming your style sheet definition file is <TT>style.ssh</TT>, simply add the style sheet entity to the local declaration subset: <LIT> <!DOCTYPE TOC-DEF PUBLIC "-//Synex Information AB//DTD Navigator Explorer//EN" [ <!ENTITY StyleSpec SYSTEM "style.ssh"> ]> </LIT> That's all there is to it. </SUBSECT1> </SECTION> ]]> </CHAPTER> </BODY> <APPMAT> <APPENDIX><TITLE>Troubleshooting</TITLE> When &p; processes an SGML document, there is some complex processing going on. The document's DTD, its associated style sheets, and its navigator definitions must be retrieved; possibly the <TT>CATALOG</TT> and <TT>ENTITYRC</TT> files as well. Then &p; parses the files needed, and brings up the result fully formatted on-screen. Any one of these processing steps may fail, for any number of reasons: the files may not be valid SGML, files are not found, or whatever. &p; does its best to recover gracefully from such processing errors. <SECTION ID="PARSEDOC"><TITLE>Parsing of Documents</TITLE> &p; is not a validating SGML parser. It expects the SGML documents to be normalized and correct, meaning that each element must be encapsulated by markup. <TT>SHORTTAG</TT> is the only markup minimization feature that is fully supported. Even so, &p; does a good job of making sanity checks on the SGML source, as e.g. all of the hyperlinking is created by the application's inherent knowledge of the corresponding concept. When there is a parsing problem, &p; will report it and let you locate the offending passage for possible remedial action. </SECTION> <SECTION ID="PARSEDEC"><TITLE>Parsing of the SGML declaration</TITLE> The parser does not use or interpret the SGML declaration, but knows how to skip its contents in order to reach the DTD. For more information on technical aspects, please consult the <XREF RID="TR-MAN">&p; Technical Reference</XREF>. </SECTION> </APPENDIX> <APPENDIX><TITLE>Keyboard Shortcuts</TITLE> &p; supports the use of mnemonics for accessing menus and commands from the keyboard, where a mnemonic is a letter that is associated with the menu or command. Mnemonics are always underlined for easy identification. You can bring down a menu by holding the <TT>Alt</TT> key down and simultaneously pressing the key with the mnemonic letter. Whenever a menu is visible, you can invoke the command corresponding to a mnemonic just by pressing its key. In addition, there are a number of keyboard shortcuts for invoking various &p; commands, listed in the tables below. <![ %windows; [ <TABLE> <TBODY><HEAD>File Menu</HEAD> <HEAD>Keyboard Equivalent</HEAD> <HEAD>Description</HEAD> <ROW> <CELL>Reload</CELL> <CELL>Ctrl+R</CELL> <CELL>Reparse the current file.</CELL> </ROW> ]]> <![ %PRO; [ <ROW> <CELL>Print</CELL> <CELL>Ctrl+P</CELL> <CELL>Print the current file.</CELL> </ROW> ]]> <ROW> <CELL>Exit</CELL> <CELL>Ctrl+F4</CELL> <CELL>Terminates the application.</CELL> </ROW> </TBODY> </TABLE> <TABLE> <TBODY><HEAD>Edit Menu</HEAD> <HEAD>Keyboard Equivalent</HEAD> <HEAD>Description</HEAD> <ROW> <CELL>Copy</CELL> <CELL>Ctrl+Ins</CELL> <CELL>Paste the contents of the clipboard.</CELL> </ROW> <ROW> <CELL>Search…</CELL> <CELL>Ctrl+S</CELL> <CELL>String searches the document for the corresponding string.</CELL> </ROW> <ROW> <CELL>First</CELL> <CELL>Ctrl+F2</CELL> <CELL>Scrolls to the next undisplayed occurrence of the sought string.</CELL> </ROW> <ROW> <CELL>Previous</CELL> <CELL>F2</CELL> <CELL>Scrolls to the previous undisplayed occurrence of the sought string.</CELL> </ROW> <ROW> <CELL>Next</CELL> <CELL>F3</CELL> <CELL>Scrolls to the next undisplayed occurrence of the sought string.</CELL> </ROW> <ROW> <CELL>Last</CELL> <CELL>Ctrl+F3</CELL> <CELL>Scrolls to the last occurrence of the sought string.</CELL> </ROW> <ROW> <CELL>Back</CELL> <CELL>Ctrl+B</CELL> <CELL>Backtrack to a previous location.</CELL> </ROW> <ROW> <CELL>Forward</CELL> <CELL>Ctrl+F</CELL> <CELL>Return after backtracking.</CELL> </ROW> </TBODY> </TABLE> <![ %PRO; [ <TABLE> <TBODY><HEAD>Options Menu</HEAD> <HEAD>Keyboard Equivalent</HEAD> <HEAD>Description</HEAD> <ROW> <CELL>Show Tags</CELL> <CELL>Ctrl+T</CELL> <CELL>Toggle the display of tags.</CELL> </ROW> <ROW> <CELL>Show Hot Spots</CELL> <CELL>Ctrl+H</CELL> <CELL>Toggle the display of hot spots.</CELL> </ROW> </TBODY> </TABLE> <TABLE> <TBODY><HEAD>Webs Menu</HEAD> <HEAD>Keyboard Equivalent</HEAD> <HEAD>Description</HEAD> <ROW> <CELL>Annotate</CELL> <CELL>Ctrl+A</CELL> <CELL>Annotate selection</CELL> </ROW> <ROW> <CELL>Bookmark</CELL> <CELL>Ctrl+M</CELL> <CELL>Attach bookmark to selection.</CELL> </ROW> <ROW> <CELL>Begin Link</CELL> <CELL>Ctrl+L</CELL> <CELL>Create source anchor in a link.</CELL> </ROW> <ROW> <CELL>Connect Link</CELL> <CELL>Ctrl+C</CELL> <CELL>Connect target anchor to source anchor.</CELL> </ROW> </TBODY> </TABLE> ]]> <![ %mac; [ <LIT> ************************************ * COPY NEEDS TO BE ADDED FOR MAC * ************************************ </LIT> ]]> <![ %motif; [ <LIT> ************************************** * COPY NEEDS TO BE ADDED FOR MOTIF * ************************************** </LIT> ]]> </APPENDIX> </APPMAT> </BOOK>