Considering to move to asciidoc ?

[dagwieers]

Hi,

I have been discussing this with Serge last month. Looking at the code/docs I feel that simply using asciidoc (which translates to DocBook perfectly) is a much easier way of developing. You can have different pieces in different files, included in other documents (even with different title levels depending on the document).

If you would be interested, I am happy to discuss and help with the migration, and we can grab a beer too :-D

PS asciidoc/docbook is being used by O'Reilly authors in producing a book (however, O'Reilly's styling has not been made public). If interested I can provide you with a few example documents that show the possibilities.

[srgvg]

I think Paul hase some requirements on what needs to be done, but as that would just be another layer on the existing docbook stuff, it should be quite easy to implement it.
One practical problem: atm Paul is rewriting lots of part in the experimental branch, and also the make script is working very diferently, which is a major breakage from the master branch.
Ideally, work on asciidoc would need to happen afater experimental is merged back in master.
Another way, might be to start with extra code which handles the source files in asciitext, which would allow to start writing new chapters in asciidoc, while keeping the existing chapters in docbook, and have those moved to ascidoc gradually? Docbookc has an .xml extendsion and we could use a separate extension for asciidoc (not sure which is the most appropriate).

1. Paul, what do you think?
2. Dag: maybe you could make some small proof of concept script which is able to a) convert the docbook text in asciidoc, and 2) convert asciidoc in docbook? If you wriite something up, be sure to fork from experimental.
3. I could have a look to extent my make script to first convert sources from .ascii to .xml when the former is available, and then having the book fully build from docbook as usual.

Some things to pay attention to:

1. Be sure to have a look at the different and tags, which are sometimes used dynamically depending on the type and the structure of the book.
2. Index and wordlist still needs to be able to be generated (there are words which manually have a special tag for that).

I'm sure Paul has some other features which are important for him.

[dagwieers]

There is an XSL that can be used for doing conversions from DocBook to AsciiDoc, which might be a bit rough around the edges, but we could improve it to make it work well. It is BSD licensed and in need of a new maintainer, so maybe we should look at that. I believe we could do all this in an afternoon session somewhere :-)

PS AsciiDoc by default uses .txt, github expects .asciidoc, and there is hope of having a consensus to use .adoc :-) I have been promoting this idea for a few years and github using .asciidoc may help to get to .adoc...

[paulcobbaut]

Dag:"...grab a beer..."
I am convinced now you have very good ideas. I have no idea atm what asciidoc is...

Serge: "Ideally, work on asciidoc would need to happen after experimental is merged back in master."
I agree 100 percent. I underestimated this rewrite/migration, I'd hate to have two of those nested.

Also I am a bit to busy this and next week to take a good look at asciidoc, but I should have lots of free time between June 25th and August 1st (see mail also).

Serge:"I'm sure Paul has some other features which are important for him."
It must stay modular so I can customize courses for clients. The rest --> July!

Dag: "There is an XSL ... afternoon session."
I agree.

(...sorry in advance for possible silence from my part the next two weeks, teaching day+evening classes...)

[dagwieers]

Paul: "I agree 100 percent. I underestimated this rewrite/migration, I'd hate to have two of those nested."
I disagree, for the simple fact that if the XSLT works fine (and we can make it work fine!), merging AsciiDoc is much easier than merging DocBook. As you don't have to fight nesting changes anymore. You simply have to compare paragraphs.

Paul: "It must stay modular so I can customize courses for clients. The rest --> July!"
I am convinced that with AsciiDoc you can throw out most of the scripts, and simply write AsciiDoc and convert the root-document. AsciiDoc will pull in the chapters you have referenced, including rebasing and renumbering chapters on-the-fly.

DocBook is nice, but (like XML) it is not meant for editing and not for merging changes (by humans) ;-)

[srgvg]

The biggest part of the make script primarily handles joining the xml files in the right order.

If I understood Dag correctly, the process is ASCIIDOC -> DOCBOOK -> PDF ?
If so, I'd propose to work out a procedure to convert ASCIIDOC to docbook, then I'l update the script to automatically detect the ASCIIDOC files and converting them to docbook XML. After that, the sctip can run as it does now.

[dagwieers]

Serge, it's a bit different. AsciiDoc can take care of inclusions so you do not have to do asciidoc -> docbook conversion per file, but rather per "root" document. And the toolchain already has the tools (a2x) to convert via DocBook to various formats (given you have the tools installed it depends on, eg. FOP or others). I don't really know what scripts you are referring to (I assume these scripts rebase paragraphs/nesting and merges DocBook pieces together into a single DocBook document), but I would be surprised they would be still needed.

But again, all the talking is probably wasted if I can simply show you how it works, and we can perform the things we need on the sources directly.

[dagwieers]

In case you'd have a few minutes to spare, here are some references from the excellent AsciiDoc userguide:

• 31. Converting DocBook to other file formats
  • http://www.methods.co.nz/asciidoc/userguide.html#X12
• 34.5. Combining separate documents
  • http://www.methods.co.nz/asciidoc/userguide.html#X90

These should provide insight in what's possible.

[paulcobbaut]

So when do we meet ? I work from home from today till the end of July probably, so i can come to Gent or show you Antwerp.

[dagwieers]

On Mon, 27 Jun 2011, paulcobbaut wrote:

So when do we meet ? I work from home from today till the end of July
probably, so i can come to Gent or show you Antwerp.

I might be without a job starting from 15/7, so that would fit my calendar
better. That said, I may carpool on wednesday with Serge in order to
discuss asciidoc a bit.

I plan to have a full tree of the project on my machine and do some
preparations in the morning on the train.

PS Apparently I missed another barcamp Ghent, why oh why do they insist on
twitter. I feel so old... Or maybe I just need another cellphone ?

-- dag wieers, dag@wieers.com, http://dag.wieers.com/
-- dagit linux solutions, info@dagit.net, http://dagit.net/

[Any errors in spelling, tact or fact are transmission errors]

[dagwieers]

So we failed to carpool, twice...

I am currently unemployed for at least a month, leaving me with plenty of time to meet and discuss. Doodle ?

[paulcobbaut]

I am currently not so able to walk... so if not meeting here in Antwerp, then close to a parking spot or a train station. I am also dogsitting until the 31st of July. I put a Doodle up here http://www.doodle.com/w6vm97hk2q6uwq7u