RE: [docbook-apps] endnotes section in ePub

[Jason Zech <zech@loyolapress.com>]

Thanks again, Bob. I've managed to get it up and running, and it looks great. 

There is one issue left for me to resolve: by default the footnotes/endnotes are creating links using only IDs (since it presumes you'll be linking within the same doc), but in epub with endnotes, the links need to go across different HTML files. I've managed to fix this in the links TO the endnotes page (just added endnotes filename to the href attribute, since the footnotes will always lead OUT to the same endnotes file). 

  <xsl:template match="d:footnote">
...
<a id="{$name}" href="endnotes.html{$href}"> 

What I'm unable to do now is figure out how to have the processor generate the HREF for the returning links so that it includes the appropriate filename before the #id. Any advice? I can't seem to find a variable to plug in that carries the filename. Am I going in the right direction here?

<xsl:template match="*" mode="footnote.body.number">
  <xsl:variable name="name">
    <xsl:text>ftn.</xsl:text>
    <xsl:call-template name="object.id">
      <xsl:with-param name="object" select="ancestor::d:footnote"/>
    </xsl:call-template>
  </xsl:variable>
  <xsl:variable name="href">
    <xsl:text>#</xsl:text>
    <xsl:call-template name="object.id">
      <xsl:with-param name="object" select="ancestor::d:footnote"/>
    </xsl:call-template>
  </xsl:variable>
  <xsl:variable name="footnote.mark">
    <sup>
      <xsl:text>[</xsl:text>
      <a id="{$name}" href="{$href}">
        <xsl:apply-templates select="." mode="class.attribute"/>
        <xsl:apply-templates select="ancestor::d:footnote" mode="footnote.number"/>
      </a>
      <xsl:text>]</xsl:text>
    </sup>
  </xsl:variable>

  <xsl:variable name="html">
    <xsl:apply-templates select="."/>
  </xsl:variable>

  <xsl:choose>
    <xsl:when test="$exsl.node.set.available != 0">
      <xsl:variable name="html-nodes" select="exsl:node-set($html)"/>
      <xsl:choose>
        <xsl:when test="$html-nodes//p">
          <xsl:apply-templates select="$html-nodes" mode="insert.html.p">
            <xsl:with-param name="mark" select="$footnote.mark"/>
          </xsl:apply-templates>
        </xsl:when>
        <xsl:otherwise>
          <xsl:apply-templates select="$html-nodes" mode="insert.html.text">
            <xsl:with-param name="mark" select="$footnote.mark"/>
          </xsl:apply-templates>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:when>
    <xsl:otherwise>
      <xsl:copy-of select="$html"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>


-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net] 
Sent: Monday, July 18, 2011 5:22 PM
To: Jason Zech; Robert Nagle
Cc: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] endnotes section in ePub

Hi Jason,
Here is a quick summary of an approach, untested.

1.  You can start by copying the template with match="d:appendix" from component.xsl 
to your customization layer and changing the match attribute to add the role 
qualifier.  That template will give you the basic elements and title processing.

2.  Replace <xsl:apply-templates/> with <xsl:call-template name="process.endnotes"/>

3. Copy the template named 'process.footnotes' from footnote.xsl to your 
customization, renaming it to 'process.endnotes'.

4.  Modify process.endnotes to replace:

<xsl:variable name="footnotes" select=".//d:footnote"/>

with:

<xsl:variable name="footnotes" select="//d:footnote"/>

Removing the leading dot in the select statement converts it from selecting footnotes 
only as descendants of the current element to descendants of the root element.

I didn't have a chance to test this, but it should get you started.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Jason Zech" <zech@loyolapress.com>
To: "Bob Stayton" <bobs@sagehill.net>; "Robert Nagle" <idiotprogrammer@gmail.com>
Cc: <docbook-apps@lists.oasis-open.org>
Sent: Monday, July 18, 2011 12:27 PM
Subject: RE: [docbook-apps] endnotes section in ePub


Hi all,

Thanks, Bob, for the instructions, and thanks Robert for asking good questions of 
clarification.

The priority issue makes perfect sense to me, and I've built out a series of 
stylesheets as described (I already had a custom layer importing epub/docbook.xsl, so 
I just pasted epub/docbook.xsl into that and imported the CustomEpubFormat.xsl instead 
of docbook.xsl). Everything seems to process fine without me having tackled the issue 
of how to gather those footnotes and dump them into this appendix I have created.

I'm a little stumped, though, on the more mundane task of figuring out how output my 
footnotes into this appendix. Can anyone provide a little advice or a resource that 
might help me get started with filling out the [format the content of the special 
appendix] portion of this question?

Again, the directions in Bob's book for customizing print footnotes to endnotes 
doesn't seem to translate into the way the XHTML-1_1 style sheets are structured.

Any help would be greatly appreciated.

Jason

-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Monday, July 11, 2011 3:11 PM
To: Robert Nagle
Cc: docbook-apps@lists.oasis-open.org; Jason Zech
Subject: Re: [docbook-apps] endnotes section in ePub

Well, that looks like it will be a problem.  Here is the import sequence (highest
priority first):

1. YourCustomization.xsl,
    which xsl:imports:
2. epub/docbook.xsl,
    which xsl:includes chunk-code.xsl (element chunking templates)
    and which xsl:imports:
3. xhtml-1_1/docbook.xsl (element formatting templates) and xhtml-1_1/chunk-common.xsl
(utility chunking templates)

Note that epub/docbook.xsl  *includes* chunk-code.xsl, which is not import but instead
puts the included templates at the same import level as those in epub/docbook.xsl
(level 2).

Let's say you put a template like this in YourCustomization.xsl:

<xsl:template match="d:appendix[@role = 'endnotes']">
   [format the content of the special appendix]

When your stylesheet processes the appendix element, the best match is the highest
import template which is your custom one at level 1, and so it will proceed with
creating the formatted list of footnote entries.  But that's wrong, because there is
no chunked HTML wrapper for that formatted content to be placed into.  I suspect that
formatted content would be sent to standard output instead of to any file.

What you would like to do is have the XSLT processor select the chunking template from
Level 2, and apply formats from Level 1.  There is no way for you to write such a
template for your customization layer.

I can see that the stock epub stylesheet should be restructured to better support
customization.  With the current version, I think you would have to do this:

a.  Create a new stylesheet module to customize the formatting of content,  perhaps
named CustomEpubFormat.xsl.

b.  In CustomEpubFormat.xsl, add xsl:import href="path-to/xhtml-1_1/docbook.xsl", and
add any templates to customize element formatting, such as the one for endnotes.

c.  Copy the epub/docbook.xsl file to a new filename like CustomEpubChunk.xsl.

d.  In CustomEpubChunk.xsl, change the first xsl:import to:
      <xsl:import href="CustomEpubFormat.xsl"/> (instead of ../xhtml-1_1/docbook.xsl)
   And leave the rest of it alone.

Now process your document with CustomEpubChunk.xsl.  When the appendix is encountered,
the matching templates with the highest import precedence is the stock appendix
chunking template (in chunk-code.xsl which is xsl:included in CustomEpubChunk.xsl).
So that template is applied and will create the chunk wrapper for the appendix, and
then apply xsl:apply-imports.  When it does apply imports, the processor will pass
over any templates at Level 1 and look in Levels 2 and below.  So it looks in
CustomEpubFormat.xsl and finds your custom template for formatting the special
appendix.  For all other elements that are not customized, it will fall further in the
import sequence to ../xhtml-1_1/docbook.xsl to handle the formatting.  That should
work.

The problem with this customization is that epub/docbook.xsl has almost 1700 lines of
code which must be copied to CustomEpubChunk.xsl.  I don't like having to copy so much
code for no purpose.  When I rewrite this, I'll move everything but the imports and
includes to a separate stylesheet module that can be included.  That would make it
easier to insert a customization into the import sequence without having to copy over
all those templates in epub/docbook.xsl

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Robert Nagle" <idiotprogrammer@gmail.com>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: <docbook-apps@lists.oasis-open.org>; "Jason Zech" <zech@loyolapress.com>
Sent: Monday, July 11, 2011 10:51 AM
Subject: Re: [docbook-apps] endnotes section in ePub


Sorry, just one more thing.

What if you are calling the epub/docbook.xsl file?

I'm not at a desk with my project files, but I don't think I was
calling the chunk XSL in my customization layer. I was just calling
the epub XSL. (and epub calls the chunk XSL)

http://docbook.sourceforge.net/release/xsl/current/epub/docbook.xsl

Would this make a difference?

Thanks.

rj



On Mon, Jul 11, 2011 at 12:41 PM, Bob Stayton <bobs@sagehill.net> wrote:
> Hi Robert,
> I was not refering to two-pass profiling, I was refering to the two files
> that are needed for customizing chunked HTML.
>
> In the chunking stylesheet, there are two templates for each element: one
> for chunking and one for formatting the content of the chunk. The chunking
> templates have higher import precedence than the content-formatting
> templates. When you process the document, for each element, it first
> applies the chunking template to create the wrapper for the content, and
> inside that it does xsl:apply-imports, which causes the stylesheet to reach
> down in the import precedence to the original formatting template for that
> element.
>
> If you were to just put an element-formatting template in a stylesheet that
> imports chunk.xsl, your template will overwrite the chunking template for
> that element and break the output. Instead, your formatting template needs
> to be at a lower import precedence, and that set up is described in my book.
>
> Regarding the table of contents, you could add another template:
>
> <xsl:template match="d:appendix[@role = 'endnotes']"
> mode="object.title.markup">
> <xsl:apply-templates select="." mode="title.markup"/>
> </xsl:template>
>
> The 'object.title.markup' mode generates "Appendix A: Endnotes", while
> 'title.markup' mode generates just "Endnotes". I haven't tested this, but
> something like it should work.
>
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
>
>
> ----- Original Message ----- From: "Robert Nagle"
> <idiotprogrammer@gmail.com>
> To: <docbook-apps@lists.oasis-open.org>; "Jason Zech" <zech@loyolapress.com>
> Sent: Monday, July 11, 2011 10:21 AM
> Subject: Re: [docbook-apps] endnotes section in ePub
>
>
>> I am somewhat interested in the method for customizing chunking
>> described here because I face similar scenarios.
>>
>>
>> YOU SAID: In this case, you want the standard chunking behavior for an
>> appendix, but you want to alter its content. Therefore, your custom
>> template just needs to handle the content and not try to deal with the
>> chunking process. That means it needs to be in the "mydocbook.xsl"
>> part of the customization described in that doc.
>>
>> If you were doing two pass profiling, then the first pass will create
>> the content for the appendix while the second pass will make the chunk
>> URL work with the html output? Is that what you mean? Or am I
>> confusing 2 different things?
>>
>> Also, how would you instruct the HTML TOC not to omit the label
>> APPENDIX but not the others?
>>
>> Thanks.
>>
>>
>> --
>> Robert Nagle
>> 6121 Winsome Ln #56C, Houston TX 77057-5581
>> (H) 713 893 3424/ (W) 832-251-7522 Carbon Neutral Since Jan 2010
>> http://www.robertnagle.info
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>>
>>
>>
>
>



-- 
Robert Nagle
6121 Winsome Ln #56C, Houston TX 77057-5581
(H) 713 893 3424/ (W) 832-251-7522 Carbon Neutral Since Jan 2010
http://www.robertnagle.info