DocBook Technical Committee Meeting Minutes: 21 October 2009

[Norman Walsh <ndw@nwalsh.com>]

> DocBook Technical Committee Meeting Agenda: 21 October 2009
> =============================================================
> 
> The DocBook Technical Committee met on Wednesday, 21 October 2009
>
> 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

Present: Scott, Larry, Jirka, Corey, Norm, Bob

Scribe: Norm

> 2. Accepting the minutes [1] of the previous meeting.

Accepted.

> 3. Next meeting: 18 November 2009

No regrets heard.

> 4. Review of the agenda.

Scott: Please add the request to form an eLearning TC

For next month:

  Dealing with corss references in modular documentation, see
  http://lists.oasis-open.org/archives/docbook-tc/200910/msg00006.html  

> 5. Review of open action items
> 
>   a. Norm to put the new backwards compatibility policy in the spec.
> 
>   b. Norm to put the new backwards compatibility policy in the
>      reference documentation.
> 
>   c. Norm to take a look at the inlines and make a proposal
>      regarding RFE 2791288.
> 
>   d. Norm to reply to RFE 2820947 (transclusion) with the
>      committee's concerns (see the minutes).

Continued: a-d

>   e. Bob to develop a stylesheet to transform an assembly
>      into a document.

Completed.

>   f. Larry to revise the assembly sample and schema based on comments.

Completed.

>   g. Gershon to develop a reltable example.

Continued.

> 6.  DocBook 5.0 standards update.

We're within 12 of having all the votes we need!

Everyone look through the list and find people you know. Send them
private encouragement to vote ("Yes" of course :-) and then send the
list of contacts to the docbook-tc list so we can minimize overlap.

> 7.  New edition of DocBook: The Definitive Guide

Not a lot of progress. January looks more likely than December, but
we're still working on it.

> 8.  Publishing Subcommittee report.

Scott: We went through final review comments period. What came out
that we need to add documentation in the schema and create a DTD
version. The SC has decided to make those changes, after which time
it'll require another 15 day review period.

Scott The comments are in the schema, but I can't create a DTD using
the tools.

Norm: Yeah, the tools for that are pretty awful.

Some discussion. Scott will try to use the XSLT simplification tools
that are part of the main distribution process.

> 8b. Create an eLearning TC

See: http://lists.oasis-open.org/archives/docbook-tc/200910/msg00017.html

Scott summarizes. With assembly and topics coming, DocBook is an even
better fit for the eLearning/training paradigm.

A DocBook to SCORM conversion utility has already been developed in
the community.

Larry: I think this is a good idea. The changes we're making for
modular DocBook make this an ideal time to embark on this effort.

Scott: One comment that I received was that this might compete with
the DITA eLearning specialization. But I think that's OK, DITA isn't
the only game in town.

Proposal: The DocBook TC endorses the formation of an eLearning
subcommittee under the charter proposed by Scott.

Accepted with no objections.

> 9.  Modular DocBook.

Larry: I've been responding to comments from people. I've added a
default output format to the structure element that would apply to its
children. I won't repeat everything that we discussed at the last
telcon.

Larry: When I added the default output format to structure, I needed
some way to say "don't render this" and I may have overloaded
renderas. On line 259 of the file, I have an output statement with two
output formats and a renderas of "norender".

[[ Some discussion of the example in the assembly file. ]]

Some sentiment that using renderas="norender" is abuse of the renderas
attribute and should be changed.

Although not rendering in some formats is a kind of filtering, it
seems not to be one of the normal effectivity attribute so filtering
doesn't apply? Not complete agreement.

Norm ponders the use of more complex XPath evaluation to simplify
authoring.

Consensus seems to come back to adding a new attribute to the output
element that indicates that the content should be suppressed.

Possible names: omitoutput, discard, suppress

Straw poll, vote for up to two:

omitoutput : 
discard    : 2
suppress   : 3

Is there anyone who cannot live with "suppress"?

Proposal: Add a suppress attribute to output, if suppress=true (or 1) then
the output is not rendered.

Accepted.

(In addition, Norm suggests removing "output" from the attribute names
on the <output> element.)

Additional discussion about the use of grammer= on line 317. Conclusion:
change grammer= on that line to transform= and add it to the transforms
section at the bottom (renamed from grammartransforms):

  <module resourceref="help.tutorial">
    <output outputformat="helpsystem" outputfile="xidi-help.tutorial"
            grammar="tutorial"/>
    ...
  </module>
  ...
  <grammartransforms xml:base="file:///opt/xidi/util/grammartransforms">
    <transform grammar="dita" fileref="dita2docbook.xsl"/>
    <transform grammar="tutorial" fileref="docbook2tutorial.xsl"/>
  </grammartransforms>

Becomes:

  <module resourceref="help.tutorial">
    <output outputformat="helpsystem" outputfile="xidi-help.tutorial"
            name="tutorial"/>
    ...
  </module>
  ...
  <transforms xml:base="file:///opt/xidi/util/transforms">
    <transform grammar="dita" fileref="dita2docbook.xsl"/>
    <transform name="tutorial" fileref="docbook2tutorial.xsl"/>
  </transforms>

Bob encourages everyone to try out the transform stylesheet that he
supplied which generates an assembly file for an existing document.

Jirka suggests that perhaps the assembly elements should be in a
different namespace.

Norm agrees that its worth considering but worries about the fact that
authors would have to switch back and forth between the assembly
namespace and the docbook namespace for content.

Bob wonders if this is really necessary? It would definitely
complicate things.

Jirka isn't sure, just thinks it's worth considering.

Larry raises questions about how much simplicity and defaulting should
be allowed. We want to make sure that we're optimizing for what we're
trying to do. Short term optimization may not be valuable in the long
run.

> 10. Add topic element (RFE #2820190).

We have a design, but we're leaving this open until we're a little
farther along.

> 11.  Review of Requests for Enhancement

Postponed until next meetings.

> [1] http://lists.oasis-open.org/archives/docbook-tc/200909/msg00005.html

12. Any other business?

None heard. Adjourned.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | If today was a fish, I'd throw it
http://www.oasis-open.org/docbook/ | back in.
Chair, DocBook Technical Committee |

PGP signature