[Zope3-dev] Data Format of the DevelCookbook

[Stephan Richter]

Hello everyone,

Its me again. As the book's content takes more and more shape, I am getting to 
the limits of StructuredText and I do not think that ReStructuredText is the 
solution either for reasons listed below. So I think I decided on a new 
format, but I wanted to check with you guys and the publisher (who is CCed) 
whether this will be a good solution.

Let's start with the requirements:

1. I want to keep the book online for people to comment on it; I really like 
the Wiki style. I think that talkback might be an overkill for me.

2. We need to be able to produce a real book; so I must be able to insert a 
lot of meta data and structural information, such as index entries and markup 
of special sections, such as exercises.

3. When we go through the editing process with the publisher, they prefer to 
have a Word file for commenting. Jordan, is this correct?

While I think we could cover all this by using Docbook as source, I must say 
that I do not like XML; it is just too much to write and I have heard Docbook 
has lots of flexibility problems. Furthermore, the output is not that 
impressive. For example, making a single list item is 

  <listitem>
    <para>
      Item text here.
   </para>
  </listitem>

in comparison to

  \item Item text here

in LaTeX and 

  - Item text here

in StructuredText.

I think the real solution is to use LaTeX! It is proven to work and produces 
great-looking and structured documents. When done right, it separates 
content/structure and presentation. There is a great tool out there for $99 
($45 for education) that allows me to do round trip engineering to and from 
Word. Furthermore I found a great python tool called pylatex that allows to 
convert LaTeX to HTML and it would be not too hard to write a StructuredText 
writer for it, since it strictly separates parsing and writing.

As part of my TA this semester I also converted a professors book from 
WordPerfect to LaTeX and got a lot of experience; LaTeX is very flexible and 
is a proven tool. The final output was almost like my printed textbooks (in 
Physics LaTeX is the de-facto publication standard).

Shelly, is SAMS also publishing books from Latex sources or what is your 
preferred format?

What does everyone else think about this? Jim, what format would you prefer 
for technical editing? 

Any comments and suggestions are very welcomed!

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training