[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] DocBook Technical Committee Meeting Agenda: 15June 2011
I must give my regrets for this month's meeting, as a mandatory training session has been scheduled directly opposite this meeting (and I suspect you all will be having more fun).
I had completed my action item prior to the previous meeting, however there was little discussion on the mailing lists. I have attached my original message and Norm's response to it and my response to him. Norm and I did discuss the issues briefly during the second attempt at last month's meeting and resolved that using the element name "description" instead of "manifesttext" would be preferable and that supporting namespaces in the format attribute is something we should probably wait to implement until it is requested, since you could include something to indicate the namespace in the tokens that were used (dita.webhelp and db.webhelp for the DITA and DocBook versions of Web help). With these changes, I think that updating the schema to deal with the issues listed in the original message would bring it into compliance with what we have discussed.
Regards,
Larry Rowland
-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Friday, June 10, 2011 10:10 AM
To: DocBook Technical Committee
Cc: docbook@lists.oasis-open.org
Subject: [docbook-tc] DocBook Technical Committee Meeting Agenda: 15 June 2011
DocBook Technical Committee Meeting Agenda: 15 June 2011
=============================================================
The DocBook Technical Committee will meet on Wednesday, 15 June 2011 at
01:00p EDT for 90 minutes.
Attendance at teleconferences is restricted to members
(and prospective members) of the committee.
This is the phone number for Wednesday's DocBook TC call:
Phone: +1-719-387-5556
Code: 902213
The DocBook TC uses the #docbook IRC channel on
irc.freenode.org. The IRC channel is used for exchanging
URIs, providing out-of-band comments, and other aspects
of the teleconference, so please join us there if at
all possible.
Agenda
1. Roll call
2. Accepting the minutes [1] of the previous meeting.
3. Next meeting: 20 July 2011
4. Review of the agenda.
5. Review of open action items
a. Larry to review the DocBook 5.1 schema to see if it reflects
his notion of the current state of play for assembly.
b. Jirka to create a single file Publishers schema.
c. Bob to query Norm about adding Publishers schema to TDG.
d. Bob to send note to Norm asking if he can create
a Simplified DocBook 5 schema. Scott said he could help.
e. Bob to update his XSL stylesheet for building a
DocBook document from an assembly.
f. Jirka will write up a comparison of the two transclusion
approaches (empty element with @ref attribute or
dedicated ref element).
g. Nancy will review the DITA discussion of this
issue of processing order of transclusions and profiling.
h. Bob to investigate ISTC and report to the TC.
6. Publishers Schema promotion
Add to docbook.org.
Stylesheets.
Documentation.
7. Simplified DocBook 5
8. DocBook assembly.
9. Transclusion in DocBook.
10. Handling HTML and FO semantics [2]
11. Review of Requests for Enhancement
To browse a specific RFE, enter the URL (on one line):
http://sourceforge.net/tracker/index.php?func=detail&;;
group_id=21935&atid=384107&aid=XXXX
RFEs to revisit for 6.0
1907003 biblioid content model too broad
RFEs under discussion
1679665 Add better support for modular documentation
2820190 add a topic element
2820947 Ability to transclude text
3035565 Allow sections at any level
3107140 aconym expansion inline
3146537 HTML forms elements are missing from DocBook 5 schemas
3156768 <result> tag
3163121 Add <preface> as a child of <set>
3274136 Production markup is too limiting
3287339 Add ISTC to class attribute for biblioid
-----
[1] http://lists.oasis-open.org/archives/docbook-tc/201104/msg00017.html
[2] http://lists.oasis-open.org/archives/docbook/201106/msg00007.html
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
--- Begin Message ---
- From: "Rowland, Larry" <larry.rowland@hp.com>
- To: "docbook-tc@lists.oasis-open.org" <docbook-tc@lists.oasis-open.org>
- Date: Tue, 10 May 2011 17:21:34 +0000
As requested at the last TC meeting, I am initiating a discussion of how well the current schema at top of tree reflects the recent discussions of the assembly at TC meetings. I applied the attached RNC version of the top of tree assembly schema, provided by Norm, to three recent sample files generated during the discussions of the assembly and relationship elements. The following comments are based on elements and attributes that were not allowed by the current schema (or behaved differently than the discussions assumed) but were included in the files and were necessary to accomplish the outcomes described in the discussions of the files. The assembly schema is a flattened schema and quite large, so doing a thorough analysis of it will take some time, but this should be a good starting point for the discussion. The names of the attributes and elements are open for discussion. The semantics they represent are missing. The values of the attributes are representative, not necessarily exhaustive (this is, after all, intended to stimulate discussion). 1) The element "manifesttext" is missing. It is intended to provide descriptions of the resources for a manifest document generated by parsing an assembly that has a set of resources designed to be reused across assemblies, to support easy reuse of shared resources. It replaces a proposed description attribute that was rejected due to localization concerns about putting editable text in an attribute. It is intended for simple (typically a sentence or phrase) descriptions, so little, if any, markup should be allowed inside it. I assumed CDATA. A) The element "manifesttext" should be allowed as a child of "resources." B) The element "manifesttext" should be allowed as a child of "resource." 2) The attribute "format" on the "output" element originally allowed multiple tokens rather than a single one. This was to allow a single output element to bind a characteristic to multiple output formats (such as webhelp and ohj, which frequently have similar delivery structures). If it does not allow multiple tokens, the same result can be achieved by repeated binding of the characteristic to multiple output statements, but the intent may be less obvious. Allowing the tokens to include name spaces was also discussed, supporting something like "dita:webhelp" to indicate the output is in the form of a webhelp system described by DITA as opposed to "db:webhelp" which would specify a DocBook Webhelp system. 3) It may be desirable to allow the element output in more positions as a child of structure, it currently has to precede title, which was somewhat confusing, as I initially concluded it was not allowed as a direct child of structure. I had title and titleabbrev preceding the output elements in one file, but following it in another or I would have concluded it was not allowed as a child of structure based on a single instance that had it in the wrong position. Similar concerns apply to positioning it inside a module. 4) The attribute "chunk" should be allowed on the element "output," as well as on "module," to deal with situations where chunking needs to be specified for one output but not for others into which the same structure is being rendered. If specified on a module as well as on an output element that is a child of the module, the value of the attribute on the module is the default for all outputs and the value on the output element overrides the default for the specified outputs. 5) The attribute "linking" needs to be added to the element "instance" to allow specifying the type of linking. Example values include "targetonly" and "destinationonly," and "pathshome," and "listdestination." This is the name of the attribute used for much the same purpose in DITA. 6) The attribute "type" should be allowed on the element "relationships" to allow defining groups of relations with specific characteristics based on the type specification. Example values include "pathlist" and "lists." 7) The element "instance" needs to be added as a child of "relationships" to support the use of relationships to describe combinations of paths through documentation. Larry ======================================================================= [ Larry Rowland | If you want to build a ship, don't drum ] [ MSL/QST+CSI | up the men to gather the wood, divide ] [ Hewlett-Packard | the work, and give orders. Instead, ] [ 3404 East Harmony Road | teach them to yearn for the vast and ] [ Fort Collins, CO 80528 | endless sea. - Antoine de Saint Exupery ] [ Phone: 970/898-2280 +-----------------------------------------] [ E-Mail:larry.rowland@.hp.com ] =======================================================================--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php--- End Message ---
--- Begin Message ---
- From: Norman Walsh <ndw@nwalsh.com>
- To: "docbook-tc@lists.oasis-open.org" <docbook-tc@lists.oasis-open.org>
- Date: Wed, 11 May 2011 16:53:54 +0000
"Rowland, Larry" <larry.rowland@hp.com> writes: > As requested at the last TC meeting, I am initiating a discussion of > how well the current schema at top of tree reflects the recent > discussions of the assembly at TC meetings. [...] > 1) The element "manifesttext" is missing. It is intended to provide > descriptions of the resources for a manifest document generated by > parsing an assembly that has a set of resources designed to be > reused across assemblies, to support easy reuse of shared > resources. It replaces a proposed description attribute that was > rejected due to localization concerns about putting editable text > in an attribute. It is intended for simple (typically a sentence > or phrase) descriptions, so little, if any, markup should be > allowed inside it. I assumed CDATA. > A) The element "manifesttext" should be allowed as a child of > "resources." > B) The element "manifesttext" should be allowed as a child of > "resource." Can we overload "alt" for this purpose? I'm not sure that's a good idea, I'm just wondering out loud. If not, I think I'd prefer an element called "description" or something more generic than "manifesttext". > 2) The attribute "format" on the "output" element originally allowed > multiple tokens rather than a single one. This was to allow a > single output element to bind a characteristic to multiple output > formats (such as webhelp and ohj, which frequently have similar > delivery structures). If it does not allow multiple tokens, the > same result can be achieved by repeated binding of the > characteristic to multiple output statements, but the intent may be > less obvious. > > Allowing the tokens to include name spaces was also discussed, > supporting something like "dita:webhelp" to indicate the output is > in the form of a webhelp system described by DITA as opposed to > "db:webhelp" which would specify a DocBook Webhelp system. Multiple tokens is ok by me. I'm agnostic on whether they should have namespaces or not. On the one hand, it would distinguish between dita:webhelp and db:webhelp, but aren't the tokens just invented by the author? Are we really expecting assemblies to be reused and shared in ways that require namespaces? > 3) It may be desirable to allow the element output in more positions > as a child of structure, it currently has to precede title, which > was somewhat confusing, as I initially concluded it was not allowed > as a direct child of structure. I had title and titleabbrev > preceding the output elements in one file, but following it in > another or I would have concluded it was not allowed as a child of > structure based on a single instance that had it in the wrong > position. Similar concerns apply to positioning it inside a > module. Hmm. As long as it doesn't torture the content model, I've no objection to allowing it in more places. > 4) The attribute "chunk" should be allowed on the element "output," as > well as on "module," to deal with situations where chunking needs > to be specified for one output but not for others into which the > same structure is being rendered. If specified on a module as well > as on an output element that is a child of the module, the value of > the attribute on the module is the default for all outputs and the > value on the output element overrides the default for the specified > outputs. Ok. > 5) The attribute "linking" needs to be added to the element "instance" > to allow specifying the type of linking. Example values include > "targetonly" and "destinationonly," and "pathshome," and > "listdestination." This is the name of the attribute used for much > the same purpose in DITA. Ok. > 6) The attribute "type" should be allowed on the element > "relationships" to allow defining groups of relations with specific > characteristics based on the type specification. Example values > include "pathlist" and "lists." Ok. > 7) The element "instance" needs to be added as a child of > "relationships" to support the use of relationships to describe > combinations of paths through documentation. Ok. I've struggled from the very beginning to keep things simple. I'm just operating on faith that we really need all these knobs. As I go through the exercise of writing down the semantics and trying to implement them, I may want to push back a bit, but for the moment I don't want to be standing in the way. Be seeing you, norm -- Norman Walsh <ndw@nwalsh.com> | Convictions are more dangerous http://www.oasis-open.org/docbook/ | enemies of truth than lies.-- Chair, DocBook Technical Committee | Nietzsche--- End Message ---
--- Begin Message ---
- From: "Rowland, Larry" <larry.rowland@hp.com>
- To: Norman Walsh <ndw@nwalsh.com>, "docbook-tc@lists.oasis-open.org"<docbook-tc@lists.oasis-open.org>
- Date: Mon, 16 May 2011 22:24:42 +0000
1) Description is what the original attribute was called, but there was some objection to it (I don't remember exactly what). That's what it is, and a manifest is probably not the only possible destination for the content. I would be happy to go back to calling it a description. I think alt is stretching a bit. 2) Someone suggested allowing namespaces, but I don't remember the context. It was quite a while ago. I would suspect they are from the tool environment rather than from the author -- if the tool chain does not recognize them, they would serve no real purpose. -----Original Message----- From: Norman Walsh [mailto:ndw@nwalsh.com] Sent: Wednesday, May 11, 2011 10:54 AM To: docbook-tc@lists.oasis-open.org Subject: Re: [docbook-tc] Opening discussion of the Assembly schema "Rowland, Larry" <larry.rowland@hp.com> writes: > As requested at the last TC meeting, I am initiating a discussion of > how well the current schema at top of tree reflects the recent > discussions of the assembly at TC meetings. [...] > 1) The element "manifesttext" is missing. It is intended to provide > descriptions of the resources for a manifest document generated by > parsing an assembly that has a set of resources designed to be > reused across assemblies, to support easy reuse of shared > resources. It replaces a proposed description attribute that was > rejected due to localization concerns about putting editable text > in an attribute. It is intended for simple (typically a sentence > or phrase) descriptions, so little, if any, markup should be > allowed inside it. I assumed CDATA. > A) The element "manifesttext" should be allowed as a child of > "resources." > B) The element "manifesttext" should be allowed as a child of > "resource." Can we overload "alt" for this purpose? I'm not sure that's a good idea, I'm just wondering out loud. If not, I think I'd prefer an element called "description" or something more generic than "manifesttext". > 2) The attribute "format" on the "output" element originally allowed > multiple tokens rather than a single one. This was to allow a > single output element to bind a characteristic to multiple output > formats (such as webhelp and ohj, which frequently have similar > delivery structures). If it does not allow multiple tokens, the > same result can be achieved by repeated binding of the > characteristic to multiple output statements, but the intent may be > less obvious. > > Allowing the tokens to include name spaces was also discussed, > supporting something like "dita:webhelp" to indicate the output is > in the form of a webhelp system described by DITA as opposed to > "db:webhelp" which would specify a DocBook Webhelp system. Multiple tokens is ok by me. I'm agnostic on whether they should have namespaces or not. On the one hand, it would distinguish between dita:webhelp and db:webhelp, but aren't the tokens just invented by the author? Are we really expecting assemblies to be reused and shared in ways that require namespaces? > 3) It may be desirable to allow the element output in more positions > as a child of structure, it currently has to precede title, which > was somewhat confusing, as I initially concluded it was not allowed > as a direct child of structure. I had title and titleabbrev > preceding the output elements in one file, but following it in > another or I would have concluded it was not allowed as a child of > structure based on a single instance that had it in the wrong > position. Similar concerns apply to positioning it inside a > module. Hmm. As long as it doesn't torture the content model, I've no objection to allowing it in more places. > 4) The attribute "chunk" should be allowed on the element "output," as > well as on "module," to deal with situations where chunking needs > to be specified for one output but not for others into which the > same structure is being rendered. If specified on a module as well > as on an output element that is a child of the module, the value of > the attribute on the module is the default for all outputs and the > value on the output element overrides the default for the specified > outputs. Ok. > 5) The attribute "linking" needs to be added to the element "instance" > to allow specifying the type of linking. Example values include > "targetonly" and "destinationonly," and "pathshome," and > "listdestination." This is the name of the attribute used for much > the same purpose in DITA. Ok. > 6) The attribute "type" should be allowed on the element > "relationships" to allow defining groups of relations with specific > characteristics based on the type specification. Example values > include "pathlist" and "lists." Ok. > 7) The element "instance" needs to be added as a child of > "relationships" to support the use of relationships to describe > combinations of paths through documentation. Ok. I've struggled from the very beginning to keep things simple. I'm just operating on faith that we really need all these knobs. As I go through the exercise of writing down the semantics and trying to implement them, I may want to push back a bit, but for the moment I don't want to be standing in the way. Be seeing you, norm -- Norman Walsh <ndw@nwalsh.com> | Convictions are more dangerous http://www.oasis-open.org/docbook/ | enemies of truth than lies.-- Chair, DocBook Technical Committee | Nietzsche --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php--- End Message ---
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]