Re: [docbook-apps] Using topic and assembly - starting from article?

[Phillip Kent <phillip.kent@gmail.com>]

Dear Thomas, thanks for the summary. The functionality is even better
than I thought.

I will try it out and will be pleased to feed back any insights to the list...

Phillip

On Tue, Aug 19, 2014 at 12:20 PM, Thomas Schraitle <tom_schr@web.de> wrote:
> Hi Phillip,
>
> On Tue, 19 Aug 2014 11:01:24 +0100
> Phillip Kent <phillip.kent@gmail.com> wrote:
>
>> can someone give me a steer about this...
>>
>> I currently have a collection of standalone documents, each is a
>> DocBook <article> .
>>
>> I want to organise these into a more structured form, particularly so
>> that I can get them all to come out in a single PDF document (grouped
>> into super-topic chapters/sections...).
>>
>> The topic and assembly elements in DocBook 5.1 look ideal for that
>> purpose. Is that correct?
>
> If you want to use assemblies, then yes, the assembly element is
> correct.
>
> Your standalone resources does not necessarily need to be topic
> elements. Basically, it can be any DocBook element. However, there may
> be other restrictions, not technical ones, that impose a certain
> element (styleguide, structural, etc.)
>
>
>> If yes, how can I move from <article> to <topic>? I want one article
>> to become one topic, I don't need to chunk them into smaller parts.
>>
>> Could I simply replace <article> by <topic> in each xml file and
>> nearly everything will work without further editing?
>
> Well, this could be one solution, but a very impractical one. ;)
> However, with assemblies this is not necessary anymore. You can keep
> your documents as standalone articles, but at the same time render them
> as topics (or chapters, or whatever you want them).
>
> First, you need to identify all your resources. Add them to the
> resources element and define an unique xml:id for this. For example:
>
>   <resources xml:base="tutorial/">
>     <resource xml:id="tut1" href="tut1.xml"/>
>     <resource xml:id="tut2" href="tut2.xml"/>
>     <resource xml:id="tut3" href="tut3.xml"/>
>   </resources>
>
> Let's assume, each of the above resources are standalone articles. It's
> the same situation that you face currently.
>
> Second, let's further assume you want to create a book from your
> articles, but don't want to change them. In that case, a valid book
> consists of chapters so you can "rewrite+1" your articles into
> chapters. This is done by the output element:
>
>   <structure xml:id="user-guide">
>     <output renderas="book"/>
>     <module resourceref="full-toc"/>
>     <module resourceref="tut1">
>         <output renderas="chapter"/>
>     </module>
>     <module resourceref="tut2">
>         <output renderas="chapter"/>
>     </module>
>
>     <module resourceref="task1"/>
>
>     <module resourceref="tut3">
>         <output renderas="chapter"/>
>     </module>
>
>     <module resourceref="task4"/>
>     <module resourceref="index"/>
>   </structure>
>
> (The other resources like full-toc, task1, etc. are not relevant for
> this discussion.)
>
> To create the real structure (The Definitive Guide named it "realized
> structure") apply the assembly stylesheet.
>
> The above example is an excerpt from the original DocBook 5.1 TDG, see
> http://www.docbook.org/tdg51/en/html/ch06.html
>
>
> Hope that helps and I wasn't too wrong about this topic. :)
>
>
> --
> Gruß/Regards,
>     Thomas Schraitle
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>



-- 
//www.phillipkent.net