# Using Architectural Forms

Your SGML documents conform to a particular document type definition (DTD). To make the Information Manager understand how to treat the elements defined in your DTD, you apply attributes to basic elements in the DTD. These attributes correspond to Information Manager architectural forms, which are semantics that Information Manager interprets to build documents into an on-line library.

The examples in this section are from version 2.2.1 of the DocBook DTD.

Information Manager architectural forms are based on the organizational model of documentation in the Information Manager. The Information Manager groups an information library into bookcases containing books with sections whose titles are arranged in a hypertext table of contents. It includes access to specific elements such as tables and graphics.

Bookcases, books, sections, titles, links, tables, and graphics, are examples of important elements that the browser must identify to manage the information. Information Manager provides architectural forms that correspond to each of these types of information. To identify these pieces for the Information Manager, you apply the corresponding architectural forms to your DTD. Specifically, you add attributes to each element that has characteristics you want to identify. To make it easier to maintain your DTD, use parameter entity references provided by the Information Manager.

## Using Parameter Entity References

The Information Manager provides parameter entity references as a quick (and recommended) way to use Information Manager architectural forms. The entity names for Information Manager architectural forms are stored in `/usr/dt/infolib/<lang>/SGML/dtinfo.af`. By using parameter entity references in your attributes list rather than entering complete attributes, you'll be able to take advantage of new features of the Information Manager, while minimizing changes to your DTD. For example:

- To apply the complete attribute:

      <!ELEMENT caption - - ((%inlinechar.gp;)+) >
      <!ATTLIST caption
              %commonatts;

              DTINFO.TITLE CDATA #FIXED “#CONTENT”
      >

- To use the parameter entity reference:

      <!ELEMENT caption - - ((%inlinechar.gp;)+) >
      <!ATTLIST caption
              %commonatts;

              %DTINFO.Title; “#CONTENT”
      >

See Applying Architectural Forms and Description of Information Manager Architectural Forms for more information on editing your DTD.

## Description of DTINFO Architectural Forms

The descriptions of architectural forms identify related forms, forms that are commonly used in conjunction with the architectural form being described. A related form is identified in the documentation using its corresponding attribute name. This section discusses:

- Section Forms

- Value Form

- Scope Forms

- Hypertext Forms

- Style Form

Although it is easier to create tables of contents, bookcase specifications and style sheets from scratch, you can apply Information Manager architectural forms to existing bookcase, style sheet, and table of contents DTDs. For more information see Bookcase Forms, Style Sheet Forms, and Table of Contents Forms.

These architectural forms must be applied before most `dtdocbook2infolib` subcommands can be used.

### Understanding Values

For Information Manager architectural forms that take data values, a simple functional language provides a mechanism to assemble combinations of element content, attribute values, and literals. The arguments are defined in the table Syntax for Creating Values.

### Syntax for Creating Values

`Syntax` | `Meaning`
attr() | attr() returns the value of the attribute name used as the argument. IMPLIED attributes return an empty string. attr() references attributes on the current element only.
concat() | concat() concatenates string arguments (literals, contents of elements, attribute values, or values of the other functions).
firstof() | firstof() returns the first non-empty string in its arguments. It chooses the value from the order of possibilities defined by its arguments.
`element name` | `element name` uses, as the value, the name of an element that is a member of the current element's content model.
`literal string` | `literal string` uses either a pair of '...' or "..." enclosing quotes to signify a literal string
#CONTENT | #CONTENT uses all of the current element's content as the value.

You can combine the syntax explained in the table to create the value you want, and you can add literal strings as needed.

Examples of specifying values for architectural forms are:

    DTINFO.Title  CDATA             #FIXED
                                        "concat( attr(Label), RefTitle, ManVolNum )"
    DTINFO.Graphic  CDATA           #FIXED
                                      "firstof( attr(Fileref), attr(Other), #CONTENT )"

### Section Forms

For the Information Manager to understand the structure of your SGML files, you must apply section architectural forms. The use and meaning of a form's value depends on the type of form it is. For example, when specified for a chapter title, the value is displayed in the hypertext table of contents. For `DTINFO.Graphic`, the value is the name of the file containing the graphic data. These relationships are described in the table Meaning of the Form Values.

### Meaning of the Form Values

`Section Form` | `Meaning of Value Form, When Applied`
DTINFO.Section | The value of a section is what would be displayed in the Information Manager Reading window. The default is #CONTENT.
DTINFO.Title | The value of a title for DTINFO.Section is displayed in the Information Manager Book List.
DTINFO.Graphic | The value of a graphic is the file name containing the graphical data. This value can also be derived from entity references.
DTINFO.Ignore | This information will not be stored in the database or in the FulText Index (so it won't be displayed).
DTINFO.ShortTitle | The value of a shorttitle is the text used in certain places in the Reading window where a full title might be truncated.

`DTINFO.Section`

- Apply the `DTINFO.Section` form to container elements that separate pieces of information such as chapters. Use `DTINFO.Section` to define which elements you want displayed to readers as a unit of information in a reading window of the Information Manager. `dtdocbook2infolib` can derive the hierarchy by containment using `DTINFO.Section`.

  Entity name: `DTINFO.Section`

  Attribute template: `DTINFO.Section CDATA FIXED “#CONTENT”`

  Related Forms: `DTINFO.ID` (Required), `DTINFO.Scope`, `DTINFO.ShortTitle`, `DTINFO.Style`, `DTINFO.Title` (Required), `DTINFO.Value`

  Example:

      <!ELEMENT Preface - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;)) >
      <!ATTLIST Preface
              %commonatts;

              %DTINFO.Section;            “#CONTENT”
              %DTINFO.Style;              “sty1”
              %DTINFO.Title;              “#CONTENT”
              %DTINFO.ID;                 “attr(id)”
      >

`DTINFO.Title`

- You typically apply `DTINFO.Title` to any type of title, including chapter titles, headings, captions, figure titles, table titles, and example titles.

  Entity name: `DTINFO.Title`

  Attribute template: `DTINFO.Title CDATA #FIXED`

  Related Forms: `DTINFO.Scope`, `DTINFO.Value`

  Example:

      <!ELEMENT RefMeta - - (RefEntryTitle, ManVolNum?,RefMiscInfo*) >
      <!ATTLIST RefMeta
              %commonatts;

              %DTINFO.Title;          #“CONTENT”
              %DTINFO.Value;          “concat( RefEntryTitle, ManVolNum)”
      >

`DTINFO.ShortTitle`

- If your existing DTD has an abbreviated form of a title, apply the `DTINFO.ShortTitle` to that element. The content of this element is never displayed in a reading window, but may appear as a list item in a dialog. The content does not appear in the FulText index.

  Entity name: `DTINFO.ShortTitle`

  Attribute template: `DTINFO.ShortTitle CDATA #FIXED`

  Related Forms: `DTINFO.Value`

  Example:

      <!ELEMENT TitleAbbrev - - ((%inlinechar.gp;)+) >
      <!ATTLIST TitleAbbrev
              %commonatts;

              %DTINFO.ShortTitle;  “#CONTENT”
      >

`DTINFO.Graphic`

- Apply `DTINFO.Graphic` to elements that designate graphics, mathematical equations, or certain types of tables.

  Entity name: `DTINFO.Graphic`

  Attribute template: `DTINFO.Graphic CDATA #FIXED`

  Related Forms: `DTINFO.Scope`, `DTINFO.ID`.

  Example:

      <!ELEMENT Graphic - - CDATA>
      <!ATTLIST Graphic
              Entityref   ENTITY   #IMPLIED
              Fileref     CDATA    #IMPLIED
              Format      NOTATION
                          %notationtypes; #IMPLIED
              Id          ID       #IMPLIED

              %DTINFO.Graphic; “#CONTENT”
              %DTINFO.ID;      “:attr( ID )”
              %DTINFO.Scope.Graphic;
      >

`DTINFO.Table`

- We may not support DTINFO.Table - so it may be commented out in future documentation. Elements that designate SGML-encoded tables according to the CALS table model should receive the `DTINFO.Table` attribute. Otherwise they should receive `DTINFO.Graphic`.

  Entity name: `DTINFO.Table`

  Attribute template: `DTINFO.Table CDATA #FIXED`

  Related Forms: `Scope.Table`.

  Example:

      <!ELEMENT InformalTable - - ((%tblcontent.gp;)) -(Table|InformalTable)>
      <!ATTLIST InformalTable
              %commonatts;

              Colsep   %yesorno;                          #IMPLIED
              Frame    (Top|Bottom|Topbot|All|Sides|None) #IMPLIED
              Orient   (Port | Land)                      #IMPLIED
              Pgwide   %yesorno;                          #IMPLIED
              Rowsep   %yesorno;                          #IMPLIED
              Tabstyle NMTOKEN                            #IMPLIED

              %DTINFO.Table;      “#CONTENT”
              %DTINFO.Scope.Table;
      >

`DTINFO.Ignore`

- Apply `DTINFO.Ignore` to elements that contain information you do not want to have displayed. If the elements contain useful hypertext information, it will be used during the build process. For example, you can provide a `DTINFO.Value` that is passed up and used to create a hypertext value.

  Entity name: `DTINFO.Ignore`

  Attribute template: `DTINFO.Ignore CDATA #FIXED`

  Related Forms: `DTINFO.Value`

  Example:

      <!ELEMENT InternalComment - - ((%inlinechar.gp;)+)>
      <!ATTLIST InternalComment
              %DTINFO.Ignore; “#CONTENT”
              %DTINFO.Value;          “#CONTENT”
      >

### Value Form

The `DTINFO.Value` form defines the return value of an architectural form. `DTINFO.Value` returns a value to a higher-level element. For example, assume element `foo` has a content model of `a?`, `b`, and `foo` uses the architectural form `DTINFO.Title firstof “(a,b)”`. The value of `a` might be constructed by concatenating its `Label` attribute and its content. This construction can be processed and given to `foo` using `DTINFO.Value`. Only one `DTINFO.Value` can be placed on any element.

The value architectural form is:

`DTINFO.Value`

- The `DTINFO.Value` attribute specifies a return value for an architectural form. The value for `DTINFO.Value` is a functional language that creates a stream to be used as a value. The value takes the form of an implied concatenation. The arguments are defined in the table Syntax for Referencing Values.

  Entity name: `DTINFO.Value`

  Attribute template: `DTINFO.Value CDATA #FIXED “ `Value`”`

  Related Forms: All section forms

  Example:

      <!ELEMENT RefMeta - - (RefEntryTitle, ManVolNum?,RefMiscInfo*) >
      <!ATTLIST RefMeta
              %commonatts;

              %DTINFO.Title;
              %DTINFO.Value; “concat( RefEntryTitle,'(`,
      ManVolNum,')')”
      >

### Scope Forms

In the Information Manager, users can define the scope of searches. They can tell the browser which books to include in a search, and can specify whether to search all components of the books, body text, examples, indexes, graphics, tables, titles, or some combination thereof. Scope architectural forms determine which elements are included in a search scope in the Information Manager. Specifically, they determine which scope information is indexed within the FulText index. The scope applies to any element contained within an element to which `DTINFO.Scope` has been applied.

To apply scope forms to an element, you apply the `DTINFO.Scope` attribute with any of five values. If you do not apply a scope form to an element the data has the default scope of `Body Text`.

Possible values for `DTINFO.Scope` include Example, Graphic, Index, Table and Title, and are represented by these entities:

`DTINFO.Scope.Example`

- Apply the `DTINFO.Scope` attribute with a value of `Example` to elements that contain data you want to include in searches that are scoped to include examples.

  Entity name: `DTINFO.Scope.Example`

  Attribute template: `DTINFO.Scope Name #FIXED Example`

  Example:

      <!ELEMENT Example - - (Title, TitleAbbrev?, (%para.gp; |
                              %list.gp; | %object.gp;)+) >
      <!ATTLIST Example
              %commonatts;
              Label  CDATA  #IMPLIED

              %DTINFO.Scope.Example;
      >

`DTINFO.Scope.Graphic`

- Apply the `DTINFO.Scope` attribute with a value of `Graphic` to elements you want included in searches that are scoped to include graphics. The effect of applying this architectural form is that any strings contained within certain graphic types may be extracted and indexed for searching.

  Entity name: `DTINFO.Scope.Graphic`

  Attribute template: `DTINFO.Scope Name #FIXED Graphic`

  Related Forms: `DTINFO.Graphic`, `DTINFO.ID`, `DTINFO.Value`

  Example:

      <!ELEMENT Graphic - - CDATA>
      <!ATTLIST Graphic
              Entityref   ENTITY               #IMPLIED
              Fileref      CDATA               #IMPLIED
              Format      NOTATION
                               %notationtypes  #IMPLIED
              Id                 ID                   #IMPLIED

              %DTINFO.Graphic;
              %DTINFO.ID;             “attr( Id )”
              %DTINFO.Scope.Graphic;
              %DTINFO.Value;          “attr( Fileref )”
      >

`DTINFO.Scope.Index`

- Apply the `DTINFO.Scope` attribute with a value of `Index` to elements you want included in searches that are scoped to include book indexes.

  Entity name: `DTINFO.Scope.Index`

  Attribute template: `DTINFO.Scope Name #FIXED Index`

  Related Forms: `DTINFO.Section`

  Example:

      <!ELEMENT (SetIndex | Index) - - (DocInfo?, (Title,
                             TitleAbbrev?)?, (%component.gp;)*, (IndexDiv+ |
                             IndexEntry+)) >
      <!ATTLIST (SetIndex | Index)
              %commonatts;

              %DTINFO.Section;
              DTINFO.Scope.Index;
      >

`DTINFO.Scope.Table`

- Apply the `DTINFO.Scope` attribute with a value of `Table` to elements you want included in searches that are scoped to include tables. The effect of this architectural form is that any strings contained within the CALS SGML table model are indexed for searching.

  Entity name: `DTINFO.Scope.Table`

  Attribute template: `DTINFO.Scope Name #FIXED Table`

  Related Forms: `DTINFO.Table`.

  Example:

      <!ELEMENT InformalTable - - ((%tblcontent.gp;)) -(Table|InformalTable)>
      <!ATTLIST InformalTable
              %commonatts;
              Colsep       %yesorno;                          #IMPLIED
              Frame        (Top|Bottom|Topbot|All|Sides|None) #IMPLIED
              Orient      (Port | Land)                       #IMPLIED
              Pgwide      %yesorno;                           #IMPLIED
              Rowsep    %yesorno;                             #IMPLIED
              Tabstyle    NMTOKEN                             #IMPLIED

              %DTINFO.Table;
              %DTINFO.Scope.Table;
      >

`DTINFO.Scope.Title`

- Apply the `DTINFO.Scope` attribute with a value of `Title` to elements you want included in searches that are scoped to include titles.

  Entity name: `DTINFO.Scope.Title`

  Attribute template: `DTINFO.Scope Name #FIXED Title`

  Related Forms: `DTINFO.Title`, `DTINFO.Value`.

  Example:

      <!ELEMENT RefMeta - - (RefEntryTitle, ManVolNum?, RefMiscInfo*) >
      <!ATTLIST RefMeta
              %commonatts;

              %DTINFO.Title;
              %DTINFO.Scope.Title;
              %DTINFO.Value; “concat( RefEntryTitle, ManVolNum)”
      >

### Hypertext Forms

The attributes corresponding to hypertext architectural forms are `DTINFO.ID` and `DTINFO.IDREF`. For information on assigning a value for these attributes see the table Syntax for Referencing Values.

SGML reference concrete syntax specifies that the value of `DTINFO.ID` and `DTINFO.IDREF` must be no more than 1024 characters long and must start with an alpha-numeric character.

`DTINFO.ID`

- Apply the `DTINFO.ID` attribute to any element which specifies the destination of a link.

  Entity name: `DTINFO.ID`

  Attribute template: `DTINFO.ID CDATA #FIXED “`Value`”`

  Related Forms: All

  Example:

      <!ELEMENT Anchor - O EMPTY >
      !ATTLIST Anchor
              Id              ID              #REQUIRED
              Pagenum         CDATA           #IMPLIED
              Remap           CDATA           #IMPLIED
              Role            CDATA           #IMPLIED
              XRefLabel       CDATA           #IMPLIED

              %DTINFO.ID;                     “attr( Id )”
      >

  The value of each `DTINFO.ID` must be unique.

`DTINFO.IDREF`

- Apply the `DTINFO.IDREF` attribute to any element that contains data to be used as a hot spot for traversing to the location specified as the value for `DTINFO.IDREF`.

  Entity name: `DTINFO.IDREF`

  Attribute template: `DTINFO.IDREF CDATA #FIXED “`Value`”`

  Related Forms: All

  Example:

      <!ELEMENT Link - - ((%inlinechar.gp;)+) >
      <!ATTLIST Link
              Endterm         IDREF           #IMPLIED
              Linkend         IDREF           #REQUIRED
              Type            CDATA           #IMPLIED

              %DTINFO.IDREF; “attr( Linkend )”
      >

  The value of `DTINFO.IDREF` should be the value of an existing `DTINFO.ID`.

### Style Form

The attribute corresponding to the style architectural form is:

`DTINFO.Style`

- Apply the Information Manager style architectural form, `DTINFO.Style`, to elements to which you have already applied the structural form `DTINFO.Section` and for which you want to override their inherited style sheet. `DTINFO.Style` can be used only for elements with `DTINFO` architectural forms `Bookcase`, `Book` and `DTINFO.Section`.

  The value of `DTINFO.Style` is the name of a style sheet (the value of a style sheet's `DTINFO.ID` architectural form) and must resolve to a style sheet specified in the bookcase specification document. Style sheets are inherited by all subordinate sections unless they are overridden with a new one.

  Because the content of `DTINFO.Style` is a string that matches the ID of a stylesheet name (and is not an element) it must be quoted twice, as in `%DTINFO.Style; “‘sty1’”` or in the form `%DTINFO.Style “concat(‘sty1’)”`

  Entity name: `DTINFO.Style`

  Attribute template: `DTINFO.Style CDATA #FIXED “`Value`”`

  Related Forms: `DTINFO.Section`

  Example:

      <!ELEMENT Preface - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;)) >
      <!ATTLIST Preface
              %commonatts;

              %DTINFO.Section;
              %DTINFO.Style;  “‘sty1’”
      >

## Applying Architectural Forms

Use this procedure to apply architectural forms to your DTD. Refer to Description of Information Manager Architectural Forms for information on when to apply architectural forms to an element in your DTD:

Applying the attributes for architectural forms does not invalidate your document instance, nor does it require any modifications to your document instance.

1. At the top of your DTD, add the entity declaration and use statement for Information Manager architectural forms:

       <!ENTITY % DOCBOOK PUBLIC
        “-//Common Desktop Environment//ENTITIES DtInfo Architectural Forms//EN”
       >
       %DOCBOOK;

2. Analyze your DTD to understand what you want to display.

3. Identify container elements and the corresponding section architectural form for each. For example, an element for figure captions corresponds to the `Title` form.

4. In the attributes list for the element you are modifying, enter the parameter entity reference or complete attribute.

   To use the parameter entity reference:

       <!ELEMENT caption - - ((%inlinechar.gp;)+) >
       <!ATTLIST caption
               %commonatts;

               %DTINFO.Title; “#CONTENT”
       >

   To use the complete attribute:

       <!ELEMENT caption - - ((%inlinechar.gp;)+) >
       <!ATTLIST caption
               %commonatts;

               DTINFO.Title CDATA #FIXED “#CONTENT”
       >

   Some architectural forms have related, required forms. For example, the `DTINFO.Section` form requires an `DTINFO.Title` and an `DTINFO.ID`. See Description of Information Manager Architectural Forms for details.

5. For the element you are working with, determine whether to apply a hypertext form:

       <!ELEMENT Graphic - - CDATA>
       <!ATTLIST Graphic
               Entityref       ENTITY          #IMPLIED
               Fileref         CDATA           #IMPLIED
               Format          NOTATION
                               %notationtypes  #IMPLIED
               Id              ID              #IMPLIED

               %DTINFO.Graphic;
               %DTINFO.ID;                     “attr( Id )”
       >

   You can build a bookcase after applying a minimum of `DTINFO.Section`, `DTINFO.Title`, and `DTINFO.ID` forms.

6. For the element you are working with, determine whether to apply a data form:

       <!ELEMENT Graphic - - CDATA>
       <!ATTLIST Graphic
               Entityref       ENTITY          #IMPLIED
               Fileref         CDATA           #IMPLIED
               Format          NOTATION
                               %notationtypes  #IMPLIED
               Id              ID              #IMPLIED

               %DTINFO.Graphic;
               %DTINFO.ID;                     “attr( Id )”
               %DTINFO.Value;                  “attr( Fileref )”
       >

7. For the element you are working with, determine whether to apply a scope form:

       <!ELEMENT Graphic - - CDATA>
       <!ATTLIST Graphic
               Entityref       ENTITY          #IMPLIED
               Fileref         CDATA           #IMPLIED
               Format          NOTATION
                               %notationtypes  #IMPLIED
               Id              ID              #IMPLIED

               %DTINFO.Graphic;
               %DTINFO.Scope.Graphic;
               %DTINFO.ID;                 “attr( Id )”
               %DTINFO.Value;              “attr( Fileref )”
       >

8. For elements to which you have applied the `DTINFO.Section` architectural form, determine whether to use a style sheet other than the one inherited by this section. To use a different style sheet, apply a style form:

       <!ELEMENT Preface - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;)) >
       <!ATTLIST Preface
               %commonatts;

               %DTINFO.Section;
               %DTINFO.Style;     “sty1”
       >

9. Repeat steps 4 through 7 for each element which requires an architectural form.