docbook-apps

Hi!

I'm using the new assembly/resource/structure method to construct
books from topic elements. Thank you to everyone who worked on that
feature, it's extremely useful!

I am having trouble getting the titles of books to appear in my
rendered book files.

Based on my reading, I understand that I can include book metadata
such as a title in the structure element. For example:

<structure renderas="book" xml:id="myId">
<info>

<copyright>
<year>2016-2017</year>
<holder>My Company, Inc.</holder>
</copyright>
</info>
<module renderas="chapter" resourceref="myTopicId"/>
</structure>

When I process the assembly, the rendered XML file has the correct
book root element and it includes chapter elements rendered from my
topics. It does not have the book title though.

I see that the assemble.xsl stylesheet explicitly ignores the info and
title for a structure:

https://github.com/docbook/xslt10-stylesheets/blob/master/xsl/assembly/assemble.xsl#L44

Does anyone know how I can supply the title for a structure?

Thanks for your help!

Peter

Hi Peter,
Content you want to blend into your output from the assembly file should
be put into a <merge> element like this:

<structure>

<merge>

...
</merge>

The <merge> element has a content model like <info>, and is used for
content you want to add or replace in the resource's info element (if it
has one).

In addition to title, an info element is often used to document its
parent element, using revhistory, copyright, legalnotice, etc. While
developing the assembly schema, the authors felt that this function
needed to be retained for assembly elements themselves. So they added a
merge element to separate out any content you want to actually merge
into the resource for output.

I hope I cleared that up.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

On 5/30/2017 2:46 PM, Peter Desjardins wrote:
> Hi!
>
> I'm using the new assembly/resource/structure method to construct
> books from topic elements. Thank you to everyone who worked on that
> feature, it's extremely useful!
>
> I am having trouble getting the titles of books to appear in my
> rendered book files.
>
> Based on my reading, I understand that I can include book metadata
> such as a title in the structure element. For example:
>
> <structure renderas="book" xml:id="myId">
> <info>
>
> <copyright>
> <year>2016-2017</year>
> <holder>My Company, Inc.</holder>
> </copyright>
> </info>
> <module renderas="chapter" resourceref="myTopicId"/>
> </structure>
>
> When I process the assembly, the rendered XML file has the correct
> book root element and it includes chapter elements rendered from my
> topics. It does not have the book title though.
>
> I see that the assemble.xsl stylesheet explicitly ignores the info and
> title for a structure:
>
> https://github.com/docbook/xslt10-stylesheets/blob/master/xsl/assembly/assemble.xsl#L44
>
> Does anyone know how I can supply the title for a structure?
>
> Thanks for your help!
>
> Peter
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>

Thank you, Bob! That did clear up the situation and my book now has
the metadata that it needs.

I think the documentation about assemblies needs an update to cover
this. This paragraph and the following example seem to imply that you
can insert metadata using a dedicated resource, or by including an
<info> element in the <structure>.

https://github.com/docbook/defguide/blob/master/en/defguide5/src/ch06.xml#L870

I guess a technical writer could propose edits now that it's up on GitHub...

Peter

On Tue, May 30, 2017 at 7:19 PM, Bob Stayton <bobs@sagehill.net> wrote:
> Hi Peter,
> Content you want to blend into your output from the assembly file should be
> put into a <merge> element like this:
>
> <structure>
>

> <merge>
>
> ...
> </merge>
>
> The <merge> element has a content model like <info>, and is used for content
> you want to add or replace in the resource's info element (if it has one).
>
> In addition to title, an info element is often used to document its parent
> element, using revhistory, copyright, legalnotice, etc. While developing
> the assembly schema, the authors felt that this function needed to be
> retained for assembly elements themselves. So they added a merge element to
> separate out any content you want to actually merge into the resource for
> output.
>
> I hope I cleared that up.
>
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
>
>
> On 5/30/2017 2:46 PM, Peter Desjardins wrote:
>>
>> Hi!
>>
>> I'm using the new assembly/resource/structure method to construct
>> books from topic elements. Thank you to everyone who worked on that
>> feature, it's extremely useful!
>>
>> I am having trouble getting the titles of books to appear in my
>> rendered book files.
>>
>> Based on my reading, I understand that I can include book metadata
>> such as a title in the structure element. For example:
>>
>> <structure renderas="book" xml:id="myId">
>> <info>
>>
>> <copyright>
>> <year>2016-2017</year>
>> <holder>My Company, Inc.</holder>
>> </copyright>
>> </info>
>> <module renderas="chapter" resourceref="myTopicId"/>
>> </structure>
>>
>> When I process the assembly, the rendered XML file has the correct
>> book root element and it includes chapter elements rendered from my
>> topics. It does not have the book title though.
>>
>> I see that the assemble.xsl stylesheet explicitly ignores the info and
>> title for a structure:
>>
>>
>> https://github.com/docbook/xslt10-stylesheets/blob/master/xsl/assembly/assemble.xsl#L44
>>
>> Does anyone know how I can supply the title for a structure?
>>
>> Thanks for your help!
>>
>> Peter
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>>
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>