diff --git a/en/defguide5/src/ch06.xml b/en/defguide5/src/ch06.xml index 074f51b3a..daa5fe960 100644 --- a/en/defguide5/src/ch06.xml +++ b/en/defguide5/src/ch06.xml @@ -225,14 +225,14 @@ DocBook assemblies should be able to handle both the richness of the structures that we produce today as well as the structures we will want to produce tomorrow. -The principle task of the structure element is to +The principal task of the structure element is to identify the resources that are to be combined for that structure. The resulting structure may be delivered in any number of ways: as a single document, help system, or web site, for example. It is important to observe that the realized structure is often, but not necessarily, a valid DocBook document. What is important is -not it's validity from an authoring perspective, but rather it's +not its validity from an authoring perspective, but rather its validity with respect to what the downstream processor is expecting. @@ -240,7 +240,7 @@ expecting. realized structure should be a valid book. If, on the other hand, what is defined is a help system, then the realized structure may be a collection of nested topic elements. Even though authors -are not allowed to nest topics (per the currently proposed topic +are not allowed to nest topics (per the DocBook 5.1 topic element), the assembly process may be allowed to nest them. A structure consists mostly of module elements. @@ -556,14 +556,16 @@ database).
Setting Up the Structure -The First few lines of the structure set up general things about +The first few lines of the structure set up general things about the help system: Defining the Basics of the Help System - XIDI Build System Help - XIDI Help + + XIDI Build System Help + XIDI Help + @@ -869,17 +871,20 @@ transformation is necessary later.) We can address the problem of missing metadata by creating a new resource that contains an info element containing -the appropriate metadata and then pointing to it. But this case is so common, -that we simply allow the info element to be placed in the +the appropriate metadata and then pointing to it. Alternatively, you +can supply a merge element containing metadata for the +structure. The merge element has the same content +model as info. Metadata elements that you include in the +merge element are applied to the output element for the structure. With these amendments, here's our new structure: - + Widget User Guide - + @@ -940,9 +945,9 @@ subordinate modules in a new top-level module: - + Widget User Guide - + @@ -951,9 +956,9 @@ subordinate modules in a new top-level module: - + Troubleshooting - + @@ -1032,7 +1037,7 @@ that we want: If a module “A” is nested within a module “B” that refers to a resource, the result of processing “A” is inserted into “B” as the last -child of “B”. (in the case of several nested modules, they are inserted +child of “B”. (In the case of several nested modules, they are inserted as the last children in the order specified.) After further review of the content, the subject matter expert decides @@ -1116,9 +1121,9 @@ semantics we've already encountered: - + Troubleshooting spindle and bearing problems - + @@ -1129,24 +1134,26 @@ semantics we've already encountered: The only disadvantage of this approach is that we lose all of the metadata associated with tutorials 3 and 5. This might include publication -dates, copyright information, etc. We could add those fields to the info +dates, copyright information, etc. We could add those fields to the merge wrapper for the appendix in the assembly, but then it may have to be maintained in two places. Instead, we introduce one more convention: if a module -refers to another resource and contains an info -element, then the elements within that info replace any elements -of the same name in the referenced resource's metadata. (If the referenced -resource has no metadata, then the specified info becomes the -first child of the referenced resource.) +refers to another resource and contains a +merge element, then the elements within that +merge replace any elements of the same name in the +referenced resource's metadata. (If the referenced resource has no +metadata, then the specified merge becomes an +info and is inserted as the first child of the referenced +resource.) The second approach uses this convention: - + Troubleshooting spindle and bearing problems - + @@ -1180,9 +1187,9 @@ guide in one place. - + Widget User Guide - + @@ -1191,9 +1198,9 @@ guide in one place. - + Troubleshooting spindle and bearing problems - + @@ -1226,9 +1233,9 @@ elements: - + Widget User Guide - + @@ -1239,9 +1246,9 @@ elements: - + Troubleshooting spindle and bearing problems - + @@ -1286,9 +1293,9 @@ apply only to that module. - + Widget User Guide - + @@ -1302,9 +1309,9 @@ apply only to that module. - + Troubleshooting spindle and bearing problems - + @@ -1338,16 +1345,16 @@ a plausible structure for our online reference. - + Widget Reference - + - + Troubleshooting spindle and bearing problems - + @@ -1359,7 +1366,7 @@ a plausible structure for our online reference. The resulting realized structure will be a nested set of topic elements. Topics don't nest in DocBook (at least -under the current proposal), so this isn't a valid DocBook document. +in DocBook 5.1), so this isn't a valid DocBook document. However, the nested topics provide a navigational structure for the online presentation. The rendering system is, we assume, smart enough to render each of the topics separately, as if they were all top-level