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

[Thomas Schraitle <tom_schr@web.de>]

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