Format

[fbraem]

Any idea which format will be used for the cookbook? I'm currently investigating asciidoc to replace the docbook comments in my GLUEscript project. I'm looking at asciidoc, because writing docbook is cumbersome and error-prone (closing tags correctly for example).

[guenter]

I'm pretty open to the format question; the only thing to consider is to choose a format that's friendly for publishing as a printed book, should the opportunity arise. From the samples I've seen on the asciidoc page this looks promising.

[btbytes]

+1 for AsciiDoc.

There are quite a few professional programming books written using ASCIIDoc [1]
AFAICT, AsciiDoc is popular C++ programmers over ReST[2], markdown etc.

[1] http://www.methods.co.nz/asciidoc/#X6
[2] http://docutils.sourceforge.net/rst.html

[rmoffer]

Depending on what the primary output format is you might want to consider LaTeX or docbook.

You can't beat LaTeX for the quality of the print output - but it sucks at everything else.

Docbook attempts to be a reasonable structured markup format - until recently Ive always been disappointed at the tool suites to go from the markup to the output format, they've never been able to deliver on the promise of the concept (its as important how the documents look as it is what they say) - the Poco PDFs illistrate that as well.

But I've recently discovered Publican - its being used by RedHat (including JBoss, Fedora and other projects). Both the HTML and PDF outputs look great. And its been designed to make it easy for projects to build their own "themes" so all documents don't look the same (you can spot a LaTeX document from a mile off).

If you are going to play wit Publican - do yourself a favor and use the latest version of Fedora there is (14) - even though we use CentOS for all our product builds I gave up trying to get Publican to build on it and create a Tech Pubs virtual machine that runs publican...

(There's also a Windows version of Publican - but I didn't play with that).


richard.

[raulgd]

It would be nice if it is Open Document Format.

As you guys say, if the opportunity arises to publish it (which was my intention in the first place hehe) the format should be usable in MS Word and at least Adobe products to be designed, proofed and everything.

That way, we could use libreoffice for editing, or if some of you have MS and like to use it, you could use the ODF export plugin.

EDIT:
Also, something I forgot to mention, using word processors like libreoffice or MS Word, gives us the flexibility to autogenerate and update the TOC and Index as we move through the book writing process, I haven't heard much of asciidoc, I'll look into it, but I've worked with professional edition tools (Adobe illustrator, indesign and incopy), and haven't seen any support for it, I'll have to research on that

[rmoffer]

A couple of suggestion/comments.

Word processing is not the same as writing a book. Tools that are great for writing a 30 report wont work for a 300page book across multiple authors. Anything that allows a contributor to insert style tags will break at scale with multiple contributors because people will take shortcuts...

Avoid at all costs formats that cannot be meaningfully "diffed" in a revision control system. You'll spend hours tracking down changes that are being made.

Use a revision control system for everything - text, examples and production tools.

If you're serious about publishing it - check with several publishers what formats they prefer (not the same as accept). You want a format that means the publishers don't have to do a lot of rework to fit it into their production process - it makes it easier to sell the idea if they have no rework to do.

Develop macros/a tool that make it easy to include source code from outside the book (i.e. source code should not be mastered inside the book). That way the code can be edited (and compiled and executed) which will avoid cut-and-paste/compilation errors in a key part of the reason for a book - teaching people Poco. The example code should be compiled as part of the document build process to ensure its correct. If you have errors in the source code you lose credibility in the text.

Don't duplicate - if you're documenting the API - you will make errors - so why not just include the actual Poco API reference text (pre-processed to fit in with book format). If the text is incomplete/misleading fix it at source, not in your copy.


Just my opinions.

richard.