Fw: Slides schema and assembly investigation (action item b)

Larry asked me to post this to the Committee as he is having 
trouble posting.

 

Bob Stayton
Sagehill Enterprises


From: Rowland, Larry 

Sent: Tuesday, July 16, 2013 7:10 PM

To: Bob 
Stayton ; DocBook Technical Committee 

Subject: Slides schema and assembly investigation (action item 
b)

I 
have spent some time working on analyzing the new slides schema that was 
developed during the Google Summer of Code, using the artifacts from the report 
on project that were posted here:

 

    http://www.google-melange.com/gsoc/project/google/gsoc2012/gabor/63002

 

I 
also downloaded the most recent version of the XSL transforms (docbook-xsl-1.78.1.zip) 
to work with producing documents based on the transform.

 

For 
what I am considering the most basic application for the slides schema and 
transforms (simply generating a set of slides for a presentation) I do not find 
any real advantage of using the assembly mechanism for producing the slides. 
 In fact, the loss of the ability to include content in the assembly that 
was decided upon in late 2011 would make the process of defining of defining a 
simple set of slides difficult if an assembly was brought into the 
process.

 

In 
more complex situations, such as multiple slide sets that are all about a common 
topic (such as might be used in training or in a set of presentations based on a 
technical paper) the introduction of an assembly would be more 
valuable.

 

For 
example, given a set of technical papers on DocBook assembly processing aimed at 
two different conferences, on like SIGDOC and the other like Extreme Markup 
Languages.  While there is a common core of information that would be of 
use in both venues, but the level of complexity and exact content would be 
different for the different venues.  This could lead to a set of resources 
that might be organized like this:

 

  <resources 
xml:base="http://repo1/slides/assemblies">
  
  <description>Slide 
Content</description>
  
  <resource 
href="" 
xml:id="intro.users">
  
    <description>Intro 
slide for overview</description>
  
  </resource>
  
  <resource 
href="" 
xml:id="intro.technical">
  
    <description>Intro 
slide for technical paper</description>
  
  </resource>
  
  ...
  </resources>
  
<resources 
xml:base="http://repo1/general-resources">
  
  <description>General 
resources for presentations</description>
  
  <resource 
href="" 
xml:id="ascii.table">
  
    <description>ASCII 
Table</description>
  
  </resource>
  
  <resource 
href="" 
xml:id="unicode.base.table">
  
    <description>ASCII 
Table</description>
  
  </resource>
  
  ...
  </resources>
  
<resources 
xml:base="file:///users/lrr/Documents/Papers/DocBook-Assemblies">
  
  <description>Technical 
Paper Elements</description>
  
  <resource 
href="" 
xml:id="proj.overview">
  
    <description>Project 
Description Overview</description>
  
  </resource>
  
  <resource 
href="" 
xml:id="proj.details">
  
    <description>Project 
description Exposition</description>
  
  </resource>
  
  ...
  </resources>

 

where the first resource 
collection is content prepared specifically for slides, either complete slides 
or portions of slides to be combined by module children of a module that 
represents a slide, the second resource collection is common content that is of 
more general use across projects, and the final resource collection is the 
content that is aimed at producing the papers, themselves.  The hrefs in 
the technical resource collection might come from inside files that might 
represent sections in the papers, with different sections assembled into the 
different papers.

 

Then, the four documents (two 
slide sets and two papers) would be represented by structure elements that could 
pick and choose from the resource collections.

 

  <structure 
renderas="slides" xml:id="simple.slides" >
    <info>
      <title>Overview (SIGDOC) Presentation</title>
    </info>
    <module 
renderas="foil" 
resourceref="intro.users"/>
    <module 
renderas="foil" 
resourceref="proj.overview"/>
    ....
  </structure>
  
  <structure 
renderas="slides" xml:id="technical.presentation">
    <info>
      <title>Technical Presentation</title>
    </info>
    <module 
renderas="foil" 
resourceref="intro.technical"/>
    <module 
renderas="foilgroup">
      <module 
renderas="foil">
        <module 
resourceref="unicode.processing" 
contentonly="true"/>
        <module 
renderas="handoutnotes" 
resourceref="unicode.base.table"
          
contentonly="true"/>
      </module>
      
...
    </module>
    ...
  
</structure>
  
  
<structure 
renderas="article" xml:id="using.assemblies">
    <merge>
      <title>Using Assemblies to Handle Complex 
Documents</title>
    
</merge>
    <module></module>
    
...
  </structure>
  

  <structure renderas="article" 
xml:id="processing.assemblies">
    <merge>
      <title>Processing Assemblies in DocBook</title>
      <subtitle>A Practical Application 
of
        Modern Transform Technology</subtitle>
    </merge>
    <module></module>
    
...
  </structure>

 

I 
will not attempt to tell people in this group how to put together an article. 
 The two slide sets represent a simple structure of foils for the "How to 
Use Assemblies" and a much more complex slide presentation for the technical 
audience.  IDs are provided on the structures to allow processing different 
structures independently by indicating the structure to process to the 
transform.

 

There were a couple of issues 
that came up with the schema and with processing them using XSLTPROC, which was 
the recommended processor.

 

  1. The assembly above 
would not have produced a valid slides structure.  The speakernote and 
handoutnote elements are required and cannot be empty.  I pretty much never 
use speaker notes, and seldom provide handout notes (I tend to provide more of 
an article style document when I do slides -- I don't think notes about slides 
are the best approach).  I think they should be optional.  They are 
allowed as children of the slides element, but have to be first.  It is not 
clear to me what they mean at this level and how they merge with the other 
elements.

 

 2. I tried rendering 
the slides using plain.xsl, slidy.xsl, and s5.xsl, after I figured out I needed 
to drop that directory into the regular DocBook XSL structure.  The 
transforms do not work.  I patched them and got them to work, and the 
results did to appear to work (I spent about two hours trying various patches to 
the resulting files, but they all produce an empty body element in DOM when I 
opened HTML debugger. I know our committee does not own the transforms, but we 
should pass this on to the maintainers.  There may have been some 
incompatibility between the version of the DocBook transforms I was working with 
and the one that the extension was based on.  The instructions say to look 
at the rendered version of a file in the doc directory, but the rendered version 
isn't there.  It wasn't impossible to get the transforms working, but a 
simple, text file with instructions on what to do would be helpful when this is 
packaged.

 

Definitely interesting. 
 I may stick with Slidy for a while ;-)

 

LRR

 

On 
Jul 11, 2013, at 5:11 PM, "Rowland, Larry" <> 
wrote:

-----Original 
Message-----
From: Bob Stayton [mailto:] 
Sent: Thursday, July 11, 2013 
1:02 PM
To: Norm Walsh; Rowland, Larry; Dick Hamilton; Scott Hudson; Jirka 
Kosek; Bob Stayton
Subject: DocBook TC action item reminders

If you 
are getting this mail, then you have an 
action item in the list below, and 
this is your friendly
reminder service before the next meeting.
If you 
have already completed your action items, then
good for you!

Next 
meeting is Wednesday 17 July 2013.

Actions:

 a.  Norm to 
publish an XSD for 5.1 when it is finished.

 b.  Larry to try 
mapping slides to assembly.

 c.  Norm to produce a DocBook 5.1 
candidate release.

 d.  Norm to follow up on RFE 3491860 
license tag

 e.  Norm to add result element to DocBook 5.1 
schema.

 f.  Dick to fix the DocBook5 conversion stylesheet on 
SourceForge.

 g.  Bob to review Dick's fixes to the conversion 
stylesheet.

 h.  Norm to pull the rdfalite schema together as a 
non-normative
     release 
candidate.

 i.  Norm to talk to OASIS about some examples 
of
     internal published items, such as draft 
specs and
     non-normative customization 
layers.

 j.  Jirka and Scott to investigate table 
captioning.

 k.  Norm to implement index "see under" and "see 
also under".

Bob Stayton
Sagehill Enterprises