OASIS DocBook TC2

Title: Version reference for DocBook Publishers documents? Folks, It has come to my attention that the DocBook Publishers specification did not contain any specific guidance on how documents should declare their conformance to the spec (see https://sourceforge.net/tracker/?func=detail&aid=3006144&group_id=21935&atid=1037852 and the recent email to the list from Nic Gibson). In other words, according to: http://www.docbook.org/docs/howto/#cust-naming How shall DocBook Publishers documents be versioned? Should it be similar to simplified, such that: 5.0-extension publishers-1.0 It is not a true subset of DocBook 5.0, due to the additions of Dublin Core, speaker, line, linegroup, drama, dialogue, and poetry. Thoughts? Thanks and best regards, --Scott Scott Hudson Pelco by Schneider Electric United States API Strategy – API & Integration This transmission is intended only for use by the intended recipient(s). If you are not an intended recipient you should not read, disclose copy, circulate or in any other way use the information contained in this transmission. The information contained in this transmission may be confidential and/or privileged. If you have received this transmission in error, please notify the sender immediately and delete this transmission including any attachments.

On 1 February 2011 18:24, Scott Hudson <scott.hudson@pelco.com> wrote: > How shall DocBook Publishers documents be versioned? Should it be similar to > simplified, such that: > > 5.0-extension publishers-1.0 I've always expected the version to be numeric Scott? Equally, is @version used anywhere such that it would make it clear that I am processing pubs rather than plain docbook? > > It is not a true subset of DocBook 5.0, due to the additions of Dublin Core, > speaker, line, linegroup, drama, dialogue, and poetry. For which TDG is clear. "Don't call it docbook" Bit late now, but renaming the document element to x-pubs, where x is book/article/... perhaps? Or simpler, just give it a clear / different name, then use docbook ns etc? First time for docbook I guess. Is website a fair comparison? regards -- Dave Pawson XSLT XSL-FO FAQ. Docbook FAQ. http://www.dpawson.co.uk

On 3 Feb 2011, at 09:32, Dave Pawson wrote: > On 1 February 2011 18:24, Scott Hudson <scott.hudson@pelco.com> wrote: > >> How shall DocBook Publishers documents be versioned? Should it be similar to >> simplified, such that: >> >> 5.0-extension publishers-1.0 > > I've always expected the version to be numeric Scott? > Equally, is @version used anywhere such that it would > make it clear that I am processing pubs rather than > plain docbook? > I'd agree that version should normally be numeric but, apart from namespace how else do we identify this? > >> >> It is not a true subset of DocBook 5.0, due to the additions of Dublin Core, >> speaker, line, linegroup, drama, dialogue, and poetry. > > > For which TDG is clear. "Don't call it docbook" > Bit late now, but renaming the document element > to x-pubs, where x is book/article/... perhaps? This is exactly where my concern came from. I think that renaming the document element would possibly be too much - it would break support in too many tools (for example, Oxygen recognizes DocBook by, amongst other things, the document element) and would complicate the DocBook XSLT. > > Or simpler, just give it a clear / different name, > then use docbook ns etc? I wasn't involved in DocBook Publishers from the beginning - was a new namespace considered for the new elements? > > First time for docbook I guess. I think there possibly needs to be a different set of decisions here. Right now, we have the TDG guidelines. Those make perfect sense for something that originates outside of the DocBook infrastructure as it were. What appears to be needed is a way to identify an official variant on DocBook in a way that makes it clear that it isn't DocBook but is an official and public variant. There are three possible ways to identify this as far as I can see 1) A new root element 2) A namespace for the new elements (what about the modified elements?) 3) A new version I think that 3) is the least destructive. > Is website a fair comparison? I think it probably is. How is website 'identified'? nic > > regards > > > -- > Dave Pawson > XSLT XSL-FO FAQ. > Docbook FAQ. > http://www.dpawson.co.uk > > --------------------------------------------------------------------- > 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 > -- Nic Gibson Corbas Consulting Digital Publishing Consultancy and Training http://www.corbas.co.uk , +44 (0)7718 906817

On 3 February 2011 09:53, Nic Gibson <nicg@corbas.net> wrote: > I think there possibly needs to be a different set of decisions here. Right now, we have the TDG guidelines. Those make perfect sense for something that originates outside of the DocBook infrastructure as it were. What appears to be needed is a way to identify an official variant on DocBook in a way that makes it clear that it isn't DocBook but is an official and public variant. That is exactly what is covered by tdg :-) http://www.docbook.org/tdg51/en/html/ch05.html#s-notdocbook  There are three possible ways to identify this as far as I can see > > 1) A new root element > 2) A namespace for the new elements (what about the modified elements?) > 3) A new version > > I think that 3) is the least destructive. > >> Is website a fair comparison? > > I think it probably is. How is website 'identified'? I doubt this was raised when Norm (IIRC) developed website (and slides?) for his own use, then publicised them. website has a different document element, as does slides, just that they use a customization layer on top of docbook. Which may point to a similar route for db-pubs as being a previously trodden one? Customization for the schema/stylseheets, relying on the base infrastructure of docbook for support. Shouting "This is not docbook" is possibly 4 on your list Nic, as per tdg, but it doesn't get us very far in terms of usage and clarity when using docbook tools. With this logic, I could be swayed towards 1) above? regards -- Dave Pawson XSLT XSL-FO FAQ. Docbook FAQ. http://www.dpawson.co.uk

On 3 Feb 2011, at 10:37, Dave Pawson wrote: > On 3 February 2011 09:53, Nic Gibson <nicg@corbas.net> wrote: > >> I think there possibly needs to be a different set of decisions here. Right now, we have the TDG guidelines. Those make perfect sense for something that originates outside of the DocBook infrastructure as it were. What appears to be needed is a way to identify an official variant on DocBook in a way that makes it clear that it isn't DocBook but is an official and public variant. > > That is exactly what is covered by tdg :-) > http://www.docbook.org/tdg51/en/html/ch05.html#s-notdocbook > > I take your point :) By those guidelines we should be using a new version 'number' that looks something like: "5.0-extension publishers-1.0" (or possibly "5.0-variant publishers-1.0") I think that slightly misses the point that I'm trying to make though - DocBook Publishers has an official 'DocBook-ness' in an way that (say) the DocBook 4.3 variants I've created for a set of biochemistry texts didn't have - those were done for a specific publisher and had a public identifier that indicated that. Given that there are now two special purpose DocBook sub-committees, I'd like to see something that indicates that closer relationship with DocBook. Perhaps that's just wishful thinking on my part, though. > > There are three possible ways to identify this as far as I can see >> >> 1) A new root element >> 2) A namespace for the new elements (what about the modified elements?) >> 3) A new version >> >> I think that 3) is the least destructive. >> >>> Is website a fair comparison? >> >> I think it probably is. How is website 'identified'? > > I doubt this was raised when Norm (IIRC) developed website > (and slides?) for his own use, then publicised them. > > website has a different document element, as does slides, > just that they use a customization layer on top of docbook. > > Which may point to a similar route for db-pubs as being > a previously trodden one? > Customization for the schema/stylseheets, relying > on the base infrastructure of docbook for support. > > Shouting "This is not docbook" is possibly 4 on your list Nic, > as per tdg, but it doesn't get us very far in terms of usage > and clarity when using docbook tools. That's why I didn't add it - I don't see that it gets us anywhere useful. > > With this logic, I could be swayed towards 1) above? I'm not convinced that it gets us anywhere useful but I think that the precedent of website and slides is worth considering. cheers nic > > regards > > > -- > Dave Pawson > XSLT XSL-FO FAQ. > Docbook FAQ. > http://www.dpawson.co.uk > > --------------------------------------------------------------------- > 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 > -- Nic Gibson Corbas Consulting Digital Publishing Consultancy and Training http://www.corbas.co.uk , +44 (0)7718 906817

Dave, et al, The Publishers schema IS an official work of the DocBook TC, so the argument that "it's not DocBook" is incorrect. According to http://www.docbook.org/docs/howto/#cust-naming the version is NOT float value, nor an integer, but it is a version string. As the Publishers schema is not a true subset, but does extend some markup models, I think either extension or variant are appropriate. So again, I offer: "5.0-extension publishers-1.0" The namespace should not change, as it is officially docbook, and the stylesheets from the standard distribution should work on this schema (especially with the contributions from Nic!). Since website and slides are not official work products, I don't think it's a fair comparison for publishers. The spec has been approved, so the root element cannot be changed. It's more akin to simplified, except that content models are extended. Thanks and best regards, --Scott Scott Hudson Pelco by Schneider Electric United States API Strategy On 2/3/11 3:54 AM, "Nic Gibson" <nicg@corbas.net> wrote: > > On 3 Feb 2011, at 10:37, Dave Pawson wrote: > >> On 3 February 2011 09:53, Nic Gibson <nicg@corbas.net> wrote: >> >>> I think there possibly needs to be a different set of decisions here. Right >>> now, we have the TDG guidelines. Those make perfect sense for something that >>> originates outside of the DocBook infrastructure as it were. What appears to >>> be needed is a way to identify an official variant on DocBook in a way that >>> makes it clear that it isn't DocBook but is an official and public variant. >> >> That is exactly what is covered by tdg :-) >> http://www.docbook.org/tdg51/en/html/ch05.html#s-notdocbook >> >> > > I take your point :) > By those guidelines we should be using a new version 'number' that looks > something like: > > "5.0-extension publishers-1.0" > > (or possibly "5.0-variant publishers-1.0") > > I think that slightly misses the point that I'm trying to make though - > DocBook Publishers has an official 'DocBook-ness' in an way that (say) the > DocBook 4.3 variants I've created for a set of biochemistry texts didn't have > - those were done for a specific publisher and had a public identifier that > indicated that. > > Given that there are now two special purpose DocBook sub-committees, I'd like > to see something that indicates that closer relationship with DocBook. Perhaps > that's just wishful thinking on my part, though. > >> >> There are three possible ways to identify this as far as I can see >>> >>> 1) A new root element >>> 2) A namespace for the new elements (what about the modified elements?) >>> 3) A new version >>> >>> I think that 3) is the least destructive. >>> >>>> Is website a fair comparison? >>> >>> I think it probably is. How is website 'identified'? >> >> I doubt this was raised when Norm (IIRC) developed website >> (and slides?) for his own use, then publicised them. >> >> website has a different document element, as does slides, >> just that they use a customization layer on top of docbook. >> >> Which may point to a similar route for db-pubs as being >> a previously trodden one? > >> Customization for the schema/stylseheets, relying >> on the base infrastructure of docbook for support. >> >> Shouting "This is not docbook" is possibly 4 on your list Nic, >> as per tdg, but it doesn't get us very far in terms of usage >> and clarity when using docbook tools. > > That's why I didn't add it - I don't see that it gets us anywhere useful. > >> >> With this logic, I could be swayed towards 1) above? > > I'm not convinced that it gets us anywhere useful but I think that the > precedent of website and slides is worth considering. > > cheers > > nic > > >> >> regards >> >> >> -- >> Dave Pawson >> XSLT XSL-FO FAQ. >> Docbook FAQ. >> http://www.dpawson.co.uk >> >> --------------------------------------------------------------------- >> 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 >> > > -- > Nic Gibson > Corbas Consulting > Digital Publishing Consultancy and Training > http://www.corbas.co.uk , +44 (0)7718 906817 > > > > > > > > --------------------------------------------------------------------- > 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 > This transmission is intended only for use by the intended recipient(s). If you are not an intended recipient you should not read, disclose copy, circulate or in any other way use the information contained in this transmission. The information contained in this transmission may be confidential and/or privileged. If you have received this transmission in error, please notify the sender immediately and delete this transmission including any attachments.

Dave Pawson wrote: > I've always expected the version to be numeric Scott? That was never case with DocBook 5. See http://www.docbook.org/docs/howto/#cust-naming http://www.docbook.org/tdg5/en/html/ch05.html#s-notdocbook > For which TDG is clear. "Don't call it docbook" > Bit late now, but renaming the document element > to x-pubs, where x is book/article/... perhaps? Why to rename root element, it doesn't make sense. > Or simpler, just give it a clear / different name, > then use docbook ns etc? I think it is enough to call it DocBook Publishers or something like that and add version="5.0-variant publishers-1.0" to root element. (variant is better then extension, because some elements were removed) Jirka -- ------------------------------------------------------------------ Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz ------------------------------------------------------------------ Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing ------------------------------------------------------------------ OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member ------------------------------------------------------------------ OpenPGP digital signature

On 8 February 2011 13:15, Jirka Kosek <jirka@kosek.cz> wrote: > Dave Pawson wrote: > >> I've always expected the version to be numeric Scott? > > That was never case with DocBook 5. See > > http://www.docbook.org/docs/howto/#cust-naming > > http://www.docbook.org/tdg5/en/html/ch05.html#s-notdocbook > >> For which TDG is clear. "Don't call it docbook" >> Bit late now, but renaming the document element >> to x-pubs, where x is book/article/... perhaps? > > Why to rename root element, it doesn't make sense. My reasoning is that the user is going to be caught out? I'd like the processing (validation or styling) to point out 'this is not docbook', somehow. > >> Or simpler, just give it a clear / different name, >> then use docbook ns etc? > > I think it is enough to call it DocBook Publishers or something like > that and add version="5.0-variant publishers-1.0" to root element. > > (variant is better then extension, because some elements were removed) Which is fine for a user that understands that difference. How many do? IMHO it would be more 'friendly' for processing to make it very clear. We now have docbook Oasis docbook variants Unofficial docbook variants (webside, slides) and non docbook (my own, I changed one element) I'd like these to be clearly identified, somehow, to the user. regards -- Dave Pawson XSLT XSL-FO FAQ. Docbook FAQ. http://www.dpawson.co.uk

Dave Pawson wrote: > Which is fine for a user that understands that difference. > How many do? > > IMHO it would be more 'friendly' for processing to make > it very clear. > > We now have > docbook > Oasis docbook variants > Unofficial docbook variants (webside, slides) > and non docbook (my own, I changed one element) > > I'd like these to be clearly identified, somehow, to the user. You can: 1) manually assign schema 2) change name of root element 3) change namespace of elements 4) use version attribute Options 2) and 3) breaks existing toolchains, so they are no go. Option 1) doesn't universally work, because people might use different schemas (RELAX NG vs. XSD) caused by limitations in tools used. Option 4) seems as an optimal solution -- it doesn't break anything but can be used to locate appropriate schema. Jirka -- ------------------------------------------------------------------ Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz ------------------------------------------------------------------ Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing ------------------------------------------------------------------ OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member ------------------------------------------------------------------ OpenPGP digital signature

On 8 February 2011 16:18, Jirka Kosek <jirka@kosek.cz> wrote: > Dave Pawson wrote: >> I'd like these to be clearly identified, somehow, to the user. > > You can: > > 1) manually assign schema > 2) change name of root element > 3) change namespace of elements > 4) use version attribute > > Options 2) and 3) breaks existing toolchains, so they are no go. > > Option 1) doesn't universally work, because people might use different > schemas (RELAX NG vs. XSD) caused by limitations in tools used. > > Option 4) seems as an optimal solution -- it doesn't break anything but > can be used to locate appropriate schema. And still won't let the un-enlightened user know? Nothing in the validation says 'this is docbook and you're using dbpubs', or vice versa? To me that's something worthwhile doing. regards -- Dave Pawson XSLT XSL-FO FAQ. Docbook FAQ. http://www.dpawson.co.uk

Dave Pawson wrote: > And still won't let the un-enlightened user know? > > Nothing in the validation says 'this is docbook and you're using > dbpubs', or vice versa? Dave, maybe you should describe use case for this. For what it is good for? If some one has document which is instance of "publishers" then either this is also valid DocBook (if no additional publishers elements are used) or it is only valid against publishers schema because some publisher specific elements are used. Jirka -- ------------------------------------------------------------------ Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz ------------------------------------------------------------------ Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing ------------------------------------------------------------------ OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member ------------------------------------------------------------------ OpenPGP digital signature

On 8 February 2011 17:56, Jirka Kosek <jirka@kosek.cz> wrote: > Dave Pawson wrote: > >> And still won't let the un-enlightened user know? >> >> Nothing in the validation says 'this is docbook and you're using >> dbpubs', or vice versa? > > Dave, maybe you should describe use case for this. For what it is good for? > > If some one has document which is instance of "publishers" then either > this is also valid DocBook (if no additional publishers elements are > used) or it is only valid against publishers schema because some > publisher specific elements are used. So Mr ignorant creates an instance of the latter. Takes a liking to using dc:author for instance. Tries to validate against docbook and receives this funny error (which says nothing about version, or dbpubs....) What is he to make of that error? If some part of the processing reported that 'hey, this instance is dbpubs, you're using docbook' then he might be wiser. HTH -- Dave Pawson XSLT XSL-FO FAQ. Docbook FAQ. http://www.dpawson.co.uk

Dave Pawson wrote: > So Mr ignorant creates an instance of the latter. > Takes a liking to using dc:author for instance. > > Tries to validate against docbook and receives this funny error > (which says nothing about version, or dbpubs....) > What is he to make of that error? > > If some part of the processing reported that 'hey, this instance > is dbpubs, you're using docbook' then he might be wiser. It would be possible to add similar check into standard Schematron schema for DocBook -- it can report warning always when there is something special in version attribute. However I'm still not convinced it would be better then to do nothing in this case. Jirka -- ------------------------------------------------------------------ Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz ------------------------------------------------------------------ Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing ------------------------------------------------------------------ OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member ------------------------------------------------------------------ OpenPGP digital signature

On 8 Feb 2011, at 16:18, Jirka Kosek wrote: > Dave Pawson wrote: > >> Which is fine for a user that understands that difference. >> How many do? >> >> IMHO it would be more 'friendly' for processing to make >> it very clear. >> >> We now have >> docbook >> Oasis docbook variants >> Unofficial docbook variants (webside, slides) >> and non docbook (my own, I changed one element) >> >> I'd like these to be clearly identified, somehow, to the user. > > You can: > > 1) manually assign schema > 2) change name of root element > 3) change namespace of elements > 4) use version attribute > > Options 2) and 3) breaks existing toolchains, so they are no go. > > Option 1) doesn't universally work, because people might use different > schemas (RELAX NG vs. XSD) caused by limitations in tools used. > > Option 4) seems as an optimal solution -- it doesn't break anything but > can be used to locate appropriate schema. This is my gut feeling too - it's the least worrying approach. I think that Dave's "Oasis docbook variants" category is likely to need some clarification. The chances are, that over time there will be more of them. I'd like to see some way of identifying them (perhaps an 'official variant' component of the version string). When I asked the question in the first place I didn't realise it would lead to so much discussion! nic -- Nic Gibson Corbas Consulting Digital Publishing Consultancy and Training http://www.corbas.co.uk , +44 (0)7718 906817