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

["Bob Stayton" <bobs@sagehill.net>]

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