search

linuxtraining / lt

The Linux Training Book
http://linux-training.be/
Other
39 stars 18 forks source link

Considering to move to asciidoc ? #3

Open dagwieers opened 13 years ago

dagwieers commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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

These should provide insight in what's possible.

paulcobbaut commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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