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

["Rowland, Larry" <larry.rowland@hp.com>]

Hello Gershon and Bob,

Thanks to both of you for the comments.  I was hoping to get some
discussion of this going on after the last meeting, but I suspect
there was too much churn at that point.

Bob is correct about the indirection provided by the use of the
resource collection; the idea is to allow the structure element
to be stable while switching the resources.  In fact, the original
proposal actually describes an inheritance model that I did not
try to demonstrate in this sample (I guess I was trying to get the
simple "what is a document" problem resolved before getting into
the sophisticated aspects of the model).  I suspect the folks from
Flatiron Solutions have run into enough of the issues with DITA's
hard coded links to realize that this would be an improvement.

I agree that renderas may well be overloaded now and need to be
renamed.  In the beginning I think the goal was to use as much
of the DocBook grammar as we could -- since we have moved on
from that the names of the attributes are up for discussion, too.
I suspect we actually need renderas that would be exactly what
renderas does, as well as something like renderto that can do
what the compound renderas content does when I am specifying a
filename as well as the output render model.

Bob, you are right about the resources being in a different file.
This assembly would probably be broken up across multiple files,
since the real definitions of the documents would be large enough
to make a single file clumsy.

Gershon, I agree about additional elements.  The title element is
allowed as a child of module and I was assuming that if it was
present it would override the title of the content that was being
referenced.  It may be desirable to make it explicit.  I am also
allowing the info element as a child of module (although I don't
think I showed that), which could be used to provide an abstract
element, or extended to allow a description element.  I was using
comments to provide the description of the referenced elements
(although I did not do a complete job of that) but I understand
that some content management systems do not allow free storage
of comments, so an element would be good for the section
description, although I would favor something more generic than
section-description, which assumes I am pulling in a section;
there are likely times I would be pulling in more or less (a
chapter or an admonition).

I am not sure about @role on a resource, since I think of it as
more of a non-formatted chunk of source -- I would expect the
structure to be where the @role would be applied rather than the
resource, but it would probably be best to allow the DocBook
common attributes on resource and resources with the expectation
that our users will surprise us with how flexibly they apply
the markup.

The assumption was that an @grammar attribute was a sign to use
a transform at build time to convert from the source grammar to
DocBook before passing to the final output (we actually have
something similar to that in our production system that allows
on-the-fly conversion from some specialized grammars we use into
our main production grammar.  I agree the processing expectations
need to be made clear.

Bob is right about the nested resources.  It was perceived as a
flat list.  However, multiple resources elements are allowed in
the same assembly, so that may server the same purpose as the
resource-group -- I am not sure if another level of nesting is
required, but if so, we can certainly provide a mechanism for
it.

I think renderas is not the best choice for what to use.  We are
actually identifying the type of document.  The assumption was that
the book was the default type of document and that it didn't need
the attribute telling what it was, while help system and tutorial
needed to be explicit.  The renderas was a bad choice for the
structure level attribute, since it really is more conceptual
(this is a book, this is a help system) and there may be multiple
ways to render it that make sense (PDF and HTML for books, CHM and
Oracle Help for Java for help system, etc.) so we need a class or
type attribute.

Bob, I am not sure about the nested assembly elements; the
original proposal went into a lot of detail about assemblies
and how they behave and may have covered that -- I was trying
for the first case of "can I reuse content from referenced
repositories" and didn't get into the more sophisticated uses.

I think I have covered everything, but there was a lot of comment.
If I missed anything, let me know and I will try to cover it.
We need to rewrite the original proposal using the new markup,
since it covers a number of things that were brought up.

Thanks again for all the discussion.  Given the delay of today's
meeting, we may be able to have a fully fleshed out sample before
the next meeting if we can keep this discussion going.

Best Regards,
Larry Rowland



-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Wednesday, June 17, 2009 7:55 AM
To: Gershon Joseph (gerjosep); Rowland, Larry; DocBook Technical Committee
Cc: docbook@lists.oasis-open.org
Subject: Re: [docbook-tc] RE: [docbook] DocBook Technical Committee Meeting Agenda: 17 June 2009

Hi Gershon,
Regarding <resources> and <resource>, my understanding (Larry, please
correct me if I get this wrong) is that <resources> contains a flat list of
potential content that may be referenced in the <structure> element.  Think
of it as a manifest or inventory, not necessarily all included in the
output.  Separating the resource list from the structure solves a big
problem I have had with DITA, which is the inclusion of hard-coded filenames
and paths in maps.  When you move a file in DITA, you are faced with editing
all your maps to relocate the file.  One level of indirection is very
helpful.  I could see putting the resources element in a
separately-maintained file that is referenced into an assembly by XInclude
or system entity.   Then you only need to edit a changed pathname in one
place, since all other references are by xml:id.  You could also substitute
a different resources file to build a translated document with the same
structure.

All of the structure is defined in the <structure> element with nesting
<module> elements.  Nesting <resource> elements is not necessary.  The map
is in <structure> not <resources>.

This latest example shows that <structure> elements can nest.  In the
structure with xml:id="user.guide", there is a module with
resourceref="help.tutorial", where "help.tutorial" is the xml:id of another
structure.  I wonder if referencing a nested assembly makes sense as well,
since an assembly would contain its own list of resources.  That would
require an external link mechanism, as an assembly element would not contain
another assembly and its xml:id.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message -----
From: "Gershon Joseph (gerjosep)" <gerjosep@cisco.com>
To: "Rowland, Larry" <larry.rowland@hp.com>; "Bob Stayton"
<bobs@sagehill.net>; "DocBook Technical Committee"
<docbook-tc@lists.oasis-open.org>
Cc: <docbook@lists.oasis-open.org>
Sent: Wednesday, June 17, 2009 5:15 AM
Subject: RE: [docbook-tc] RE: [docbook] DocBook Technical Committee Meeting
Agenda: 17 June 2009


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