First Steps in Structure: an Overview Many Experienced Framemaker Users May Have Never Used Structured Documents

Tools 9 First steps in structure: an overview Many experienced FrameMaker users may have never used structured documents. Steve Rickaby attempts a beginner’s guide. This article and its successors are intended document structure. SGML and HTML are well- to provide an easy introduction to structured known examples of languages for describing working in FrameMaker for readers who have document structure (although SGML is, strictly not used structured documents before. speaking, a metalanguage). FrameMaker users who have upgraded beyond FrameMaker users are familiar with the use Version 6 will have noticed that it now supports of paragraph and character tags to define and both unstructured and structured working. control the appearance of text objects. There is a A version of FrameMaker that supported one-to-one correspondence between a paragraph structured documentation has in fact been or a character sequence and the tag applied to available since FrameBuilder, which was an it. For example, a chapter document may have a alternative to FrameMaker 3.0 in the early 1990s. chapter title, sections with headings to which a With its acquisition of FrameMaker in 1995, Heading tag is applied, body paragraphs to which Adobe introduced a separate FrameMaker+SGML a Body tag is applied, list paragraphs to which a product. FrameMaker 7.0 saw the fusion of Bulleted tag has been applied, and so on. ‘plain’ FrameMaker and FrameMaker+SGML into However, beyond its physical placement, one application. there is no concept of the heading to which Here we will introduce the idea of structured a specific body paragraph ‘belongs’. Equally, working and describe some of its advantages, there is nothing to stop an author following one while later articles will delve into the mechanics Heading with another: the only indication of the of setting up a simple structure definition. document’s structure is the physical placement of its component objects. Enter structured documents: in a structured Chapter title Chapter document, a separate syntax describes the document’s structure independently of its Heading presentation. For the simple example above, Chapter title a sequence of heading and body paragraphs Body might be wrapped in a Section, and sections in a Section Chapter. Bulleted FrameMaker uses the term element to describe Section title the objects that represent structure. It’s helpful to Bulleted think of elements as a separate level of document organisation from the language of tags, table Without structure — Body styles, markers and so on that you already know just a sequence of paragraphs (although these still work as before). This separate Bulleted list level of organisation is hierarchical: sections contain a title and body paragraphs, and are themselves contained in chapters — or whatever List para document structure suits your purpose. Figure 1 illustrates this: in the structured List para version, the section title, body and list elements With structure — elements ‘know’ that they are part of a section. We’ll see how this is achieved later. When thinking about elements, it’s helpful Figure 1. Chaos and order: applying a simple structure to remember that an element may exist only to contain other elements, as with Section in Figure 1. Others, such as Body elements, clearly What is a structured document? must contain text. There is no default relation- Every document possesses structure: it is ship between elements and paragraph tags. obvious that a book, for example, contains The extra level of organisation provided by chapters made up of sections, paragraphs, elements can be used by FrameMaker to apply lists and so on. A structured document is one rules, to: that adds some form of notation to provide a . Control the document’s structure by restricting description of its organisation that is separate the elements allowed in a specific context. from the document’s presentation. A suitable . Apply formatting to text objects automatically notation in this context is one that can be used based on their context, relieving authors from this to define a concrete language that describes task and allowing them to concentrate on writing. Communicator Spring 2007 0 Tools Why should I use structured documents? How structure is defined The introduction of a structural description of Until now we’ve purposely referred only to the documents brings many advantages: ‘structure definition’ for a document, without . A much greater level of automation becomes describing how it is achieved. FrameMaker possible, such as the context-dependent uses an element definition document (EDD) to application of formatting mentioned above. hold the structure definition for a document . A document’s structure can be validated, that or family of documents. An EDD contains the is, checked against the structure definition element definitions, and is itself a structured and any errors and omissions flagged. FrameMaker document. The language required . Structure enables design devices that would to define elements and their rules in an EDD is be tedious and error-prone to apply in built into FrameMaker itself. unstructured FrameMaker to be wrapped in Just as you can import the unstructured elements and used much more easily. aspects of a document — paragraph and . The ability to interact with documents at a character tags, page layouts, table definition, structural level makes edits to the structure variables and so on — from one FrameMaker easier and less error-prone, as well as making document to another, so you can import element objects such as markers much easier to select. definitions between an EDD and a FrameMaker . Formatting rules within the structure document, and between FrameMaker documents. definition enable document content to be Importing element definitions into a structured reformatted in response to structural changes, FrameMaker document reapplies the structural for example changing one element into definitions to the document, and you can another with a single command and having all opt to remove local formatting overrides, child elements reformat automatically. enforcing the formatting defined by the EDD. Meaning can be introduced into document However, importing element definitions into an structures. For example, the documentation unstructured FrameMaker document sadly does of a software programming interface might not magically apply structure — we’ll see how include name, interface definition, parameter that can be achieved in a future article. definition list, usage and error messages for each procedure call. Such elements can be given descriptive names in the structure definition, and completeness can be checked and enforced. Show the element catalog . Locally applied formatting can be removed Enter attributes by reapplying the structure definition to a document. Show the structure view . Document contents can be repurposed much more easily. Extra information about parts of a document can be introduced through the use of attributes, data fields that ‘belong’ to elements but which do not appear in the document itself. Inter-working with document tagging formats such as SGML and XML becomes possible. As with everything, there is a downside. Setting up a Figure 2. Extra icons in the document view structured writing environment carries a reasonably high overhead, which includes getting to grips with structure definitions, analysing your documents, There is a strong correspondence between defining and testing the required structures, and FrameMaker’s EDD and the document type becoming familiar with the parts of FrameMaker’s definition document (DTD) used in SGML — indeed, user interface concerned with structure. Acquiring FrameMaker can create a DTD from an EDD and deep proficiency with these, as with unstructured vice versa. The significant difference is that while FrameMaker, make take years. However, the a DTD defines only structure, an EDD can also message behind these articles is that making a include additional rules to control formatting start is not as difficult as you might think — and and other issues in the target document. not as difficult as it’s sometimes made out to be. By now, readers who are familiar with Word’s Structured documents in FrameMaker Outline view may be wondering what all the fuss When you first start FrameMaker Version is about. However, Outline view only understands 7.x, it asks you whether you want to work in Word’s predefined heading styles and body structured or unstructured mode. If you choose text. In structured FrameMaker, by contrast, unstructured, structure commands are excluded every object within a document is controlled by from FrameMaker’s menus. In fact there’s little the structure definition, and that definition is point to this, as it’s perfectly possible to work completely under the documenter’s control. with unstructured documents in structured Communicator Spring 2007 1 Missing element Invalid structure Figure 4. Defects in structure Figure 3. Structure view of a simple imaginary document FrameMaker and just ignore the structure document, the structure shows a red square. features. (The converse is not true.) Equally, if the existence or location of an The most significant thing you notice when element makes the document’s structure invalid first invoking the structured interface is that with respect to the EDD, the structure shows a the top right of the document view sprouts a dotted red line. Figure 4 illustrates these. few extra icons, as Figure 2 shows. Of these, the most interesting at this stage is the icon to Future articles display the structure view. The next article in this series will look at working with structured documents more The structure view closely, at the advantages and disadvantages of FrameMaker’s structure view, which is independent using off-the-shelf EDDs, and will describe the of the document view, shows a document in terms construction of a simple EDD. Later articles will of its elements and their relationships. go into more detail about element definitions, Figure 3 shows an imaginary example. Here a rules and how they are used.

Load more