[Inso Home Page] [Home] [Collection] [Book] [Expand] [Collapse] [Search Forms] [Previous Section with Hits] [Next Section with Hits] [Clear Search] [Preferences] [Print] [Help]

 inside  Expand Search

 1. Introduction to DynaWeb Publishing   [Table of Contents]  3. Overview of DynaWeb Configuration Files

DynaWeb Publishers Guide

[-] 2. Publishing DynaText Books Using DynaWeb

2. Publishing DynaText Books Using DynaWeb


Purpose of this Chapter

This chapter provides an overview of the tasks required to publish both existing DynaText collections and word processing documents onto the Web using DynaWeb. This chapter provides an in-depth discussion of the use of stylesheets to control the conversion of the SGML source to its HTML equivalent.

Overview of Serving DynaText Books with DynaWeb

To serve out existing DynaText books through DynaWeb, you need to create a new stylesheet (named dynaweb.wv). This allows DynaWeb to map your DynaText styles to their closest HTML equivalents. Optionally, you can create DynaWeb variants of all your stylesheets (revelatory, TOC, etc.) if you also want to map those styles to HTML equivalents.

You will need to convert your graphics to a form that is commonly supported by Web browsers (for example: GIF, JPEG, XBM).

How DynaWeb Books Appear to Web Clients


Because the data that DynaWeb serves to clients is true HTML, browsers do not distinguish DynaWeb -served pages from standard HTML pages. DynaWeb's default interface serves frames to frame-enabled browsers and a non-frame layout to browsers that are not frame-enabled.

What Web Browsers Control

In general, browsers control the font and size charactistics of any text they download, as well as the final interpretation of the HTML tags used to augment your pages.

You can attempt to control these aspects of your documents by including such information as default-font and other meta-information. However, remember that the web browser always has final control over how your data is presented.

Introduction To Stylesheets

Purpose Of This Section

This section provides a high-level overview of the information needed in order to construct a functional dynaweb.wv stylesheet, including a step-by-step walkthrough for converting your SGML styles into their HTML counterparts. If you are not acquainted with stylesheets, additional information can be found in the Publishing: Document Preparation book located with your DynaText documentation..

What Stylesheets Do

Stylesheets provide information about the styles used inside your documents - in this case, your DynaText books. Examples of this information are font size and color. All of this information (called property values) is used by DynaText to control the way your information is displayed on the screen and in print. DynaText reads the information from the stylesheet and applies it wherever that style is used inside a document.

Style Groups and Inheritance

In order to understand how to create a DynaWeb stylesheet, you will need to understand the concepts of style groups and inheritance.

Style Groups

A style group contains property values that can be applied to a number of different styles. The style group sets the attributes and values for the entire group. Individual styles that belong to the group have no attributes of their own, rather, they draw their attributes and values from the group definition.

Each DynaWeb style group corresponds to a specific HTML element, for which the group is named; for example, the h1 style group corresponds to the HTML H1 element. By using the appropriate DynaWeb style groups, you can easily set up your conversion stylesheets to convert books from your DTD to the HTML DTD.


Inheritance is the method by which individual styles get their values from style groups. Styles that belong to a style group derive the attributes from the group. However, an attribute set inside an individual style overrides the derived value from that style's group.

The htmlgrps.v Stylesheet

DynaWeb supplies a stock stylesheet that you can add into an existing fulltext.v stylesheet. The htmlgrps.v stylesheet contains pre-set style groups that correspond to the basic HTML styles. You can easily assign existing SGML styles to the style group that provides the HTML tags the style needs. The SGML style then derives the necessary properties, such as text-before and text-after, from the style group.

The dynaweb.wv Stylesheet


The dynaweb.wv stylesheet provides mappings that allow DynaWeb to substitute HTML tags for the original SGML styles. At the same time, DynaWeb recognizes and evaluates the property-value functions (PVFs) contained in DynaText stylesheets. The dynaweb.wv stylesheet is kept with the other stylesheets used by the collection. If all of your books use a single DTD, then you will only need to create a single dynaweb.wv stylesheet. However, if you use more than one DTD, you will need to create a new stylesheet for each of the DTDs.

The fullhtml.v Stylesheet

In prior versions of DynaWeb, the dynaweb.wv stylesheet was named fullhtml.v. The 4.1 version of DynaWeb still recognizes the fullhtml.v stylesheet and will use it if it is available. If you already have fullhtml.v stylesheets created, they will work seamlessly with DynaWeb 4.1.

Acceptable main stylesheet names are:

Acceptable TOC stylesheet names are:

How DynaWeb Uses the dynaweb.wv Stylesheet

Once you've mapped each style to its HTML equivalents, DynaWeb uses the text-before and text-after properties of the style to insert HTML tags before and after each element instance.

Note: The following examples are presented as they would appear when using a text editor to edit your stylesheet.

Example: text-before

To illustrate, suppose there is a "Note" style in your DTD that automatically generates the text "Note: " at the start of an element. The style definition of the "Note" style would look like this:

<style name="NOTE">
    <text-before>   Note:   </> 

The text-before property of the "Note" style turns this tagged line:

<note>Be careful of thin ice!</note>

into this output:

Note: Be careful of thin ice!

In the dynaweb.wv stylesheet, we need to decide how we want to display the "Note" style using HTML. In this case, we'll just use a standard paragraph tag. Using the text-before and text-after properties, we can insert the tags the browser needs in order to display the "Note" style properly. The "Note" style in the dynaweb.wv stylesheet now looks like:

<style name="NOTE">
    <text-before>   <p>Note:  </>

If we were to display the element again in InStEd using the dynaweb.wv stylesheet, we would now see this output:

<p>Note: Be careful of thin ice!

Notice that the text output of the "Note" style now looks like valid HTML.

Property Value Functions

Property value functions are built-in functions provided by DynaText that can be used in stylesheets. DynaWeb recognizes and evaluates all of the property value functions used in its stylesheets. Any DynaText style that uses property value functions in text-before or text-after properties should not use the style groups provided in the htmlgrps.v stylesheet. If you do use the style groups, you will overwrite the PVF contained in the style. You must explicitly set the text-before and text-after properties inside the style in order to retain the property-value function.

Further Information: "Appendix B: Property Value Functions," Publishing: Document Preparation.

The starttag() and endtag() PVFs

When specifying text-after strings in particular, adding the closing HTML tag can be confusing. DynaWeb provides two PVFs of its own to aid in the mapping of SGML styles to HTML tags. Style attributes are closed with the following tag:


However, only the first two characters of the tag are important to the stylesheet parser. As a result, if we try to end an HTML tag normally in the text-after property, it would look like this:

<text-after> </p> </>

As soon as the stylesheet parser sees the left-angle (<) followed by the slash (/) character, it ends the style (in this case, prematurely). The above line ends up being read like this:

<text-after> </

and we lose the text-after content. Previously, this was avoided by using the join() PVF in the text-after property.

<text-after> join('<','/p>') </>

By delaying the evaluation of the ending tag until the text-after property was ended properly, the problem was avoided. Now, instead of typing in the entire join() PVF, you can simply type endtag() and specify the tag you are ending inside the parentheses, as follows:

<text-after> endtag(p) </>

This generates the following output in the text-after property:


Although it is not necessary to use it, the starttag() PVF is provided for symmetry and shares the same syntax as the endtag() PVF.

Creating a dynaweb.wv Stylesheet

Copying The fulltext.v Stylesheet

  1. Make a copy of the fulltext.v you want to convert and name the new file dynaweb.wv.
  2. Open the htmlgrps.v file located in the data/styles directory under the installation directory.
  3. Copy everything between the <sheet> and </sheet> tags. Paste it into the new dynaweb.wv file directly after the <sheet> tag.
  4. Replace the #SDATA statement from your original fulltext.v with the #SDATA statement in the htmlgrps.v stylesheet.
  5. Save the dynaweb.wv stylesheet.

    Assigning SGML Styles to HTML Groups

    Purpose of this Section

    This section provides a list of the basic tasks you will need to perform in order to map the styles contained in the newly created dynaweb.wv stylesheet to the HTML style groups.

    The HTML Style Groups

    The following table lists the supplied style groups and the HTML tags to which they refer. Each of the style groups shares its name with the HTML style (and tag) to which it refers.

    Group Name



    Address block


    Bold-faced text


    Block quotation


    Line break


    Corresponds to <entry> tag in CALS tables.


    Corresponds to <row> tag in CALS tables.


    Corresponds to <table> tag in CALS tables.


    Corresponds to <title> tag in CALS tables.


    Citation text


    Source code


    Definition of a term (in a definition list)


    Directory lists


    Definition list


    Term (in a definition list)


    Emphasized text

    h1 - h6

    Header levels: h1 is the most significant, h6 the least.


    Horizontal dividing line


    Italicized text


    Keyboard-entry text


    List item




    Ordered list




    Preformatted text


    Literal character(s)


    Strong-emphasis text


    Fixed-width text


    Unordered list (also bulleted)


    Variable-name text

    Procedure for Assigning Groups Using InStEd

    To assign SGML styles to HTML style groups and to customize the predefined style groups, use InStEd.

    Perform the following steps for each style you want to assign to a group:

    1. Set a group for the selected style.

      From the View menu, select Group List. The Group List appears in the List pane (the upper left pane of the InStEd window); for example:

      Figure 2-1: Group Listing in InStEd


      Each grouped style is displayed beneath the name of its group. Ungrouped styles are displayed at the end of the list.

      Using the Group List makes it easy to see which DynaText group assignments exist. Evaluating the effect of DynaText group assignments may be worthwhile, because assigning a style to a different group obviates any previous group assignments. Before changing the group assignment of a style, you may want to modify the style to replicate some or all of the property values of the DynaText group.

      Note: If you are not interested in the pre-existing group assignments, you might prefer to access style names by using the Style List. This displays all the styles together in alphanumeric order.

    2. From the list, select a style (by double clicking on its name).
    3. To assign a group to the selected style, from the Style menu, select Set Group.

      Note: You can place many styles in the same group. But you can assign each style to only one group.

    4. Optionally, verify the effects of assigning a style to a group. Select View|Style List. This displays all the styles together in alphanumeric order in the List pane. You can select any style whose group setting you want to view; for example, to view the effect of assigning the CHAPTER,TITLE style to the h2 group, select that style in the Style List, as follows:

      Figure 2-2: CHAPTER,TITLE Selected in Style List


      InStEd highlights the style name in the List pane. In the Preview pane (lower left of window), it highlights the next element belonging to the selected style, as follows:

      Figure 2-3: CHAPTER,TITLE Element Selected By InStEd


      By inspecting the highlighted element, you can see the effects of the style's group assignment. For the h2 group assignment in this example, notice that the h2 end tag (</h2>) appears, but the begin tag (<h2>) is missing. In this case, you would need to modify the style definition to complete the group assignment.

      Because the Preview pane displays several elements at once, you can often inspect the effects of several group assignments without having to select the styles. In this example, for instance, you can also view the effects of h3 and p group assignments. These assignments have correctly inserted the tags of the corresponding HTML h3 and p elements (the p element does not require an end tag).

      Note: If you double click on a style name in any list, InStEd displays the style's properties in one of the three Definition Forms (right side of window), where you can view and edit the style's properties

      Repeat this process for each style that you are assigning to a group. This completes the minimal amount of set-up work for a conversion stylesheet.

      Assigning Styles to HTML Groups without InStEd

      In order to assign your SGML styles to HTML style groups, you will need to decide which HTML styles best represent the styles you were using in your DynaText book.

      To add the style to one of the existing HTML groups, add the argument 'group="{groupname}" ', where {groupname} is the name of the group you wish the style to be a member of, directly after the style declaration:

      <style name="PARA" group="p"> </style>

      This allows the "PARA" style to use the "p" group's text-before and text-after properties.

      You will need to do this with all of the styles you wish to add to the HTML style groups. Remember that if a style uses a PVF in text-before or text-after properties, you may not want to add that style to a style group because its PVF will be overwritten by the style group's properties.

      Converting SGML Containers

      Many SGML DTDs use the idea of containers. Containers are used to surround a section of the document and allow that portion to be manipulated as a single unit. HTML does not support the idea of containers except in specific cases, such as lists and tables. Because HTML has no containers, these styles have no direct equivalent in the HTML DTD. The only portion of the container style that can be mapped is the label or title of the container, which can be mapped to one of the Heading elements of HTML (h1 to h6). When viewed from the browser, the illusion is that the container structure has been retained, when actually only the labels stand to mark where the containers begin and end.

      Here is an example of an SGML container structure:

           <LABEL>Green Vegetables</LABEL>
            <P>Broccoli is a green vegetable.</P>
             <P>Celery is also a green vegetable.</P>
           <LABEL>Yellow Vegetables</LABEL>
             <P>Corn is the only yellow vegetable I can think of.</P>

      By specifying one of the containers used in the example above (map, block, or subblock) you can easily control how much of the information is shown or requested. Since HTML has no containers, the HTML generated from the above example would be as follows:

           <H2>Green Vegetables</H2>
             <P>Broccoli is a green vegetable.</P>
             <P>Celery is also a green vegetable.</P>
          <H2>Yellow Vegetables</H2>
              <P>Corn is the only yellow vegetable I can think of.</P> 

      The idea of the containers is kept through the retention of the titles, but the actual containers are not translated into HTML. Only the titles and labels of the containers are translated. Therefore, these are the only styles we need to assign to HTML style groups.

      Remember, if your container titles use any text-before or text-after strings of their own, you must modify those styles individually in order to retain the original attribute.

      The only containers recognized by HTML tagging are lists and tables. Later sections will deal with these containers individually.

      Mapping HTML Lists

      Purpose of this Section

      The purpose of this section is to provide a more detailed explanation of using property value functions to map a single style of LIST with different TYPE attributes to HTML lists.

      Example: Mapping Lists

      This section presents one possible example of mapping lists from a publisher's DTD to the HTML DTD. The two DTD's use distinct logic for lists:

      • The publisher's DTD defines a single LIST element possessing a TYPE attribute that controls the type of list (either BULLeted or NUMbered). The syntax for a bulleted list is as follows:
        <LIST TYPE="BULL">  <ITEM><P>Sample Text Here</P></ITEM>
      • HTML defines three distinct types of lists: ordered list, unordered list, and definition list. In the example above, the use of the TYPE attribute allows one set of tags to define multiple types of lists. HTML, however, uses distinct tags to represent different types of lists.

        The correspondence between the tags used in the specific example above and the HTML unordered list elements is as follows:


        Corresponding HTML

        <list type="bull">


        <item><p>Sample Text Here</p></item>

        <LI>Sample Text Here



        In both cases, the output is:

        • Sample Text Here

      Refining Your Stylesheet

      In the previous example, we mapped <LIST> to the ul group and <ITEM,P> to the li group. However, this mapping cannot account for all of the lists that the original SGML markup was designed to accommodate. Therefore, we need to modify the text-before and text-after properties, using property-value functions to provide suitable tagging for each type of list.

      The table below compares the text-before and text-after values for our example. This example assumes that you have a basic knowledge of the PVFs covered in the Publishing: Document Preparation book. If you are not familiar with the PVFs mentioned in the following example, read Appendix D in the Publishing: Document Preparation guide or find someone who has dealt with PVFs before.

      Example: You have two types of LISTs, bulleted and numbered. If the different types of lists are referred to with different styles (say NUMLIST and BULLIST), then you can map each style to the HTML list to which it corresponds. However, if you use a single style, LIST, for all of your lists and differentiate between bulleted and numbered lists by using an attribute of the style (LIST type="bull"), you will need to use a property value function to properly tag the list. The following table shows the changes you need to make in order to modify the PVFs you use to adapt the style to each type to take the HTML tags into account.

      Style Names















      Note that the PVF moved to the LIST element because we had to decide at the LIST level whether to use a UL tag or an OL tag. The (LIST, P) element simply needed a LI tag, no matter which type of list was required. We no longer need to decide whether to use a bullet or a number on the (LIST, P) element because the browser takes care of that for us.



      DynaWeb includes a converter that recognizes DVI equations and automatically converts them to XBM images. This conversion is transparent to the reader, who receives a page of HTML with embedded inline images replacing the original equations.

      The conversion process runs every time an equation is requested as part of a response. The generated images are discarded immediately after the response is completed, eliminating the need for additional storage space or file maintenance.

      Figure 2-4: DVI Equation As Displayed Through DynaWeb


      Supported Equations

      In order for DynaWeb to automatically convert your equations to XBM images, they must be in DVI format. If your books contain SGML equations or TEX equations, they must be converted into DVI files in order for DynaWeb (or DynaText) to display them. An explanation of how to create DVI files for your TEX equations can be found in Chapter 9: "Links to Non-textual Objects" of the Publishing: Document Preparation book.

      If your equations are included in the form of raster files, DynaWeb will interpret them as normal figures.

      Searching inside Equations

      You may search inside your DVI equations if you included your equations in the index created during the mkbook procedure. (More information on indexing equations can be found in Chapter 7: "Inline Objects" of the Publishing: Document Preparation book.)

      When returning search hits contained inside equations, DynaWeb highlights the equation containing the search hit.

      Adding Equation Fonts

      In order to add custom fonts to your DynaWeb installation, your fonts must be in the PK font format. PK fonts are generated from TeX fonts using MetaFont. Equation fonts must be placed in the data/pkfonts directory under your DynaWeb installation directory. In addition, they must be named according to the following syntax: fontname.[dpi]pk where [dpi] is the size of the font that DynaWeb will use.



      DynaWeb automatically recognizes hyperlinks contained in DynaText books and translates them into HTML anchors. Once the dynaweb.wv stylesheet is completed, links within the same book will work without any further manipulation of the stylesheet.

      Referencing Stylesheets

      Sometimes stylesheets will designate another stylesheet to be used when displaying the target of a link. This stylesheet could be a revelatory stylesheet, or specify another stylesheet. When creating a dynaweb.wv stylesheet, check to make sure that you are not referencing any stylesheets that do not provide the correct HTML tags for your document.

      Change the stylesheet reference in your link style to point to the dynaweb.wv stylesheet or an HTML version of the revelatory stylesheet. If you use an alternate stylesheet for displaying the target of a link, you can repeat the steps for creating your dynaweb.wv stylesheet to create an HTML version of the specified stylesheet.

      Creating a New Window

      One attribute of the ebt-link property is the window attribute. This attribute determines whether the target of the hyperlink is shown in a new window or replaces the contents of the current window. If you choose to have the target open in a new window, be aware that Netscape and Microsoft both open new browser instances to display the target. If you have a link-heavy book or collection, these multiple browser instances may bog down the client machine. If you remove the window=new attribute from your links, the target will appear in the Content pane of the current browser.

      Linking across Books

      In order for DynaWeb to successfully create HTML equivalents for cross-book links, you will need to replace all occurences of idmatch in your dynaweb.wv with xidmatch. For example, when setting up a hyperlink style such as <EXTREF>, after copying the style into the dynaweb.wv stylesheet, modify the style so that the idmatch attribute is changed to xidmatch as in the second example below.

      <style name="EXTREF">
          <script>   ebt-link root=idmatch(ID, attr(RID)) book=attr(book)  window=new  stylesheet=link.rev  </>
      - - - - - - - - - - - - - - -
      <style name="EXTREF">
          <script>   ebt-link root=xidmatch(ID, attr(RID)) book=attr(book)  window=new  stylesheet=link.rev  </>

      Note: xidmatch only needs to be present in styles that deal with links that cross between books. Links that travel within the confines of a single book do not need to be altered.

      Using query() in ebt-link Expressions

      In addition to substituting xidmatch for idmatch in your dynaweb.wv stylesheet, you will also need to substitute xquery for query in your ebt-link attributes. Follow the instructions for xidmatch to replace query with xquery in your stylesheet.

      Linking Inside a DynaText Book through a URL

      DynaWeb allows publishers to link to specific places inside their DynaText books in the URL of the request. After the book name in the URL, add the following line:


      where [ID#] is a valid ID or REFID inside the book.

      This allows publishers to embed links to specific pages or sections inside their DynaText books and be able to display that section in DynaWeb.

      TCL() PVF

      The TCL PVF allows publishers to access Tcl and the Tcl extensions for DynaWeb from a PVF inside a stylesheet. Publishers can use the DynaWeb Tcl extensions to access and modify the HTTP header information from their stylesheets.


      The TCL PVF can be inserted into stylesheets in the same manner as any PVF. The syntax for the TCL PVF is:


      The value of [TCL_COMMAND] must be surrounded by quotes and must be a valid Tcl extension. Due to limitations in the nature of TOC and content generation, the Tcl extensions that deal with TOC and content generation cannot be used with the TCL PVF. A list of valid and invalid Tcl extensions follows this section.

      Note: If you use the Tcl commands dwCall or dwProcessTemplate in a TCL PVF, the returned value of the command is substituted in place of the TCL PVF. For example, if in a TCL PVF, you call a script that resolves to either true or false, the returned value will be substituted for the TCL PVF. In the following example, the figure will be hidden depending on the returned value of the script ShowFigures, which looks at the URL to see whether the user has turned off displaying figures and returns either a value of "true" or "false".

      <STYLE name="FIGURE"> 
          <hide> TCL("dwCall ShowFigures") </>

      After the script is called, the TCL PVF is replaced with the value of ShowFigures.

      <STYLE name="FIGURE">
          <hide> true   </>

      Valid Tcl Extensions for Use with the TCL PVF

      HTTP-Related Tcl Extensions







      URL-Related Tcl Extensions






























      Utility Tcl Extensions










      Invalid Tcl Extensions for Use with the TCL PVF


















      Page-Related Tcl Extensions







       1. Introduction to DynaWeb Publishing   [Table of Contents]  3. Overview of DynaWeb Configuration Files