MIL-M-28001A APPENDIX B 70. GUIDELINES 70.1 Introduction. This section provides additional material to be used by those creating a Formatting Output Specification Instance (FOSI) or altering an existing one. This material is supplemental only; in order to create or modify a FOSI, the author must have a good working knowledge of sections 10 through 40 of this appendix. The principles discussed in this section are illustrated in the Template FOSI in Section 50, and the reader may find it useful to cross- reference between the two sections. Ideally, a FOSI author has a background in typographic design and has a working knowledge of SGML. The most important qualification, however, is intimate familiarity with the requirements of the functional specification that are to be represented through the FOSI. It may be possible to gain enough expertise to create or modify a FOSI by carefully reading this appendix and using the Template FOSI as a baseline. The following subsections describe a typical approach to creating or modifying a FOSI. Within each step of the approach, techniques for applying specific OS concepts are discussed. In addition, relevance of OS concepts to particular element types within the Template DTD of Appendix A are noted. The novice FOSI author may find it useful to read this entire section in order to get an idea of the topics discussed. Throughout this section, the characteristic names are used as they appear in Section 30 and are capitalized. To help the reader relate constructs and characteristics to their actual encoding specified in section 40, the names appearing in the DTD may also follow in parenthesis (generally shortened versions and uncapitalized). In referring to values of characteristics of type "toggle", the phrases "turned on" and "turned off" are used to mean non-zero and zero, respectively. 70.2 Step 1 - Understanding the Requirements. The first step in creating a FOSI is understanding the requirements for the structure and formatting of the documents to be interchanged. The information about the structure of the document should already be rigorously described in a Document Type Definition (DTD). The DTD defines the element types, the possible structure the document can have using these element types, and the attributes that can be associated with each element type. Ideally, there is supporting documentation to describe the meaning and usage of each element type and its attributes, although if such documentation is not available, the burden may fall upon the FOSI author to determine this information from the original functional specification. -365- MIL-M-28001A APPENDIX B Formatting information may be contained in a single functional specification or may appear in a combination of specifications. Again, the burden may fall upon the FOSI author to determine how the formatting information in the specifications relates to the element types defined in the DTD. In addition, the FOSI author must identify all relevant formatting information in the specifications that must be included in the FOSI, for example, page makeup information. There may be cases where an organization uses formatting practices in addition to or in place of formatting guidelines in the functional specifications. These "common practices" have been indirectly approved because of acceptance of delivered documents using these practices. An example is the common use of kerning in documents conforming to MIL- M-38784B, where kerning is not mentioned in the specification. The FOSI author must be aware of these "common practices", typically documented in the organization's style guidelines, so that all the relevant formatting information is included in the FOSI. 70.3 Step 2 - Understanding OS Concepts. The FOSI author must be aware of some underlying principles of the OS in order to correctly communicate the formatting information. Following is a discussion of these basic principles. 70.3.1 Intent of a FOSI. A FOSI is intended to specify, in general, how a particular class of documents should be formatted. It does not specify how any particular document was actually formatted; this appendix is not precise or robust enough to provide all the necessary information. Characteristics are in general descriptions of the format of a document, rather than commands that tell a formatting system what to do. For example, if a FOSI has a value of "10" for the Font Size Characteristic for element type "A", this should be interpreted as: "However your formatting system works, make sure that font size 10 is used to process element 'A'." The FOSI should not be interpreted as saying "When you see a start-tag for element 'A' call a command that changes the font size and give it a value of 10". This is a subtle, but extremely important, distinction. The first interpretation allows any system (including a human) to create the desired end result, while the second interpretation allows for only systems with a specific command language to easily create the desired result. In this way, the OS does not presume to direct how a formatting system should behave in order to accomplish the desired result. 70.3.2 Identification and Treatment of Source Data. The basic unit of data within the source document identified within a FOSI is an element (qualified by its context and occurrence). Additionally, attribute values associated with the element can be identified. Once identified, an element is treated as as whole. That is, the -366- MIL-M-28001A APPENDIX B characteristics associated with the element through the FOSI apply to all the content of that element. There is no notion of "start-tag" and "end-tag" processing. In general, it is safe to think of the characteristics as "going into effect" as soon as processing of the element's content begins. Some characteristics, however, are designed to take affect "after" the element content has been processed and are so identified in this specification. An example is the "End Line" characteristic. In addition, some characteristics specify whether other characteristics take affect "before" or "after" the element content is processed, for example, the Placement characteristic of the Puttext, Putgraph, and Usetext categories. 70.3.3 Cognizance of Source DTD. In general, it should be possible to determine the formatting of a document without any knowledge of the source DTD whatsoever. In other words, every relevant element and attribute in the source DTD should have an entry in the FOSI identifying its category and describing how it is to be formatted. In processing a FOSI, there should be no assumptions made about the source data. For example, an element type of "ftnote" cannot be assumed to be a footnote. It must be identified as a footnote by positioning its description in the proper structure of the FOSI (the "ftndesc"). A footnote can have the element type "xyz" in the source DTD, but as long as it is described in the "ftndesc" of the FOSI, it will be treated as a footnote. Similarly, all attributes that affect formatting must be identified in the FOSI. 70.4 Step 3 - Organizing and Documenting a FOSI. 70.4.1 Technique - Order of elements-in-context in the FOSI. The order of the elements-in-context within the Style, Table, Graphics, or Footnote Descriptions has no bearing on how the element is formatted. Some sensible ordering scheme is useful, however, for human readability and access. Ordering the elements-in-context to match the order of element types in the source DTD may be a good choice, as the reader of the FOSI is most likely familiar with the source DTD. Typically, the source DTD reflects the structure of the document and provides a progression from "structural"-type elements (like chapters and sections) through "paragraph"-type elements (like title and para) down to "inline"-type elements (like emphasis). If the source DTD does not provide this type of ordering, you may find it useful to group FOSI entries into these types of functional areas as they may share common types of descriptions. 70.4.2 Technique - Documenting a FOSI. It is good practice to include comments within a FOSI to explain techniques used. Comments cannot be used in place of encoding information through characteristics, but they can help the reader understand the intent of a particular encoding. Comments are preceded by the string "". They can be placed between any elements in the FOSI but not within tag delimiters. -367- MIL-M-28001A APPENDIX B 70.5 Step 4 - Setting up the Security Description. In the Security Description, you set up the strings that are to be automatically generated for the "security text" identified in the header and footer. To set up these strings, you must know the possible values for the attribute in the source DTD that indicates security. First, identify the name of the attribute in the source that indicates security levels with the "attspec" characteristic. Then, through the Secorder, you indicate the priority of its values. This priority is used when computing the value that is to appear in the header or footer. Then you can set up the string that is to appear for each value. Style and positioning characteristics are specified for the string through the "sectext" portion of the header and footer specification. 70.6 Step 5 - Setting up Page Models. A description of how the pages are to look (the page model) can be set up independently of the content that goes on them. The areas in which content are to be placed and their placement and relationship are defined in Section 30.4. Using Figure 2 in Section 30 as a guide, the FOSI author must analyze the formatting specifications for page layout to determine the sizes of these areas and specify the characteristics that control how and when these areas are created on the page. 70.6.1 Technique - Using Page Sets. Page sets give you the means to specify automatic relationships between recto, verso, and automatically generated blank pages. Typically, these relationships are useful when the document is to be printed "two-sided" in a book style. Each page layout can be described individually, but if only the recto page is described, all pages have the same layout. By turning on the Recto/Verso toggle, inner and outer margins are automatically reversed on recto and verso pages, usually to allow a wider margin for the bind edge. By turning on the Blank Page toggle, special actions can be taken when a blank page is automatically generated, for example, when the text for a new chapter starts on a recto page and the text for the previous chapter ends on a recto page. To specify these actions, define a "Blank Page Logic" usage rule for the Usetext characteristic when placing text in the header or footer. 70.6.2 Technique - Setting Page Parameters. The layout areas within the page can be thought of as a set of building blocks that must fit together. Because their relationships are defined in the OS (refer to Section 30.4 and Figure 2), it is your responsibility to ensure that the sizes you specify are valid. For example, the width of the Header Area is always the same width as the Flowing Text Area, but you can define the depth. You can also define the depth of the Top Margin, Flowing Text Area and the space above and below it, the Footer Area, and the Bottom Margin. You must ensure that the sum of these depths equals the depth of the page. -368- MIL-M-28001A APPENDIX B One approach to defining the sizes of layout areas is to first define the width and depth of the page. Then define the widths of areas. Most likely, the width of a column is the most important parameter. If there are multiple columns on the page, define the widths of the Column Area and Gutter Area. The sum of these widths provides the width of the Flowing Text Area. The difference between the width of the page and the width of the Flowing Text Area is then divided between the Left Margin and Right Margin. It may be divided equally, or if you are doing recto/verso printing, you may want to leave slightly more space for the margin that is the bind margin. Now determine the depths. Choose the most important parameter and work from there. For example, you may know the depth of the Flowing Text Area and the Top and Bottom Margins. Divide the remaining space between the Header and Footer Areas, leaving some Space Above and Space Below the Flowing Text Area if desired. Note that the depth of some areas is flexible, allowing for a minimum, nominal, and maximum depth. Always work with the nominal depth in your computations. The Change Mark Area can be thought of as "overlaid" on the Margins; its width and depth are specified independently of other size computations. 70.6.3 Technique - Using Page References. Page references are a shortcut for specifying a page model when its only difference from another page model is the header and footer information. Each page model can be assigned a unique identifier through the "pgid" attribute. A page reference then refers to this page model through the "pgidref" attribute and any header and footer information additionally supplied overrides the header and footer information in the referenced page model. If no header and footer information is supplied, the page model has no header and footer material. 70.6.4 Technique - Setting Up Headers and Footers. Headers and footers typically contain text that is dependent on document content (such as the technical order number and the chapter title). To specify text dependent on document content, use Usetext, making sure to specify Savetext on the appropriate element-in-context. Define appropriate usage rules on the Usetext to specify how variable information is to be controlled, including blank page logic when appropriate. 70.6.4.1 Positioning Techniques. The style and positioning of text placed in the header and footers is determined by the Subcharacteristics (subchar) specified for Puttext and Usetext and the Vertical Quadding (vquad) additionally specified within the header or footer itself. For simple cases, where the text is anticipated to be a single line, use the Quadding values "right", "left", "center", "in", -369- MIL-M-28001A APPENDIX B and "out" for horizontal positioning and the Vertical Quadding values of "top", "middle", and "bottom" for vertical positioning. This allows for nine positions relative to the Header or Footer Area. Note that "vquad" is an inclusion to the content model of the header and footer. This allows it to be placed anywhere within the header and footer specification. When it appears within a Subcharacteristic list, it applies to the text specified by the Puttext or Usetext that is the parent of the list. When it appears outside the Subcharacteristic list, it applies to the text specified by the preceding Puttext or Usetext. For more precise positioning and handling multiple-line text, form a "box" using Prespace Nominal to specify the distance from the top edge of the area, Postspace Nominal to specify the distance from the bottom edge of the area, Left Indent (leftind) to specify the distance from the left edge of the area, and Right Indent (rightind) to specify the distance from the right edge of the area. Quadding can then be used to specify how the lines are positioned within the box. 70.6.4.2 Using Security Values. Headers and Footers may contain various types of security classifications, which may vary depending on the content of the page or sheet. This text is identified within the headers and footers as Security Text (sectext). This text is special because it is automatically generated based on the specifications within the Security Description (secdesc). The Subcharacteristics specify the style and positioning of the resulting text in the same way as other header and footer text. The value of Scope provides input into how the computation for selecting the security text is made. 70.6.4.3 Using Page Numbers. To generate page numbers, set up a Usetext specification within the footer. Within its Subcharacteristic list, set up an Enumerate specification, assigning a page number id. Use this id as the Source of the Usetext. Specify style and positioning characteristics with the other Subcharacteristics. To restart page numbering, use the page number id in the Reset list of the Enumeration of the element causing page numbering to restart, for example, chapters. 70.6.5 Technique - Setting up Footnote Areas. In setting up the footnote area, choose whether the footnotes will appear at the bottom of each column or spanning the Flowing Text Area. Because the footnote area "grows upward", you can think of the "depth" as the "height". Specify the maximum amount of space that the footnotes can take up within the column and the fixed amount of space that should always appear between the text and the footnotes. Identify a rule separating the flowing text and footnotes by specifying its length and thickness. Specify whether footnotes can break across pages, and if so, specify what the rule and generated text look like (using subcharacteristics). -370- MIL-M-28001A APPENDIX B Specify whether footnotes stay "attached" to the footer or the flowing text when a floating figure or table appears at the bottom of the page. 70.6.6 Technique - Controlling Floating Elements. Table and figures can be thought of as "floating" elements because they may not appear in the resulting formatted document in exactly the same position as they occurred in the source document. In the source, tables and figures may have attributes specified for them that indicate they are "associated" with other source text. For example, a figure might be associated with a particular paragraph so that they can be kept together on the same page for nominal readability. With the Figure and Table Placement characteristics, you can set up the guidelines for how associated figures and tables are treated during composition. Note that mixing inline and floating figures can cause figures to appear out of order on the page. 70.7 Step 6 - Setting up the Style Description. After setting up the page models, you must consider how to specify formatting characteristics for every element that may appear in the document. One approach is to look at the formatting specification and determine the overall general requirements. These requirements can be specified for the document element, providing document-wide defaults. Then, you might look for common sets of requirements, specifying them as named environments, for example, for front, body, and back matter. Next, consider each element type and the requirements that must be specified for each that are different from the document or environment specifications. You must determine whether there are unique requirements for element types in specific contexts and specify elements-in-context for each. Finally, you must determine how attributes in the source affect formatting and further specify the characteristics to handle them. 70.8 Step 7 - Setting up the Document Default. The values specified for the document element supply the ultimate default values when characteristics are left unspecified, so you should exercise great care in selecting their values. For example, you may want to determine whether most elements begin on a new line or not. If you choose to turn Start Line (startln) on as the document default, be sure that you specifically turn it off for those elements that do not start on a new line. Or, you may choose to leave Start Line off and specifically turn it on for each relevant element. In general, choose defaults that will make the FOSI as brief as possible, yet allow an intuitive value to be specified for differing elements. 70.8.1 Technique - Setting up Hyphenation Rules. Hyphenation rules are set up for the document element and apply to the entire document. Use of hyphenation can then be enabled or disabled for any particular element-in-context. -371- MIL-M-28001A APPENDIX B 70.9 Step 8 - Setting up Environments. Environments are useful when some set of characteristics is common to many elements. Environments can be referred to by any element-in-context and then only the differing characteristics for that element-in-context need to be specified. You should exercise care in defining environments, using them only when they make the FOSI more brief and easier to comprehend. 70.10 Step 9 - Determining Element Categories. The first step in defining a specification for an element type is to determine its category. All elements described in the Style Description (styldesc) are placed in the Flowing Text Area in the order in which they occur in the source document. All elements to be treated as tables must be described in the Table Description (tabdesc) and those to be treated as graphics in the Graphics Description (grphdesc). Tables and graphics are also placed in the Flowing Text Area, but are subject to the Placement rules specified for the page model. All elements to be treated as footnotes must be described in the Footnote Description (ftndesc) and are placed in the Footnote Area. 70.11 Step 10 - Describing Elements. If document and environment defaults have already been established, describing elements is a matter of determining which characteristics differ from those defaults and thus need to be specified. 70.11.1 Technique - Grouping elements. When elements require the exact same set of characteristics and do not have unique contexts or attribute specifications, they can be grouped in a single FOSI entry. To group elements, specify their names in a list as the value for the "gi" of the element-in-context (e-i-c). 70.11.2 Technique - Using Context and Occurrence. In your analysis of the source DTD and formatting requirements, you may find the author of the source DTD has chosen to use a single element type to identify a piece of information but that element type may be used in many "contexts" throughout the document. For example, "title" identifies a title, but when used within a "chapter", it identifies a chapter title, and when used within a "section", it identifies a section title. You must determine when different formatting characteristics apply and specify an element-in-context for each. Be sure to analyze all levels of the document, especially areas where "structural" elements are optional. For example, a "chapter" may or may not have "section"s. Whether it actually does can have a profound impact on formatting, for example, numbering of paragraphs may be different. In these cases, you may need to specify many lower-level elements twice: once in the context of "section" and once in the context of "chapter" itself. -372- MIL-M-28001A APPENDIX B Also, look carefully at elements that can appear in many places. For example, "para" can appear in any level of subparagraph or step. You may need to adjust formatting characteristics for "para", such as indents, depending on which subparagraph or step it is in. 70.11.3 Technique - Using Inheritance and Defaulting. Inheritance and defaulting are the rules for determining the value of a characteristic when it is left unspecified for an element-in-context. For a discussion of these rules, refer to Section 20.3.3. The major consideration for choosing to use defaulting is brevity of the specification. Approaches to using defaulting have already been discussed in this section. In considering the use of inheritance, it is important to note that inheritance provides a dramatic reduction in the size of the specification for certain kinds of elements. For example, suppose the "tool" element has been defined to identify information about a tool within a paragraph for hypertext purposes. In printed documents, this information should appear exactly the same as the rest of the paragraph text. By inheriting the paragraph characteristics, you can ensure that the tool text appears the same as the rest of the paragraph text. You don't need to predict every possible context for "tool" (there are thousands) in order to get the correct results. Note that inheritance specifies that characteristics are picked up from those in effect for the parent at the point in the document where the element-in-context occurs. As the FOSI author, you can be aware of all the possible places an element-in-context can occur in a document by examining the source DTD, but the actual parent and characteristics in effect can be determined only by looking at the actual source document. In general, the goal of a FOSI is to describe all possible documents that could be created according to the source DTD, so inheritance provides very important relief from having to specify all possible contexts. 70.11.4 Technique - Determining the Font. There are two ways to specify the style of the font for text. Use Style to specify the general style of the font. Fonts styles are proportionally-spaced serif (serif), proportionally-spaced sans serif (sanserif), monospaced serif (monoser), and monospaced sans serif (monosans). In addition, you can specify the name of an actual font, for example, "Century Textbook", which the formatting system can optionally use to make the choice of the font to use. To specify characteristics of the font, use Posture, Weight, and Proportionate Width. To specify the "normal" font, use the values "upright", "medium", and "regular", respectively. To specify the size of the font, supply a value for Size, typically in points. How the formatting system actually chooses an actual font is up to the FOSI -373- MIL-M-28001A APPENDIX B implementation. While the specification describes fonts as a style modified by characteristics, it is common for font libraries to include different actual fonts for upright and italic versions, for example. 70.11.5 Technique - Specifying Leading. Leading is directly related to the font size. In this specification, leading is measured from text baseline to text baseline, so the value for Lead should be at least as large as the value for the Font Size, and is typically slightly larger. Certain special cases may employ "negative leading" where the leading is less than the font size. Always specify Leading when you specify a Font, as the inherited or defaulted value may not be appropriate. 70.11.6 Technique - Controlling Hyphenation. For each element-in- context, you can specify whether hyphenation should take place or not. If it should, the hyphenation characteristics specified in the document description apply. The only characteristic that can be overriden is the Hyphenation Zone. You may want to disable hyphenation in text in large type, for example, chapter headings, or in table cells. 70.11.7 Technique - Specifying Word Spacing, Letter Spacing, and Kerning. Word spacing, letter spacing, and kerning are generally set up for the document element and are rarely changed for a particular element. Typically, word and letter spacing values are specified with "em spaces". The actual size of an em space is determined by the font in use. This allows word and letter spacing to vary with the font in use. Specifying different values for Minimum, Nominal, and Maximum gives the formatter freedom to adjust letters and words during justification. Choose values that allow enough latitude yet render the text readable. 70.11.8 Technique - Using Indents. Indents establish "margins" against which text can be positioned. You can specify the indents relative to the column area boundaries, or you may find it convenient to specify indents relative to the text margins of the parent, for example, in the case of nested paragraphs. One typical use of indents is for "hanging" indents for lists and steps, where the first line contains a number, for example, to be "outdented" and the rest of the text appears as a block. To achieve this effect, specify the left margin for the block of text as a Left Indent (leftind) value on the element-in-context. Specify the left margin for the number as a subcharacteristic (subchar) to the Usetext used for outputting the number. -374- MIL-M-28001A APPENDIX B 70.11.9 Technique - Specifying Quadding. The Quadding values of "left", "right", "center", and "justify" represent typical typographic positioning techniques. The values "in" and "out" work exactly the same as "left" and "right" but leave the actual determination of which side to the formatter based on the bind edge. "In" and "out" are most commonly used in headers and footers. "Asis" instructs the formatter to try to put the same characters found on lines in the source (including spaces) on the same lines in the output. Typically, this is used when including computer program listings, example terminal screens, pseudo-graphics drawn with characters, and the like. This data is usually originally produced with a monospace device, so it is best to specify a monospace font in conjunction with "asis" quadding. 70.11.10 Technique - Using Highlighting. Scoring, Score Weight (scorewt), and Score Offset (scoreoff) are used for underlining, overbars, and strike-throughs. Additionally, a Score Character (scorechr) can be overlaid to achieve a "crossed out" effect, for example, with an "x". Reverse, Color, and Screens are used for special effects. 70.11.11 Technique - Specifying Change Marks. You can specify that either a bar or literal string appears in the Change Mark Area to denote changed text. Specify a bar by indicating a Bar Thickness. Specify a literal by providing the string to appear, for example "rev1". Font and Highlight characteristics can be specified for the string; the leading is determined by the leading of the text the change mark corresponds to. Positioning of bars or literals within the Change Mark area can be controlled with Indent and Quadding. 70.11.12 Technique - Specifying Prespace and Postspace. Prespace and Postspace specify the space before and after an element, respectively, and as such will abut each other. Some planning ahead for prespace and postspace values will ensure that your FOSI really reflects your formatting requirements. In general, first specify pre- and postspace where your formatting requirements absolutely require it and place an Adjacency Priority of "force" with them. Then, analyze the general requirements for spacing between elements and try to specify the space as all prespace or all postspace. In this way, you will avoid conflicts. When you can't specify the spacing all one way, use priorities that will allow the formatter to make intelligent choices about how to distribute the space. Specifying different values for Minimum, Nominal, and Maximum gives the formatter freedom to adjust pre- and postspace during vertical justification. Choose values that allow enough latitude yet keep within the bounds of your formatting specification. -375- MIL-M-28001A APPENDIX B 70.11.13 Technique - Specifying Keeps. Keeps should be used with discretion because it is very easy to specify unrealistic expectations for the formatter. For example, turning on Keep for a chapter indicates to keep the entire chapter on a single page, which is hard to predict when you don't know the content of the document. Turn on Keep for only those elements that are you are sure fit on a single page. Note that tables and footnotes have special characteristics for controlling breaking across pages and graphics are inherently kept on a single page. A more common formatting requirement is to keep some pieces of adjoining elements together on a page, for example, to keep a title with the first two lines of the following paragraph. This type of requirement can be specified with Keep Next, Keep Previous, Widow Count, and Orphan Count. Set the Scope to indicate whether you are interested in breaking across columns or pages. 70.11.14 Technique - Specifying Vertical Justification Parameters. In general, a formatter should attempt to honor all specifications for an element's Prespace, Postspace, and Keeps. However, in performing vertical justification, the formatter may need to make some adjustments in order to balance the text in the columns. You can indicate for each element-in-context which values are most important by setting a Vertical Justification Priority on each. If you do not think such individual attention is necessary, you may choose to set these priorities for the document element and they will become the default for all elements-in-context. 70.11.15 Technique - Specifying Text Breaks. A formatting specification typically explicitly states requirements for starting text on new columns or pages, for example, starting chapters on a new page. This can be specified with Start Column and Start Page. In addition, you can specify the Page Model to be used when starting on a new page, for example, foldout pages. The OS makes no assumptions about whether elements start on a new line or not. You must explicitly specify this for each element that starts on a new line. If you determine that most elements start on a new line, you may choose to turn on Start Line as the document default and explicitly turn it off for those elements that do not start on a new line. Turning on End Line is useful for situations where you cannot predict what element will follow, but you know that it must begin on a new line. For example, the paragraph following the title in a primary paragraph is usually run-in, that is, it does not start on a new line. However, if a warning intercedes between the title and the paragraph, the paragraph must start on a new line (or else it would be run-in with the warning). The way to specify this is to turn on End Line for the warning. -376- MIL-M-28001A APPENDIX B 70.11.16 Technique - Using Spans. Span is used to specify that text normally placed within a single column in the Flowing Text Area should span all the columns. Note that tables, footnotes, and graphics have special characteristics for specifying their width. 70.11.17 Technique - Using Borders. Borders that always appear on a particular type of page model should be specified on the page model. In addition, the occurrence of certain elements on a page may trigger the appearance of a border, for example, emergency information. Border patterns are specified with a name, which is described in the declaration subset of the FOSI. It is up to the FOSI implementation to determine the actual means for producing the border on the page. 70.11.18 Technique - Using Rules. Rules are used for two purposes: as "inline" rules within paragraph text, for example, a signature line, and to "outline" blocks of text, for example, around a heading. Multiple rules can be specified on a single element-in-context; each specification draws one rule. 70.11.19 Technique - Using Character Fills. The most common use of Character Fill is for leader dots. Use the Character Fill characteristics to set up how the fill string looks and assign the string a unique name. To specify where the string appears in the output, use the unique name in the Source of a Usetext specification. 70.11.20 Technique - Using Automatic Numbering. Automatic numbering is typically specified for structural elements such as chapters, sections, paragraphs, and steps, as well as tables, figures, and footnotes. In a FOSI, you can set up "counters" for each element-in- context such that the actual value is maintained by the formatter. You can specify how these counters are incremented and which counters are reset when another counter is incremented, for example, to reset the paragraph counter when the section counter is incremented. Additional characteristics can be specified to control the style of the number when it is printed. You can chose a known numbering sequence, such as Arabic, or set up an ordered sequence of your own. An example is using daggers, double daggers, and so forth, for footnotes. Counters are assigned a unique identifier that can be referenced so that compound numbers can be created, for example, the paragraph number might include the chapter number. The Enumeration characteristics only set up how the counter is to be handled when the element-in-context it is associated with is encountered. To specify where the number appears in the output, the unique identifier must be included in the Source of a Usetext specification. Alternatively, the counter may have already been specified as part of the data in the Construction Rule of a Savetext specification and use of the Savetext identifier as the Source of the Usetext then includes the counter. -377- MIL-M-28001A APPENDIX B 70.11.21 Technique - Suppressing Text. Occasionally, text is marked up in the source document that is intended to be used for some purpose other than in the normal text flow. For example, a short title is provided for use in the Table of Contents or running header but does not appear as part of the title. In this case, you must indicate that the content of the short title does not appear in the normal text flow by turning on the Suppress characteristic. The entire content of the title, including any marked-up elements within it (such as emphasis), should not appear in the normal text flow. Typically, you will also want to save the text with a Savetext so that it can be used elsewhere. 70.11.22 Technique - Using Generated Text (Puttext). Often, the formatting specification requires the generation of a standard piece of text with each occurrence of an element, for example, the "Note" heading for a note. This text does not appear in the source document itself, and by specifying it in the FOSI, you can ensure that it is consistent throughout the document. Puttext allows you to specify a text string that is to appear before or after the element's content. You can then use Subcharacteristics to describe the style and positioning of the text string. 70.11.23 Technique - Using Pre-Defined Graphics (Putgraph). There are cases where graphics appear in the document that are not part of figures, such as the HCP symbol. Putgraph allows you to identify these graphics and specify how they appear in running text. In addition, you may chose to use Putgraph for some kinds of generated "text" instead of Puttext, for example, warning heads in 3-D boxes. These graphics are to be treated as a single "character" for positioning by the formatter. You must specify the width and depth of the graphic, as the formatter does not have font metric information available to use to position the graphic. 70.11.24 Technique - Saving Text for Multiple Uses (Savetext). Savetext allows you to "save" the content of an element for use elsewhere in the document, for example in the header, footer, or Table of Contents. The content also still appears in the Flowing Text Area in its normal sequence. Savetext can also be used to save combinations of other saved text, saved counters, and literals. Usetext is used to "retrieve" the saved text and specify how it is used. Although the specification implies a methodology, it is up to the FOSI implementation to determine how to handle Savetext and Usetext. 70.11.25 Technique - Using Saved Text (Usetext). Usetext is used to specify how any text saved via Savetext is used. Subcharacteristics can be used to specify the style and positioning of the retrieved text. The Usage Rule specifies any additional information needed to process the text, for example, the order of the information in the Table of Contents. -378- MIL-M-28001A APPENDIX B 70.11.26 Technique - Interaction of Puttext, Putgraph, and Usetext. When more than one Puttext, Putgraph, and/or Usetext is specified on an element-in-context, the order of their occurrence in the FOSI is significant. That is, the text or graphics should appear in the same order in the output as they did in the FOSI. 70.12 Step 11 - Handling Source Attributes. 70.12.1 Technique - Identifying Source Attributes. Source attributes that affect formatting must be identified in the FOSI with each element-in-context for which that attribute can be specified. An attribute is identified through the Attname. The value should be the name of the attribute, exactly as it appears in the source DTD. In addition, you can refer to attributes that were specified for ancestors of the element-in-context through the Attloc. The value of Attloc should be the name of an ancestor of the element-in-context and is assumed to be the most immediate ancestor of that element type. For example, when specifying the characteristics for a section title (gi = "title", context = "section"), you may need to know whether the "tocentry" attribute was set on the section in order to determine whether to save the contents of the title for use in the Table of Contents. To specify this in the "att" section of the FOSI entry for the title, specify a value of "tocentry" for Attname and "section" for Attloc. When no value is supplied for Attloc, the attribute is assumed to have been specified for the element-in-context being described. 70.12.2 Technique - Specifying the use of the Attribute. There are two ways of specifying how an attribute value is to be used: Specval and Fillval. For Specval, one possible value of the attribute is identified through Attval. When that value actually appears in the source document for the element-in-context, the characteristics specified in the Characteristic List for the Specval take affect. The string "#NONZERO" can be used to indicate any non-zero value, and the string "#ANY" indicates any value. In addition, the string "#ITEM#" is used to indicate the value is one out of a list. You will then have multiple Specvals with the same Attname, with each possible value in the list as an Attval. The characteristics specified for these list items are cumulative, that is, for all the values that actually occur in the list, all the corresponding characteristics take effect. For example, the declared value for the "emph" attribute on the "emphasis" element is NAMES (a list of names). For each possible value, for example, "bold", "italic", and "underline", you must provide a Specval with a list of characteristics for each. Then, when the actual attribute value is "bold underline", the characteristics specified for "bold" and "underline" take effect. -379- MIL-M-28001A APPENDIX B For Fillval, the value of the attribute is actually used as the value for a characteristic identified by its category (Fillcat) and characteristic name (Fillchar). The Fillcat and Fillchar values must be names of elements defined in the OS DTD. Use the Fillist to specify the values of the other characteristics of the category used in the Fillcat. Fillval is useful when the value for a characteristic is determined by the author of the source document as opposed to the author of the FOSI, for example, the number of columns in a table. 70.12.3 Technique - Interaction of attributes and other values. In general, you can set up the characteristics for an element without regard to the possible attributes that may affect it. Then, in the attribute specification (att) you can override the "typical" values through the characteristics specified in the characteristic lists (charlist) specified for the attributes. In some cases, the value of an attribute is so integral to the nature of the element that you may not be able to set up "typical" characteristics without considering the attribute values. In this case, there is no need to set up characteristics outside of the attribute specification. For a further discussion of attribute specifications, refer to Section 40.2.2. 70.13 Step 12 - Describing Graphics. 70.13.1 Overview of Graphics Functionality The graphics functionality has been designed to ensure that a formatting system is able to reproduce an illustration according to the specifications of the author/illustrator in such a way that it fits in with the design specifications of a FOSI. In particular it allows for: 1. The author to pass relevant sizing, cropping and placement information. 2. The author to specify exactly which portion of graphic board is to be used for the illustration, such that a "window" view of a graphic can be used. 3. The author to easily specify a particular set of values to be used by supplying a "Graphic Style" name. 70.13.2 Methodology While the actual graphics used in an illustration are typically unique, it is often the case that functional specifications allow for a small set of different size illustrations. For example only page width or column width illustrations may be allowed and may have specific width dimensions specified for each. There may also be a requirement that a particular set of graphics be placed in a document in a uniform way, for example, with 1/4 inch white space surrounding each graphic. Both to accommodate these possible requirements and to ease the job of the author, it is possible to specify different sets of graphic characteristic values and provide a name for each set of these -380- MIL-M-28001A APPENDIX B "Graphic Styles". There is one required Graphic Style in every FOSI which has the name "default". This default set of characteristic values serves the same purpose that the default Table Style serves; it allows the author to leave out attribute values that are supplied in the FOSI, and also allows for additional Graphic Styles to be specified easily in a FOSI. The first step in coming up with useful values for the graphic characteristics in a FOSI is to review the functional requirements. Are there different types of graphic reproduction areas (the area on the media or page within which the graphic may be placed)? Are they compatible with the Page Models you have specified in your FOSI? If all graphics used will be the width of a page, then it is obvious that the reproduction area dimensions for the default Graphic Style should be based on the width of a page. If there are two types of graphics, one page width and one column width, then whichever is more common should have its values specified in the default Graphic Style and a second Graphic Style should provide the other values. As is always the case where an author can specify attribute values that affect formatting, the authors values override the FOSI characteristics. This allows for authors to make an exception where necessary but also frees them from having to specify many attributes when they are already provided in the FOSI. 70.13.3 Example Since the default Graphic Style for the FOSI in Section 50 is short, it is reproduced here for reference. Below is: 1. The default Graphic Style from Appendix B. 2. A sample Graphic Style that is based on the defaults. 3. Two versions of source input that are equally valid. 4. An illustration based on the source and the FOSI styles. -381- MIL-M-28001A APPENDIX B This is the default graphics FOSI: fillcat="repro" fillchar="reprowid"> attname="reprodep" fillcat="repro" fillchar="reprodep"> fillchar="hscale"> scalefit = "0" llcordra = "0,0" attname="scalefit" fillcat="sizing" Characteristics-- hplace = "center" rotation = "0" tiplace = "above" attname="urcordra" fillcat="sizing" fillchar="urcordra"> fillcat="placement" fillchar="hplace"> attname="vplace" fillcat="placement" attname="graphsty" fillcat="grphstyl" attname="coordst" -382- MIL-M-28001A APPENDIX B fillcat="placement" fillchar="coordst"> -383- MIL-M-28001A APPENDIX B Here is the minimum source necessary assuming default values are valid for the particular graphic.: Here is the source required for the following illustration: Here is the illustration: -384- MIL-M-28001A APPENDIX B 70.14 Step 13 - Describing Tables. In the Table Description of a FOSI, you must identify all elements in the source DTD relating to tables and map them to their corresponding object in the table output structure. In addition, you specify the composition characteristics for the content of the table. Following is one approach for describing tables. 1. Set up the Table characteristics (tabatts) for each basic kind of table you have, for example, in-line and floating, ruled and unruled, and different page breaking requirements. You may also set up the Standard Cell Attributes (stdcellatts) here as the "default" settings for the whole table. 2. Put each tabatts in a tabstyle and assign the tabstyleid a unique name that indicates what kind of table it is, for example, "floatruled". Provide the table element-in-context from the source for each tabstyle. You may use the same element-in-context for more than one tabstyle, for example "table"; the unique tabstyleid distinguishes tabstyles. 3. In the e-i-c of the tabstyle, you also specify how the table is positioned within the flowing text using Quadding, Indents, Prespace, Postspace, Keeps, and Textbrk. Note that Span does not override the width specified for the table. Other characteristics for generating data, such as rules, borders, text, and graphics may also be used to put additional data in the flowing text. Style characteristics for text, such as Font, Leading, Hyphen, Wordsp, Lettersp, and Highlt have no immediate effect on the table but can be set up so that they can be inherited by another element-in-context. 4. Next, set up a subsetstyle for each unique type of table subset. Again, provide a unique name for the subsetstyleid to distinguish it from others. In general, for every characteristic that can be overriden by an attribute in the source, you should provide a Fillval construct, but you also need to provide values in the FOSI for cases where the values are not provided in the source. Stdcellatts can be specified for any object in the table subset and apply to the cells within that object. 5. For the elements-in-context supplied in the subsetspec, colspec, rowspec, and cellspec, Composition Characteristics (a charlist) can be supplied and apply to the text within the cells that are in the scope of the object. -385- MIL-M-28001A APPENDIX B 6. In the subsetatts, the number of columns for the table is specified. In the DTD in Appendix A, the number of columns in the table is a required attribute, so a Fillval construct is sufficient. Provide the table group element-in-context from the source for each subsetspec. Again, you may use the same element-in-context for more than one subsetspec, for example "tgroup"; the unique subsetstyleid distinguishes them. 7. Set up a colspec for the columns in the table. Typically, as in the case of the DTD in Appendix A, all colatts are supplied from the source, so they should all have a Fillval construct. In cases where columns are uniquely identified in the source structure by different elements, you may need to set up a colspec for each. Provide the column element-in-context from the source for each colspec. 8. Set up a rowspec for the rows in the table. Again, one rowspec is sufficient unless there are unique row elements in the source table structure. Provide the row element-in-context from the source for each rowspec. 9. Set up a cellspec for the cells in the table. Typically, cellatts are supplied from the source, so they should all have a Fillval construct. Provide the cell element-in-context from the source for each cellspec. 10. You must also consider all elements that can occur in a table as content, as it is likely that they are formatted differently than in normal flowing text. Include an element-in-context for each of these elements in the Table Description with the Composition Characteristics that apply within the table. 70.15 Step 14 - Describing Footnotes. Footnotes are simply identified in the Footnote Description so that they will appear in the Footnote Area instead of the Column Area. You can specify the same style and positioning characteristics to footnote areas that can be specified for other elements in the Style Description, except for Keeps and Span. These characteristics are specified on the Footnote Area. Typically, footnotes have an automatic number specified. 70.16 Step 15 - Verifying the FOSI. When you have finished encoding the specifications for the entire document, you will need to verify that the encoding conforms to the OS DTD by running an SGML parser. The parser confirms that the SGML syntax is correct and, in the case where characteristic values are a Finite List, can verify that correct values have be specified. The SGML parser cannot verify that other values make sense. It it the FOSI author's responsibility to ensure that the FOSI accurately reflects the formatting specification and that all required values have been specified. -386-