To facilitate bringing closure to the DocBook assembly proposal, I thought it would be useful to complete the history of its development. Below are excerpts from the meeting minutes regarding our discussions and decisions on the topic of modular DocBook and assembly. We have been at this for three years! Bob Summary of DocBook TC meeting minutes regarding DocBook assembly. ------------------------------------------------------------------ ============================================================= DocBook Technical Committee Meeting Minutes: 21 January 2009 ============================================================= 10. Using a map for modular DocBook. Scott described an initial proposal that several participants developed. The Committee asked several questions and agreed to further discussions. ACTION: Scott to write up a modular DocBook proposal for the TC to discuss. ============================================================= DocBook Technical Committee Meeting Minutes: 15 February 2009 ============================================================= Meeting cancelled. ============================================================= DocBook Technical Committee Meeting Minutes: 25 March 2009 ============================================================= 10. Using a map for modular DocBook (Dick and Jim). Scott sent out the discussion group's proposal [2]. [2]
http://lists.oasis-open.org/archives/docbook-tc/200903/msg00004.html It proposes a new <assembly> element to map DocBook elements into a publication. It would use a <toc> element to define order and hierarchy, a <resources> element to declare potential resources to be used, and a <relationships> element to define relationships between resources. The assembly is similar to IMF manifest for SCORM, making it useful for eLearning applications. Most TC comments described the proposal in favorable terms. Discussion of what scheme to use for relationships: existing comprehensive standard such as RDF, or simpler new scheme? Different groups need more than others. Suggested shipping it with a simple scheme, with provisions and instructions for binding in a more comprehensive system. ACTION: Larry to work up an complete assembly example with basic relationships. ============================================================= DocBook Technical Committee Meeting Minutes: 15 April 2009 ============================================================= 10. Using a map for modular DocBook. Continued. ============================================================= DocBook Technical Committee Meeting Minutes: 20 May 2009 ============================================================= f. Larry to work up an complete assembly example with basic relationships. COMPLETED 8. Using a map for modular DocBook. Larry posted something just a couple of hours ago.[2] [2]
http://lists.oasis-open.org/archives/docbook-tc/200905/msg00006.html Larry: Biggest concern is that I couldn't actually use the <toc> element to do the structure of a help system. Norm: What would need to be change? Larry: I need nested <tocentry> elements. This is to describe the structure of a help system which has a hierarchy but no real table of contents. ... The idea of a hierarchy in document assembly is quite common, but it doesn't always map to a table of contents. Perhaps it would be appropriate to introduce a generic hierarchy mechanism in the assembly grammar. ... This would allow references to be nested more freely than in a <toc>. I'm also abusing @rendras. Norm: I think inventing a new element is fine. I'm not sure about @renderas. Larry: I think it does make sense to allow <toc> in the assembly grammar. Nancy: We created <toc> with a book in mind, so it's not surprising that it doesn't have the exactly correct semantics. Scott: Would we need to extend <tocentry> for other things. Larry: I wasn't able to figure out how to point to content with a tocdiv. Norm: Let's try to push this forward in email if we can, otherwise revisit next month. Gershon: I got comments at CMS/DITA saying this would be really valuable. I was asked if we could use the same names as DITA maps. Nancy: That's difficult because the DITA names are all referential to the DITA topic element. My guess is that people who are using DocBook are using section or some such instead. So, we would be better off basing it on section. OTOH, there's nothing to keep us thinking about this. Scott: We're trying to extend beyond DITA maps. Gershon: Many people said they're investigating DITA for maps. Norm: I think we should figure out how to do maps for DocBook content. After we've worked out the semantics, we should consider if there are names that would make sense to keep the same. ============================================================= DocBook Technical Committee Meeting Minutes: 17 June 2009 ============================================================= Meeting cancelled. ============================================================= DocBook Technical Committee Meeting Minutes: 15 July 2009 ============================================================= 9. Using a map for modular DocBook. Discussion of Larry's second sample of DocBook assembly.[2] [2]
http://lists.oasis-open.org/archives/docbook-tc/200907/msg00003.html Norm raised concerns about the renderas attribute as well as importing foreign content such as DITA or other schemas. That implies some transformation process, and will the committee specify that? Gershon: DITA uses specializations of topicref in the bookmap schema to indicate how a topic is to be represented. He also pointed out that in DITA maps, topicref can only refer to a topic element. In DocBook assembly, any DocBook element can be included, and the renderas attribute allows the author to indicate how it would be represented. Larry: for foreign content, perhaps have a section in the assembly that identifies a stylesheet to be used for transforming content during the assembly. Bob: we should separate including DocBook content (easy) from including foreign content (harder). Norm: transformations are defined by the implementation. We may provide some reference implementations. Larry: assembling a help system requires different processing from assembling a book. Norm: put an "outputtype" attribute on the structure element as a whole to indicate how it should be processed overall, and use renderas at the element level to map one element to another. Bob: One assembly mode is to map all referenced elements into a valid DocBook book, so nested topics would become sections, for example. Another assembly mode creates a structured TOC and processes each reference separately (similar to the DocBook Website customization), without assembling it into a book first. Larry: may use an attribute on elements to indicate chunking level. ACTION: Larry to create a new assembly example for next meeting. ============================================================= DocBook Technical Committee Meeting Minutes: 19 August 2009 ============================================================= f. Larry to create a new assembly example for next meeting. COMPLETED 9. Using a map for modular DocBook. Larry presented the new features of the latest sample for assembling modular content [3]. [3]
http://lists.oasis-open.org/archives/docbook-tc/200908/msg00002.html He uses type attributes (text) rather than class (enumerated) because it needs to be application specific. The renderas attribute should default to "auto", so that it is used only to change the element from its original name. The grammartransforms element was added, e.g. for converting DITA input to DocBook before assembly. A navtitle element was added to module for a navigational title that is used when the resource in assembled. Norm suggested that the output attributes become elements instead. Larry will add those. Bob asked if resource elements nest. The answer is no, they are a flat list, and all nested structure comes in the structure element whose module elements reference resource elements. Larry asked if an info element should be added to module. Some discussion of how module and resource info information should be merged. No big interest in including info in module just yet. Bob asked how introductory blocks of text that appear between a chapter title and the first section would be handled. Larry suggested putting it in a section element, and the module referencing that resource would specify attributes contentonly="yes" and omittitle="yes". Scott suggested adding a description attribute to each resource. These could be used to generate a manifest with descriptions, for example. ACTION: Larry to send out new sample and RelaxNG schema with the latest changes. Bob suggested that members start testing the assembly mechanism so any problems that arise can be addressed. ============================================================= DocBook Technical Committee Meeting Minutes: 16 September 2009 ============================================================= d. Larry to send out new assembly sample and RelaxNG schema with the latest changes. COMPLETED 9. Using a map for modular DocBook. Extensive discussion of Sample 4 prepared by Larry in response to last meetings discussion.[2] [2]
http://lists.oasis-open.org/archives/docbook-tc/200909/msg00000.html Larry added description attributes, and converted output attributes to output elements to make them more flexible. The filterin and filterout attributes were added for profiling. The renderas attribute was added to output elements as well, so that one module could be rendered differently for different outputs. The contentonly attribute was added to allow selecting an element's children minus its wrapper. The omittitles attribute could be used to skip the title of an imported element. Norm wondered if a more general transform mechanism would be needed for things like contentonly and omittitles. Larry said they considered a subset of XPath, but didn't really need it and it would add considerable complexity to the processing. Norm questioned how the renderas attribute value was inherited by following-sibling modules, and wondered if those should each have their own attribute. Larry said that renderas="auto" was the default, but its meaning needs clear definition. A value of "auto" means that if the root element of the resource is valid at the location of the module, then use that element name. Otherwise, the value of the preceding sibling module with a renderas attribute would apply. Not clear yet what happens if no preceding sibling renderas. Gershon questioned the use of info element. Gershon wondered if @type can have more than one value. Larry clarified the difference between @type and @outputformat. @type has user-defined values. Gershon asked why filterin and filterout were mutually exclusive. The filterin sets a profile condition for inclusion, and filterout sets one for exclusion. Bob gave an example of where both could be present if different profiling attributes were used. We resolved to allow both elements. Gershon asked if @outputformat could be inherited from ancestor elements. Larry said we could add a @defaultoutputformat to structure to set the default for all of its descendants, which could be overridden for individual descendants. Larry pointed out that the attribute is already multi-valued. Gershon pointed out that the behavior of navtitle is different from the same element in DITA, which could create confusion for users of both. Norm suggested using titleabbrev instead of navtitle to avoid the confusion. Gerson asked if outputfile could be used to suppress chunking of an element. Larry suggested a @chunk attribute whose value could be "no" to turn off chunking of an element that would otherwise be chunked, a value of "yes" to chunk an element that would not otherwise be chunked, or "auto" (the default) which means to follow the rules of the chunker. Gershon asked about the empty index element as a child of module, when it could be at the top level as its own element. Bob suggested that <index/> be made a child of a resource element and pointed to by an empty module with a resourceref attribute. But no other resource element has content. Bob also pointed out that although indexes are generated, they sometimes have a type (selected indexterms instead of all terms), and sometimes has preamble content. We will investigate indexes and TOCs some more. ACTION: Bob to develop a stylesheet to transform an assembly into a document. ACTION: Gershon to develop a reltable example. ACTION: Larry to revise the same and schema based on comments. ============================================================= DocBook Technical Committee Meeting Minutes: 21 October 2009 ============================================================= e. Bob to develop a stylesheet to transform an assembly into a document. COMPLETED See
http://lists.oasis-open.org/archives/docbook-tc/200910/msg00001.html f. Larry to revise the assembly sample and schema based on comments. COMPLETED g. Gershon to develop a reltable example. CONTINUED 9. Modular DocBook. Larry's assembly sample 5:
http://lists.oasis-open.org/archives/docbook-tc/200910/msg00001.html Larry: I've been responding to comments from people. I've added a default output format to the structure element that would apply to its children. I won't repeat everything that we discussed at the last telcon. Larry: When I added the default output format to structure, I needed some way to say "don't render this" and I may have overloaded renderas. On line 259 of the file, I have an output statement with two output formats and a renderas of "norender". [[ Some discussion of the example in the assembly file. ]] Some sentiment that using renderas="norender" is abuse of the renderas attribute and should be changed. Although not rendering in some formats is a kind of filtering, it seems not to be one of the normal effectivity attribute so filtering doesn't apply? Not complete agreement. Norm ponders the use of more complex XPath evaluation to simplify authoring. Consensus seems to come back to adding a new attribute to the output element that indicates that the content should be suppressed. Possible names: omitoutput, discard, suppress Straw poll, vote for up to two: omitoutput : discard : 2 suppress : 3 Is there anyone who cannot live with "suppress"? Proposal: Add a suppress attribute to output, if suppress=true (or 1) then the output is not rendered. Accepted. (In addition, Norm suggests removing "output" from the attribute names on the <output> element.) Additional discussion about the use of grammer= on line 317. Conclusion: change grammer= on that line to transform= and add it to the transforms section at the bottom (renamed from grammartransforms): <module resourceref="help.tutorial"> <output outputformat="helpsystem" outputfile="xidi-help.tutorial" grammar="tutorial"/> ... </module> ... <grammartransforms xml:base="file:///opt/xidi/util/grammartransforms"> <transform grammar="dita" fileref="dita2docbook.xsl"/> <transform grammar="tutorial" fileref="docbook2tutorial.xsl"/> </grammartransforms> Becomes: <module resourceref="help.tutorial"> <output outputformat="helpsystem" outputfile="xidi-help.tutorial" name="tutorial"/> ... </module> ... <transforms xml:base="file:///opt/xidi/util/transforms"> <transform grammar="dita" fileref="dita2docbook.xsl"/> <transform name="tutorial" fileref="docbook2tutorial.xsl"/> </transforms> Bob encourages everyone to try out the transform stylesheet that he supplied which generates an assembly file for an existing document. Jirka suggests that perhaps the assembly elements should be in a different namespace. Norm agrees that its worth considering but worries about the fact that authors would have to switch back and forth between the assembly namespace and the docbook namespace for content. Bob wonders if this is really necessary? It would definitely complicate things. Jirka isn't sure, just thinks it's worth considering. Larry raises questions about how much simplicity and defaulting should be allowed. We want to make sure that we're optimizing for what we're trying to do. Short term optimization may not be valuable in the long run. ============================================================= DocBook Technical Committee Meeting Minutes: 18 November 2009 ============================================================= 10. DocBook assembly schema. No further changes have been suggested. Members said they would try out the prototype stylesheets that Bob provided that convert between a DocBook document and an assembly with topics. ACTION: Larry will publish an updated schema with last month's changes. Norm suggested that we make available both full and simplified versions. He is concerned that the details of the full version will overwhelm those getting started who need just basic assembly. It may be separate schemas, or just documentation and examples. ACTION: Norm to prepare a proposal for full and simplified assembly versions. Bob proposed adding a relatedlink element to DocBook 5. [2] [2]
http://lists.oasis-open.org/archives/docbook-tc/200911/msg00003.html This could complement related links managed at the assembly level. Members were generally favorable, but no action was taken yet. Bob suggested organizing a separate discussion of linking in modular DocBook, and several members expressed interest. ACTION: Bob to organize a meeting to discuss linking in modular DocBook. ============================================================= DocBook Technical Committee Meeting Minutes: 16 December 2009 ============================================================= b. Larry to publish assembly schema with last month's changes. COMPLETED c. Norm to prepare proposal for full and simplified assembly versions. COMPLETED d. Bob to organize a meeting to discuss linking in modular DocBook. COMPLETED 9. Linking in modular DocBook. See Bob's minutes from yesterday.[2] [2]
http://lists.oasis-open.org/archives/docbook-tc/200912/msg00021.html Inline relatedlinks and relationships from assemblies are two different ways of expressing the same thing. Documentation and implementation stratgies TBD. 11. DocBook assembly schema. Norm's documentation attempts: [3] [3]
http://lists.oasis-open.org/archives/docbook-tc/200911/msg00017.html Larry's assembly proposal 6: [4] [4]
http://lists.oasis-open.org/archives/docbook-tc/200912/msg00019.html Larry's summary: - Added the 'suppress' attribute to output - Added chunking control - Added name attribute to transform element - Added transform attribute to the output element - Added a transform attribute and left the grammar attribute there - Removed the word output from all of the attribute names on the output element Norm attempts to summarize his document. Norm proposes that the output of an assembly is a single document. Larry pushes back, suggesting that the output is a document or collection of documents. Norm and Larry clearly don't agree completely on the high-level processing expectations. While Norm wants the assembly to be output-agnostic, Larry has quite different processing expectations depending on what sort of output is needed. ACTION: Larry to write up his view of the processing expectations of a structure element and how it has to work to satisfy his needs. ============================================================= DocBook Technical Committee Meeting Minutes: 20 January 2010 ============================================================= c. Larry to write up his view of the processing expectations of a structure element and how it has to work to satisfy his needs. COMPLETED 10. DocBook assembly schema. Still need to resolve syntax for related links in assembly. ACTION: Bob to restart discussion on the TC mailing list. Scott raised the issue of adding info to module and other assembly elements to support metadata. Norm had added info in order to hold a title that would override the title in the resource it pointed to. Bob objected to using info for override content as well as metadata for assembly elements. It was agreed that they need to be differentiated. ACTION: Bob to initiate discussion of info on TC list. ============================================================= DocBook Technical Committee Meeting Minutes: 17 February 2010 ============================================================= d. Bob to restart assembly related links discussion. COMPLETED. e. Bob to initiate discussion of assembly info element. COMPLETED. 9. Metadata in assemblies See Bob's email[2]. [2]
http://lists.oasis-open.org/archives/docbook-tc/201002/msg00002.html The group agreed that metadata for assembly elements should be separated from metadata that should override the content of a resource. Gershon provided some perspective on the DITA approach. We agreed that info should be used for metadata for assembly elements, so that its usage agrees with its usage in general DocBook (applies to its parent element). Could not agree on an element name for the other: info in a different namespace, info-override, info-resource. Will continue the discussion on the mailing list. ACTION: Bob to post element naming question to TC list. 10. Linking in modular DocBook. See Bob's email and followups.[3] [3]
http://lists.oasis-open.org/archives/docbook-tc/201002/msg00000.html A relationship/instance element references a resource element ID. An inline relatedlink element references a content ID. These are to be merged, filtered, sorted, and output at the end of each topic. We agreed to add a "type" attribute to relatedlink to enable categorization similar to the relationship/association element. ACTION: Bob to create a sample for review. ============================================================= DocBook Technical Committee Meeting Minutes: 17 March 2010 ============================================================= Meeting cancelled. ============================================================= DocBook Technical Committee Meeting Minutes: 21 April 2010 ============================================================= a. Bob to develop a reltable example. COMPLETED and just sent out. e. Bob to post assembly metadata element naming question to TC list. COMPLETED f. Bob to create sample of linking in modular doc. COMPLETED by Norm 10. Metadata in assemblies See Bob's email[2]. [2]
http://lists.oasis-open.org/archives/docbook-tc/201002/msg00002.html After some discussion of Bob's proposal, it was accepted for the assembly beta version. We may change the element name "override" before submission to OASIS. Here are the changes. a. Permit <info> on any element in an assembly. b. Define the content of info like the DocBook 5 info element. c. An info element in <structure> can contribute to the output, just like the info element on the root element of a document. d. An info element in any other assembly element generally does not contribute to the output, although I'm sure there are cases where it could. e. Permit <override> only on <module>. f. Define the content of <override> to be only those elements that make sense to be overridden. Not sure what that list is, though. g. Any element in <override> is merged with the content that the module points to, and overrides it if the corresponding element exists in the resource. 11. Linking in modular DocBook. See Bob's email and followups.[3] [3]
http://lists.oasis-open.org/archives/docbook-tc/201002/msg00000.html Norm posted a complete example [4]. [4]
http://lists.oasis-open.org/archives/docbook-tc/201003/msg00003.html Bob reviewed it and said it was what he expected to happen when processing such related links. ACTION: Bob to republish the topic schema for inclusion in 5.1. ACTION: Bob's reltable example to be discussed at the next meeting, but we will omit it in the first 5.1 beta. ============================================================= DocBook Technical Committee Meeting Minutes: 19 May 2010 ============================================================= 11. Linking in modular DocBook. This item was regarding reltable, which is not currently slated to be included in 5.1. We will cover this at the next meeting. Norm wants to get out a 5.1 Beta that includes topic and assembly very soon. We discussed the issue of where the topic element could appear. Larry suggested only where a chapter could appear (in book and part), and Bob suggested adding anywhere a section could appear, except disallowing topic and section to be siblings. The committee favored the latter, so we will include a looser model in the 5.1 beta. ============================================================= DocBook Technical Committee Meeting Minutes: 23 June 2010 ============================================================= 8. Reltables in modular DocBook. This will held until after DocBook 5.1 beta is released. Larry suggests the current assembly elements are more powerful than a table model for related links. ACTION: Larry to render the current reltable example from Bob and Norm with the current assembly elements for comparison. ============================================================= DocBook Technical Committee Meeting Minutes: 21 July 2010 ============================================================= c. Larry to render the current reltable example from Bob and Norm with the current assembly elements for comparison. CONTINUED 8. Reltables in modular DocBook. Continued. 10. Release of DocBook 5.1 beta. Norm released 5.1b1 on docbook.org. The assembly.dtd is not yet available. Scott suggested that some tools are needed for processing. Norm's questions about assembly were addressed. a. renderas attribute on module and its output element? Module is simpler if you don't need multiple outputs. If conflict, then output element wins. b. Make renderas a qname? Yes, so namespaces can be used. c. structure element should have renderas? Yes. d. What is structure type attribute for? Tells the production system how to assemble. Norm wants more explanation for documenting it. e. Use of description attribute on resource? Norm and Gershon suggest it should be an element to support complete localization, including Ruby. Larry says it is for generating a manifest. Gershon suggested a different attribute name, then. ACTION: Norm to release 5.1b2 and announce it more widely. ACTION: Larry to create a sample of the use of @type. ============================================================= DocBook Technical Committee Meeting Minutes: 18 August 2010 ============================================================= b. Larry to render the current reltable example from Bob and Norm with the current assembly elements for comparison. CONTINUED d. Norm to release DocBook 5.1b2 and announce it more widely. COMPLETED e. Larry to create a sample of @type in an assembly. CONTINUED 8. Reltables in modular DocBook. Continued. ============================================================= DocBook Technical Committee Meeting Minutes: 22 September 2010 ============================================================= b. Larry to render the current reltable example from Bob and Norm with the current assembly elements for comparison. Larry couldn't find the example. ACTION: Nancy to send some example reltables to the tc-list. Larry's action continued. Larry and Nancy will work together on the conversion. c. Larry to create a sample of @type in an assembly. COMPLETED 8. Reltables in modular DocBook. Continued. ============================================================= DocBook Technical Committee Meeting Minutes: 20 October 2010 ============================================================= b. Larry and Nancy to render the current reltable example from Bob and Norm with the current assembly elements for comparison. COMPLETED c. Nancy to send some example reltables to the tc-list. COMPLETED 8. Reltables in modular DocBook. Larry posted examples shortly before the meeting, so the group decided to continue this item to next meeting so we could review the examples. 10. Discussion of Larry's help example in assembly and @type proposal. [3] [3]
http://lists.oasis-open.org/archives/docbook-tc/201009/msg00007.html Continue this item, urging members to review Larry's example before the next meeting. ============================================================= DocBook Technical Committee Meeting Minutes: 17 November 2010 ============================================================= b. Larry and Nancy to render the current reltable example from Bob and Norm with the current assembly elements for comparison. COMPLETED c. Nancy to send some example reltables to the tc-list. COMPLETED 8. Reltables in modular DocBook. [2] [2]
http://lists.oasis-open.org/archives/docbook-tc/201011/msg00008.html Much discussion of Larry's reltable examples, and reltables in general. Norm asked for explanations, and Larry and Nancy provided them. Norm finds reltables difficult to understand. Larry says they have implicit relationships. Bob mentioned that DITA has strongly typed topics for the columns, but DocBook topics do not. Nancy stated the goal: creating linking within an assembly. Larry found that doing the samples showed some features that would be useful, like directionality of links. ACTION: Larry to use his experience from the samples to create a fresh proposal for linking within assembly. 10. Discussion of Larry's help example in assembly and @type proposal. [3] [3]
http://lists.oasis-open.org/archives/docbook-tc/201009/msg00007.html Larry provided answers to questions. Members could see the need to add a type attribute to the assembly structure element. ============================================================= DocBook Technical Committee Meeting Minutes: 15 December 2010 ============================================================= e. Larry to create a fresh proposal for linking within assembly. COMPLETED 8. Linking in assembly. Postponed until next meeting to digest Larry's latest proposal. [4] [4]
http://lists.oasis-open.org/archives/docbook-tc/201012/msg00007.html 10. Discussion of Larry's help example in assembly and @type proposal. [3] [3]
http://docbook.org/docs/transclusion/ Larry provided answers to questions. Members could see the need to add a type attribute to the assembly structure element. ============================================================= DocBook Technical Committee Meeting Minutes: 19 January 2011 ============================================================= e. Larry to create a fresh proposal for linking within assembly. COMPLETED 6. Linking in assembly. Please see Larry's latest proposal. [2] [2]
http://lists.oasis-open.org/archives/docbook-tc/201012/msg00007.html Larry summarized the proposal. The basic relationship is bidirectional. Directional relationships can be implemented using linking="targetonly" or linking="sourceonly". He described hierarchical and navigational path relationships too. The list relationship generated much discussion. ACTION: Larry to clarify list relationship in the proposal. 8. Decision about Larry's help example in assembly and @type proposal. Postponed. Larry and Bob to track down the latest info and repost it. ============================================================= DocBook Technical Committee Meeting Minutes: 23 February 2011 ============================================================= Meeting cancelled. ============================================================= DocBook Technical Committee Meeting Minutes: 16 March 2011 ============================================================= c. Larry to clarify list relationship in the assembly linking proposal. COMPLETED 6. Linking in assembly. Please see Larry's previous proposal. [2] [2]
http://lists.oasis-open.org/archives/docbook-tc/201012/msg00007.html Larry's revised proposal is here:
http://lists.oasis-open.org/archives/docbook-tc/201103/msg00005.html Some discussion of the issues raised by Larry at the end of that document. Norm observes that he would have used <tocentry linkend="..."/> instead of nested <xref> elements. Some question about whether that's reasonable markup. Even with the TOC markup, you still need an <instance> element because you need somewhere to hang the additional semantic that this is where the list goes (@linking=). Norm: Since using TOC markup didn't reduce the number of elements we need, I'm not sure it's worth the effort. Norm asks if we can change association to title. Larry observes that it's functioning as a title here, but it isn't semantically the same as a title. If you're generating a semantic map, you use the association to measure the distance between concepts. Norm: I think we should abandon the TOC markup. Gershon: Me too. Larry: Ok. 8. Decision about Larry's help example in assembly and @type proposal. Norm: I don't recall why I objected, but I'm prepared to withdraw the objection. No other comments heard. Norm: Speaking more generally, do we have a sense of how well the Addembly Reference section in the documentation reflects reality? Larry: I think it may need some minor changes and extensions. I think adding something about the help system would be helpful. ACTION: Larry to review the DocBook 5.1 schema to see if it reflects his notion of the current state of play. ============================================================= DocBook Technical Committee Meeting Minutes: 20 April 2011 ============================================================= a. Larry to review the DocBook 5.1 schema to see if it reflects his notion of the current state of play for assembly. CONTINUED 8. DocBook assembly. Bob: What steps are needed to complete this work? Larry: need to finalize the schema. He needed the latest version from SourceForge, but could not build assembly from SVN. He will work with Norm to get the latest, and the compare it to the minutes to make sure it represents all the changes that have been discussed. He will raise any issues that come up in email. Question was asked about XSL support for processing assembly. ACTION: Bob to update his XSL stylesheet for building a DocBook document from an assembly. Larry suggested later also implementing an XSL to generate DocBook website from an assembly. Norm has written a chapter in the 5.1 TDG [2] that needs reviewing for the latest updates. [2]
http://docbook.org/tdg51/en/html/ch06.html Dick was wondering if assembly could be generalized beyond DocBook for use by other schemas. Larry said some DocBook specific elements would need to be modified. When the schema and stylesheets are available, Scott said he could do some experimental work with converting content. ============================================================= DocBook Technical Committee Meeting Minutes: 25 May 2011 ============================================================= Meeting cancelled. ============================================================= DocBook Technical Committee Meeting Minutes: 15 June 2011 ============================================================= a. Larry to review the DocBook 5.1 schema to see if it reflects his notion of the current state of play for assembly. COMPLETED e. Bob to update his XSL stylesheet for building a DocBook document from an assembly. CONTINUED 8. DocBook assembly. Larry and Norm discussed and settled the last issues on the mailing list. [1] [1]
http://lists.oasis-open.org/archives/docbook-tc/201105/msg00005.html ACTION: Norm to post DocBook 5.1 beta to docbook.org with the latest changes. ============================================================= DocBook Technical Committee Meeting Minutes: 20 July 2011 ============================================================= a. Bob to update his XSL stylesheet for building a DocBook document from an assembly. CONTINUE i. Norm to post DocBook 5.1 beta with latest assembly stuff to docbook.org. COMPLETED 6. DocBook assembly. Bob raised RFE 3368297 to allow hierarchical elements to be empty except for title. The expectation is that such empty elements would be populated during the assembly process. Basically the content models would change from using + to using * for block and sections. Since this loosens the content models, the change would be backwards compatible. Proposal to accept 3368297 was approved. The TC considers the design of assembly to be complete, and now we need experience. Bob will finish up the assembly stylesheet shortly and make it available. Later in the day Norm posted this message about implementing nearly empty hierarchy elements:
http://lists.oasis-open.org/archives/docbook/201107/msg00016.html He said he would work on solving the problem for DTD and XSD ambiguity. ============================================================= DocBook Technical Committee Meeting Minutes: 17 August 2011 ============================================================= a. Bob to update his XSL stylesheet for building a DocBook document from an assembly. CONTINUE 6. DocBook assembly a. inheritance of renderas attribute (see Bob's email
http://lists.oasis-open.org/archives/docbook-tc/201107/msg00006.html ) Larry clarified that the intention was that an automatic renderas would only be applied if the referenced object did not fit without change (e.g., including a section element under a book level). Bob suggested that any automatic renderas should be a stylesheet issue for a particular rendering of an assembly, not part of the assembly standard itself. Norm proposed that automatic renderas not be part of the assembly specification itself. APPROVED ACTION: Norm to modify the assembly documentation to reflect this change. ACTION: Larry to write documentation on creating a navigational hierarchy from an assembly. On 21 August 2011 Bob releases an updated assembly XSL toolkit on SourceForge:
http://sourceforge.net/projects/docbook/files/assembly/ ============================================================= DocBook Technical Committee Meeting Minutes: 28 September 2011 ============================================================= Meeting cancelled. ============================================================= DocBook Technical Committee Meeting Minutes: 19 October 2011 ============================================================= a. Bob to update his XSL stylesheet for building a DocBook document from an assembly. COMPLETED e. Norm to modify the assembly documentation to reflect that automatic renderas not be part of the assembly specification itself. COMPLETED f. Larry to write documentation on creating a navigational hierarchy from an assembly. CONTINUED 6. DocBook assembly a. allow structure to behave like module (see Bob's email
http://lists.oasis-open.org/archives/docbook-tc/201108/msg00018.html ) Larry suggested that if structure element behaves like module, then do we need structure? Norm also would like a comparison of structure and module if we make this change. ACTION: Bob to report on differences between structure and module. Larry suggested two alternate methods of achieving the equivalent of resourceref on structure. i. Use a child module with contentonly to reference a top-level resource. ii. Use a single child module that contains all other content, so structure does not contribute an element. ACTION: Bob and Larry to prepare samples of the same content implemented in these different approaches. b. other issues? Bob requested that people try out the XSL stylesheets he prepared for processing assembly. He pointed out that the kit includes a stylesheet to disassemble an existing DocBook document into topics and an assembly to make it easy to get started. =============================================================DocBook Technical Committee Meeting Minutes: 16 November 2011============================================================= d. Larry to write documentation on creating a navigational hierarchy from an assembly. COMPLETED h. Bob to report to TC on differences between structure and module in his proposal. COMPLETED i. Bob and Larry to prepare samples of the same content implemented in the different structure-level approaches. COMPLETED ACTION: Norm to incorporate Larry's help assembly doc [2] into The Definive Guide. 6. DocBook assembly Allow structure to behave like module (Bob's proposal
http://lists.oasis-open.org/archives/docbook-tc/201108/msg00018.html ) Bob posted a set of four examples of how to specify the root element and top level frontmatter elements in an assembly.
http://lists.oasis-open.org/archives/docbook-tc/201111/msg00001.html Bob also posted a comparison of the structure and module elements, where module comes in two flavors: container module that contains DocBook element, or resource module that references content.
http://lists.oasis-open.org/archives/docbook-tc/201111/msg00004.html The discussion centered on whether an assembly should contain actual content. Scott wondered about translation and the need to keep translatable content separate. Norm pointed out that putting content in assembly is optional. Nancy suggested we might add an attribute to indicate that no translatable content is allowed if that is the company policy. Larry pointed out that the original proposal used resource pointing to an external file for all content, so there was only one kind of module, with a required resourceref attribute. We anticipated objection to forming a full module/resource/filename combination just to add an empty index or toc element to an assembly. First we allowed resource to contain an element, then we allowed module to contain an element directly. The omittitles and contentonly attributes were added to support inserting a sequence of elements (children of the single element) from such literal content. Norm suggested that we allow the container module from a single element to contain any bag of DocBook elements, not a single element, and thereby remove omittitle, contentonly, and renderas as obsolete. This proposal received no objections. Gershon raised concerns that assembly has gotten too complicated. Larry pointed out that most of the recent discussions have been about corner cases. The group decided to step back and consider a simplified proposal. ACTION: Bob to prepare a simplified assembly schema and circulated through the mailing list. ACTION: Norm to clarify in TDG that DocBook common attributes on structure are normally copied to the output root element. =============================================================DocBook Technical Committee Meeting Minutes: 14 December 2011============================================================= f. Norm to incorporate Larry's help assembly doc [2] into The Definive Guide. CONTINUED i. Bob to prepare simplified assembly schema and circulate through the mailing list. COMPLETED j. Norm to clarify in TDG that DocBook common attributes on structure are normally copied to the output root element. CONTINUED 6. DocBook assembly Norm announced on 13 December 2011 that he had released DocBook 5.1b5, implementing RFE #3368297 empty hierarchy elements.
http://lists.oasis-open.org/archives/docbook/201112/msg00042.htmlReviewed Bob's simplified assembly proposal:
http://lists.oasis-open.org/archives/docbook-tc/201112/msg00000.htmlThere was general agreement with the proposed changes. The one remaining issue is naming the metadata container elements. There are two uses of metadata: 1. Metadata about elements in the assembly file. This information could document the author or revision history of a assembly, structure, resource, module element. It could even include a title that would be referenced by a content management system, but generally this metadata does not appear in assembled output. 2. Metadata to override info elements contained in referenced content. This metadata could be expressed in the output. Some wanted to use info for metadata about the assembly elements themselves, following the pattern of other docbook elements where an info element documents its parent. Bob mentioned that using info in module where content is being specified was confusing, since that location implies using info as an override. Larry pointed out that the element name "override" in module was not always appropriate. In the case of a module that specifies renderas="chapter" and has no resourceref attribute, then a title specified in that module would not be overriding anything. Perhaps "contentinfo" would be more general. ACTION: Bob to write up an assembly schema modeling the info elements with suggested names for discussion next month. =============================================================DocBook Technical Committee Meeting Minutes: 18 January 2011============================================================= e. Norm to incorporate Larry's help assembly doc [2] into The Definive Guide. COMPLETED g. Norm to clarify in TDG that DocBook common attributes on structure are normally copied to the output root element. COMPLETED i. Bob to write up an assembly schema modeling the info elements with suggested names for discussion next month. COMPLETED 6. DocBook assembly Norm released DocBook 5.1b6 on 16 January 2012
http://www.docbook.org/xml/5.1b6/Reviewed Bob's assembly info proposal.
http://lists.oasis-open.org/archives/docbook-tc/201201/msg00005.html Members liked the change from element name "override" to "merge" for content to be merged into the output. For metadata about assembly elements, the committee did not like the suggestion of individual info elements per assembly element. Discussed whether to use "info" or "assemblyinfo" as the element name for metadata about assembly elements. We agreed that this feature would not be heavily used. A straw poll showed lack of consensus, but only soft support for assemblyinfo. The proposal to use info and merge element names was approved. ACTION: Norm to implement these changes in 5.1 ACTION: Bob to update his assembly stylesheets. ============================================================= DocBook Technical Committee Meeting Minutes: 22 February 2011 ============================================================= 6. DocBook assembly The committee agreed that we have completed this phase of the work and need to roll it out. We await Norm's update to the schema and Bob's update to the stylesheets. Bob Stayton Sagehill Enterprises
bobs@sagehill.net