Re: [docbook-tc] RE: [docbook] DocBook Technical Committee MeetingAgenda: 17 June 2009

[Scott Hudson <scott.hudson@flatironssolutions.com>]

Thanks for your comments Gershon!

The thought behind separating the resources from the structure is that 
it follows the IMS manifest model, where the resources can be flexibly 
managed apart from the structure, but still delivered in one complete 
package. This also allows the structure to be re-arranged without having 
to adjust the resources.

We don't want to "copy" DITA, but to enable capabilities beyond what 
DITA can provide. This is where the relationships is more powerful, IMO, 
than the reltable approach in DITA.

Best regards,

--Scott

Scott Hudson	
Senior XML Architect

+1 (303) 542-2146  |  Office
+1 (303) 332-1883  |  Cell
Scott.Hudson@flatironssolutions.com
==========================================
Flatirons Solutions
http://www.flatironssolutions.com




Gershon Joseph (gerjosep) wrote:
> Hi Larry,
>
> This is coming along nicely. I have some comments, many of which stem
> from DITA use cases that are likely to apply to our users too:
>
> - I like the use of xml:base on the wrapper <resources> element. I wish
> we had something like that in DITA ;-)
>
> - What's the reason <resources> and <resource> has an id? Do we have a
> use case for linking or otherwise referring to them>. Oh, I see, we
> reference them later from the <structure> markup. So I'm wondering why
> we need to separate out the resource inventory from the structure?
> What's the reasoning for not combining them (this is what DITA does, so
> that's why I'm asking). If we have good reasons for doing it this way,
> we need to document them clearly, since users coming into this will
> likely be coming in after studying the DITA map architecture. I'm OK
> with DocBook deviating if we have good reasons to do so, with the
> understanding that any deviation from DITA may cause user confusion that
> I'd like to mitigate via best practice articles and spec documentation.
> If we want to reference resources from the <structure> to the inventory,
> I think we'd need a <resource-group> wrapper element that contains a
> group of <resource> elements, possibly nested.
>
> - I'd like to suggest an element to represent the description of the
> referenced topic instead of using XML comments. In fact, I see the need
> for two elements:
> <navtitle> which would be optional, and is either the title of the
> referenced section (topic in DITA speak) or a title to be used in the
> navigation (e.g. TOC of the online TOC pane in HTML or online help). I'd
> like to see an attribute on <resource> that's used to set whether the
> processing takes the section title from the referenced section (default
> behavior) or uses the <navtitle> to override the referenced title (this
> is commonly done in online help).
> <section-description> that provides an optional description of the
> referenced section (the intent here is for someone reading the assembly
> to get an idea of the purpose of each referenced section; this would be
> useful when the title does not provide enough context or other
> information). DITA has a way to put the abstract or short description
> here (though I'm not sure what the processing expectation would be in
> this case).
>
> - Should we allow @role on <resource> in order to apply output or format
> specific rules at rendering time?
>
> - I assume one can nest resource inside resource, though I don't think
> this is shown.
>
> - I like the use of @grammar. We may need to flesh out processing
> expectations (or is this using standard foreign schema support we
> already have in DocBook and we don't expect anything more than that?)
>
> - Should <structure> have a required @renderas? In this example,
> "user.guide> does not. I expect the UG to be rendered to PDF, HTML and
> perhaps online help too. Can @renderas take multiple values? Would we
> separate these values with a space? I assume the idea is to submit this
> assembly to the rendering engine, and the rendering engine would produce
> the various outputs requested in the structure/@renderas -- am I
> correct? Maybe we should have a different attribute for this purpose,
> since @renderas also seems to be used to point to the DocBook element we
> want the resource to render as.
>
> Cheers,
> Gershon
>
>
>
> -----Original Message-----
> From: Rowland, Larry [mailto:larry.rowland@hp.com] 
> Sent: Wednesday, June 17, 2009 12:44 AM
> To: Bob Stayton; DocBook Technical Committee
> Cc: docbook@lists.oasis-open.org
> Subject: [docbook-tc] RE: [docbook] DocBook Technical Committee Meeting
> Agenda: 17 June 2009
>
> I have produced another sample of the assembly.  I am only trying to
> address the description of structure of various documents (a help
> system, a book, and a tutorial based on shared content from two
> different repositories).  The issue of relationships among content were
> perplexing enough that I decided it would be worth resolving the "how do
> I describe the documents" question first and then address the other.  I
> have not had time to get this out to the rest of the modular
> documentation group ahead of time, so they will be fresh to the
> discussion tomorrow, too.
>
> I took the issues we ran into with the last proposal and some off-line
> discussions to come up with a model that uses a structure wrapper with
> module children that can point at content.  Modules can accept module
> elements as children, to support the hierarchy.  Both elements can
> contain things like title and toc and info to allow controlling the
> structure of the document including the things like Tables of Content
> and indices along with document wide metadata.  I do not pretend to have
> a final content model, since I think the question of how much content a
> module can contain within the assembly is still to be discussed (the
> original proposal allowed text, but no markup), but I think this will
> allow us to discuss the questions more effectively.
>
> Sorry it is so late.  I have been dealing with a family emergency for
> the last couple of weeks.
>
> Best Regards,
> Larry Rowland
>
> We have not succeeded in answering all your questions.  The answers we
> have found only serve to raise a whole new set of questions. -- In some
> ways we are as confused as ever, but we believe we're now confused on a
> higher level and about more important things.
>
> -----Original Message-----
> From: Bob Stayton [mailto:bobs@sagehill.net]
> Sent: Tuesday, June 16, 2009 5:42 AM
> To: DocBook Technical Committee
> Cc: docbook@lists.oasis-open.org
> Subject: [docbook] DocBook Technical Committee Meeting Agenda: 17 June
> 2009
>
> DocBook Technical Committee Meeting Agenda: 17 June 2009
> =============================================================
>
> The DocBook Technical Committee will meet on Wednesday, 17 June 2009 at
> 01:00p EDT (10:00a PDT, 17:00GMT, 18:00BST, 19:00CEST, 02:00JST+,
> 022:30p India+) 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: 15 July 2009
> 4. Review of the agenda.
> 5. Review of open action items
>
>   a. Bob to organize TDG reading after names are fixed.
>
>   b. Jirka to add schema comparison table to DocBook 5.0 Transition
> Guide.
>
>   c. Norm to work with Mary to make Publishing Subcommittee
>      schema a Committee Working Draft.
>
>   d. Norm to work with Keith and Scott to update the OASIS committee
>      site to make the Publishing Subcommittee Working Draft
>      publicly available.
>
>   e. Norm to put the new backwards compatibility policy in the spec.
>
>   f. Norm to put the new backwards compatibility policy in the
>      reference documentation.
>
>   g. Norm will update 5.1 with changes to initializer
>      content model.
>
>   h. Norm to take a look at the inlines and make a proposal
>      regarding RFE 2791288.
>
> 6.  DocBook 5.0 standards update.
>
> 7.  Publishing Subcommittee report.
>
> 8. Using a map for modular DocBook.
>
> 9.  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 to be considered 
>       1679665  Add better support for modular documentation  
>       2770858  Add limited emphasis to ubiquitous inlines 
>       2791288  add quote to corpauthor and gui elements 
>
>
> -----
>
> [1] http://lists.oasis-open.org/archives/docbook-tc/200905/msg00009.html
>
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
>
>
> ---------------------------------------------------------------------
> 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 
>
>