[ZDP] ZDP-Tools: New ZClasses Book, Part and Chapter

[Maik.Röder]

Hi !

> 1. What's the difference between a Chapter and a Part?

It is just a way of organization. The Part is responsible
for collecting the chapters, and the chapters are responsible
for collecting subchapters.

To take things to an extreme, it would be possible to do 
everything with just the Book ZClass.
Then you would have all the logic for Books, Parts and Chapters
and Subchapters in one ZClass. The ZClass would get rather crowded
soon, so the design decision to spread responsibility.

> Why don't we just use Chapter ZClasses?

For example searching for Books, Parts, and Chapters will be
easy to do with a Catalog search. Of course we could make
searching more complicated, but right now we just search
for meta_type and don't have to look further to distinguish
betwee Chapters and Parts.
 
> Can somebody tell me why Parts are not the same as Chapters?

Also, if you are searching for all Parts of books that need
a maintainer, you can do this easily. Or you can search for
Chapters that need writers.
 
Kamon answered:
> I would say: Part is the 1st level, Chapter is the 2nd level, and
> SubChapter is 3rd level.
>
> To keep it simple, I haven't added a 4th level in the ZCL, but in > reality
> you may have:
> Part I
>   I.1 (a chapter)
>     I.1.1 (a subchapter)
>       I.1.1.1 (sub of subchapter)
>
> The only difference is that I.1.1.1 does not appear in the current ZCL.
> This can be changed. But I think that most of the time, it is the same
> person that writes a whole subchapter. That's why the current ZCL does 
> not show details at 4th level.

I guess I should have created the Subchapter ZClasses. At least this
would have been more consistent.

Tom:
> Yes, but why the differnce in Part and Chapter?
>
> Isn't Part a Chapter as well? What difference do you want between Part 
> and Chapter?

Kamon:
> It's because in the ZCL XML file, I want <Part> to be the parent tag of
> <Chapter>.

And don't forget that this also allows to translate our ZClass hierarchy 
to XML in a straightforward way. 

> I am just thinking there is another solution: using the same tag <Chapter>
> and an attribure level=1, 2 or 3.
> Can someone tell me if this is possible with XML Document (nested tags with
> the same name ?).

The level is implicitely stored in the XML file. There is no need to make the 
level explicit. 

> If this works ( I will try it this afternoon), then OK.
> We will have a unique Zclass for all chapters and find a way to handle the
> levels/numbering.

It could be done this way, but what if at one point in the future we need
to add some new behaviour to Parts for example ? Object-oriented programming
is also about "Design for change". There may be a difference one day between
how Parts are managed (By people who have the role "Part Maintainer" and the way
Chapters are managed (By people who have the role "Chapter Maintainer".

Tom:
> I'm afraid I can't follow you. I've problems understanding XML files. Can
> you explain me what ZCL XML does at the moment and how you created this?

The basic look of the XML file is this:

<Book>
 <Part>
  <Chapter>
    <Subchapter>
    </Subchapter>
  </Chapter>
 </Part>
</Book> 

You can also see it as a tree:

                           Book
                   /                   \ 
         Part I                       Part II
          /                           /       \
      Chapter I Chapter II        Chapter I Chapter II
       /                                          \
Subchapter I                                    Subchapter I

> And what do you mean with Part to be parent of Chapter?

So, in the tree you can say that Part II is a parent of Chapter II.
 
> At the moment, you can put Chapters into Chapters thus leveling is done
> automatically. 

Please note that by making Part, Chapter and SubChapter, we would not
even have to worry about leveling and numbering !

I will add a SubChapter ZClass later.

> Same if we change Part to Chapters. Link your XML to the
> Chapter I and viola?

Linking in XML is a chapter of it's own :-)
I am not an expert in this.

Tom:
> 2. How can I let people give comments to the text?

Just Add a Comment Folder to the Draft or Draft Submission Folder
in the Chapter/Part/SubChapter.

Kamon:
> Probably need a Comment button on each page.

We don't need to add comment buttons on the page, just Comment Folders.

Kamon:

> I made my modifications to only use a <Chapter> in the ZCL file, and using
> attributes like type="Part" (or "Tutorial" or "How-to") and _purpose=the
> text that appear in blue_. This allows me to display these cases in a
> specific way.

This is not the idea of XML, Kamon. In the purpose of XML is to make
the Tags define the structure, and not the attributes.

<?xml version="1.0"?>
<ZCL title="THE DEFINITIVE ZOPE CONTENT LIBRARY">
 <Chapter title="A Web Application Platform" purpose="Introducing Zope Technology" type="Part"
num="I">
     <Chapter title="Introduction" num="I.1" contributor="Tom Deprez"/>
     <Chapter title="A Web Application Platform" num="I.2" contributor="Tom Deprez"/>
     <Chapter title="Zope as a Web Application Platform" num="I.3">
       <Chapter title="Scripting Languages" num="I.3.1" contributor="Tom deprez"/>

> >So, it's ok for you if I change all parts to chapters?
> Yes it's OK for me.

I vote not to do so. :-)

> >But I want to learn about XML :-(. Perhaps you can write a how-to? :-)
> >(How-to use XML Document?)

http://www.w3.org/XML/

> I agree I should transform this exercise into a how-to. This would give a
> second light to XML document after the one written by Amos. I will think
> about it.

We should discuss this a little bit further, I think.

Greetings,

Maik