OASIS DocBook TC2

Expand all | Collapse all

Re: [docbook-tc] Very rough proposal for DocBook transclusions

  • 1.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 15:25
    Jirka Kosek 


  • 2.  RE: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 16:06
    Thanks Jirka, I like the proposal.
    
    We actually looked at the duplicate ID problem in the past and came up 
    with some solutions that depended on the user making a choice.  It does 
    require the user to know the content well enough to make the choice, 
    but for our environment that was not an unreasonable model.
    
      1) Simplest: Strip the ID from the referenced element.  This works
         for the inline inclusion problem (that seems to be aimed at the
         same use-case that entities were aimed at).  It may not work for
         references to blocks of content, particularly if there are IDs 
         inside the block.
    
      2) Replace the ID of the referenced element with an ID provided on
         the referencing element.  Again, this does not handle content
         that has IDs included inside it, but it allows referencing the
         element (like an admonition that needs to be repeated in a document
         and also needs to have local references to it.  However, it can
         be extended as described in the next option.  We indicated this
         should be done by simple providing the ID on the referencing 
         element.
    
      3) Replace the ID of the referenced element with an ID provided on
         the referencing element AND use the new ID to prefix all IDs in
         the transcluded block.  This means you also have to modify
         references within the transcluded block that reference IDs in
         the block, but not references to IDs outside the block.  Building 
         the list of ID values that need to be processed and using it for 
         processing the references proved challenging in XSLT 1.0, but 
         straightforward in Java (I haven't tried in XSLT 2).  Once again, 
         we chose to trigger this by having an ID on the referencing element.
         If there are no IDs in the block, option 2 becomes a degenerate
         case of this one.
    
    The alternative to these three options was to pass through the ID on 
    the referenced element and do nothing to IDs inside it, which was not
    a problem if the block was only being included once, as opposed to
    being included repeatedly in a document.
    
    Both options 2 and 3 could be controlled by an attribute rather than by
    the presence of the ID, but the ID had to be provided anyway, so it
    didn't seem like too much of a stretch.  To deal with all four options
    it may be best to have an idpolicy attribute (probably with a default
    value of option 1, since inline use could become common as a replacement 
    for entities) to control this.  Not sure really, since policy 1 was in a 
    system that didn't have policy 2, so we ended up only having to deal with 
    either not modifying IDs or modifying them based on the ID attribute being 
    present.
    
    Regards,
    Larry
    
    


  • 3.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 17:44
    Rowland, Larry wrote:
    
    > We actually looked at the duplicate ID problem in the past and came up 
    > with some solutions that depended on the user making a choice.  It does 
    > require the user to know the content well enough to make the choice, 
    > but for our environment that was not an unreasonable model.
    > 
    >   1) Simplest: Strip the ID from the referenced element.  This works
    >      for the inline inclusion problem (that seems to be aimed at the
    >      same use-case that entities were aimed at).  It may not work for
    >      references to blocks of content, particularly if there are IDs 
    >      inside the block.
    
    Actually this shouldn't be necessary with my current proposal, because
    


  • 4.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-29-2010 11:02

    Attachment(s)



  • 5.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-29-2010 11:56

    Attachment(s)



  • 6.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 08-02-2010 14:58
    Jirka Kosek wrote:
    
    > I'm also attaching sample files and very sketchy XSLT 2.0 based
    > transclusion implementation if anyone is interested.
    
    I have improved this transclusions implementation slightly, the actual
    code is avaiable at:
    
    http://github.com/docbook/xslt20-stylesheets/blob/master/stylesheets/base/preprocess/15-transclude.xsl
    
    Also I have integrated code into XSLT 2.0 stylesheets
    (http://github.com/docbook/xslt20-stylesheets) so if you want to perform
    transclusions during document processing it is enough to specify
    "preprocess=transclude" parameter when invoking  transformation and
    stylesheet will handle rest for you.
    
    			Jirka
    
    -- 
    ------------------------------------------------------------------
      Jirka Kosek      e-mail: jirka@kosek.cz      http://xmlguru.cz
    ------------------------------------------------------------------
           Professional XML consulting and training services
      DocBook customization, custom XSLT/XSL-FO document processing
    ------------------------------------------------------------------
     OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
    ------------------------------------------------------------------
    
    


  • 7.  RE: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 08-09-2010 12:54
    Hi Jirka,
    
    I finally had time to catch up on this thread. Thanks for the progressively better drafts.
    
    I'm pleased to see the @name attribute replace the element content. I do believe this is a better architecture.
    
    With conditional transclusion, or transclusion of content that contains conditions, I think we need to state whether processors first resovle the conditions and then perform the transclusion, or first transclude and then resolve the conditions. In DITA we see some use cases where the order in which these things are done results in a different result, but we didn't catch this in time to say anything normative about it. I'd like to hope we can address this processing order issue in DocBook out the door in order to ensure different processors result give the same results. I know Eliot Kimber had some use caes in DITA that demonstrated the issue. I'll ask him offline for pointers to those examples so I can provide some examples marked up in DocBook we can use to test and document this. I'd like to see examples 14 and 15 be followed by a more complex exmaple that demonstrates the different result depending on processing order, so that we can also determine which order should be normative and correct per the DocBook spec.
    
    In Procedure 1, Step 2, is the circular link to Step 2 correct? I think we mean to continue with Step 3, unless I'm missing something. Or is the idea to then try step 2 again but further back up the XPath ladder? (IOW if the closest 


  • 8.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 08-09-2010 17:21
    Gershon Joseph (gerjosep) wrote:
    
    > With conditional transclusion, or transclusion of content that
    > contains conditions, I think we need to state whether processors
    > first resovle the conditions and then perform the transclusion, or
    > first transclude and then resolve the conditions. 
    
    Yes, indeed. I postponed definition of this until we are happy with the
    core transclusion functionality.
    
    I think that natural would be to resolve conditions on ref and def
    elements during transclusion and all other conditions after
    transclusions are done.
    
    > In DITA we see some
    > use cases where the order in which these things are done results in a
    > different result, but we didn't catch this in time to say anything
    > normative about it. I'd like to hope we can address this processing
    > order issue in DocBook out the door in order to ensure different
    > processors result give the same results. I know Eliot Kimber had some
    > use caes in DITA that demonstrated the issue. I'll ask him offline
    > for pointers to those examples so I can provide some examples marked
    > up in DocBook we can use to test and document this.
    
    That would be great.
    
    > I'd like to see
    > examples 14 and 15 be followed by a more complex exmaple that
    > demonstrates the different result depending on processing order, so
    > that we can also determine which order should be normative and
    > correct per the DocBook spec.
    
    OK, I will add this to my TODO list.
    
    > In Procedure 1, Step 2, is the circular link to Step 2 correct? I
    > think we mean to continue with Step 3, unless I'm missing something.
    > Or is the idea to then try step 2 again but further back up the XPath
    > ladder? 
    
    There is link from Step 2 to Step 1.
    
    > I'm wondering whether we should use @linkscope or rather call it
    > @refscope since it's scoping the 


  • 9.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-29-2010 11:02
    [Resending through working SMTP server...]
    Rowland, Larry wrote:
    
    >   1) Simplest: Strip the ID from the referenced element.  This works
    >      for the inline inclusion problem (that seems to be aimed at the
    >      same use-case that entities were aimed at).  It may not work for
    >      references to blocks of content, particularly if there are IDs 
    >      inside the block.
    
    In the latest proposal this is possible by specifying
    
    


  • 10.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-29-2010 11:50
    Rowland, Larry wrote:
    
    >   1) Simplest: Strip the ID from the referenced element.  This works
    >      for the inline inclusion problem (that seems to be aimed at the
    >      same use-case that entities were aimed at).  It may not work for
    >      references to blocks of content, particularly if there are IDs 
    >      inside the block.
    
    In the latest proposal this is possible by specifying
    
    


  • 11.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 16:24
    Norman Walsh wrote:
    > Jirka Kosek 


  • 12.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 16:39
    Two comments from me Jirka.
    I'm not entirely happy about driving docbook markup by todays tools
    and their capability. I think the attribute version seems 'right'.
    
    What purpose does 


  • 13.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 17:23
    Dave Pawson wrote:
    
    > I'm not entirely happy about driving docbook markup by todays tools
    > and their capability. I think the attribute version seems 'right'.
    
    As I have already said I have no strong preference on this. Using
    element content seemed more convenient for me.
    
    > What purpose does 


  • 14.  Re: [docbook-tc] Very rough proposal for DocBook transclusions

    Posted 07-21-2010 17:36
    On 21 July 2010 18:22, Jirka Kosek