[Zope3-dev] RE: Data Format of the DevelCookbook

[Johnston, Shelley]

Hi Stephan.  We do prefer Word (I know--gack!), but you can use anything
that can do an rtf output.  

Damon is actually the expert on this stuff, and he's going to send you a
more detailed email about it.

Shelley

-----Original Message-----
From: Stephan Richter [mailto:srichter at cosmos.phy.tufts.edu]
Sent: Sunday, December 14, 2003 3:36 PM
To: zope3-dev
Cc: Johnston, Shelley; Jordan, Damon
Subject: Data Format of the DevelCookbook


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


****************************************************************************
This email may contain confidential material.
If you were not an intended recipient, 
please notify the sender and delete all copies.
We may monitor email to and from our network.

****************************************************************************