Because that was what was asked of me by those who work in other languages :) No clue why I'm using it - I just do whatever I have to to make things accessible to all.

Speaking accessibility... This documentation: http://progit.org/book/ is written with asciidoc. An html version is generated (the above link). But a PDF version can also be created from the same source files. The source files are managed/versioned with git, and translations are done from the English authoritative version: http://github.com/progit/progit So it seems very possible to maintain a multilingual documentation with this technique. Now, it's only time to hope DocBook will do the job for Koha documentation without too much overhead, even if my experience says me the contrary. -- Frédéric

[Correction from my previous message: Frédéric Demians had mentioned AsciiDoc translation to DocBook.] LIST OF ADVANTAGES AND DISADVANTAGES WITH WORKAROUNDS OF ASCIIDOC IN COMPARISON WITH USING DOCBOOK DIRECTLY. Nicole, if the advantages seem compelling enough to you relative to any know disadvantages, my suggestion is to try AsciiDoc for a couple of chapters. If in actual use AsciiDoc seems problematic, simply output your work to DocBook and continue working in DocBook directly without having lost anything. Even if you have already started using DocBook directly, consider the potential time savings of AsciiDoc in the long term. 1. ADVANTAGES. 1.1. USAGE EASE. Simple wiki like syntax allows easy contributions from many who are already familiar with some wiki syntax. Text can be easily edited without much worry about breaking the validation. Anything which can reasonably be done to make the process of contributing easy for as many people as possible should be done. 1.2. VALIDATION EASE. Syntax validation checks are part of the package. It is much easier to avoid syntax errors in when editing in a simple text based format than in the XML format of DocuWiki. 1.3. VERSION CONTROL EASE. Plain text based format with wiki like syntax allows easy version control in Git unlike the XML format of DocBook. 1.4. DOCBOOK OUTPUT FORMAT. Output in multiple formats. DocBook is the primary output format. AsciiDoc is designed to be used for easily editing documents which will be output into into DocBook. XHTML and HTML are the other core output formats, however, generating DocBook output first and then converting to other output formats gives the best results. Once output into DocBook, many formats are available for final presentation. 1.5. MACRO SUPPORT. In addition to built in macros, custom macros can be created to allow a simple means to create complex custom output. 1.6. WELL RECOMMENDED. AsciiDoc is used for editing documentation by the fine people who brought us the wonderful version control program Git. [I do not endorse the confrontational style which appears at the end of the quoted message but I think that the argument is otherwise well presented.] From: Linus Torvalds <torvalds <at> linux-foundation.org> Subject: Re: [ANNOUNCE] GIT 1.5.3-rc4 List: comp.version-control.git Date: 2007-08-05 19:29:09 GMT [...] "I don't even bother to run "make doc". I bet that is true of almost everybody else too. Why? Because the *source* format we use (asciidoc) is already basically as readable as any formatted man-page would ever be." "You don't have to even *know* that they are AsciiDoc pages - they're just called "*.txt", and that's what they are. Text. With very minimal fixups that *allow* them to be used as source for things like html, and admittedly you get prettier output, but it really is perfectly straightforward to just read them, in ways that pretty much no other documentation format allows. Everybody else puts very intrusive crap in there, so that you *have* to be aware of in ways you don't need to worry about in AsciiDoc." "Headers? Lists? They look like headers and lists in the .txt files. No need to think about it as a reader. " "See? Texinfo is decidedly inferior. But you don't have to take it so personally. So is pretty much anything else. Anything XML/SGML is even *worse*." 1.7. FREINDLY ORIGINS. AsciiDoc is from New Zealand where some other software we know well was started. 2. DISADVANTAGES WITH WORKAROUNDS. 2.1. DOCBOOK CONVERSION. Converting between different formats should always be treated with some scepticism. Built in output conversion to DocBook may not have quite the desired DocBook markup. There may be a need for some DocBook elements or degree of control which may not be supported in AsciiDoc by default. If any output control problems are encountered, modifying the output filters and adding custom macro controls could address them. 2.2. WIKI MARKUP CONFUSION. There may be a small risk that some translators might fail to recognise the punctuation indicator for a macro and simply translate a macro keyword. If the boundaries between code and text might be truly unclear to some, those people could always do translation in the DocBook output format where the code boundaries are more clear. 2.3. NO SUPPORT FOR UNICODE IN VARIABLES. UTF-8 is supported in text but not in variable names used for macros. Underscore usage may not count multi-byte characters correctly. Avoid using anything other than ASCII text in variables as one would expect to do on many systems. Output to DocBook format and there should be no need to worry about any AsciiDoc mistakes in mutli-byte character counting. 2.4. NO WYSIWG EDITORS. There are no WYSIWG editors for AsciiDoc. There should be much less need for WYSIWIG editing for AsciiDoc than with formats more difficult for most people to read such as DocBook. The appearance should mostly be easily understood in an ordinary text editor. Output to DocBook format or a final display format to when it may be necessary to see the actual appearance as it would be represented for the final readers. 2.5. SECURITY PROBLEM. Safe mode is disabled by default in the current version which prevents checks to block the execution of malicious code inserted into a document. There is a bug for some output to DocBook which can be triggered in safe mode. The security bug should be fixed in time. Most use can be run in safe mode without problem. The actual hazard of malicious code being inserted by some documentation contributor must be very small. Precautions can be taken to isolate any risk from unknown contributors. 2.6. SMALL PROJECT. AsciiDoc is a small project unlike DocBook. AsciiDoc takes advantage of the larger DocBook project and is merely easier to use format for editing files which will be output into DocBook format. Major projects like the Linux Kernel and Git are not worried about using a small project format for documentation editing. They are generally quite pleased that AsciiDoc addresses their needs. Thomas Dukleth Agogme 109 E 9th Street, 3D New York, NY 10003 USA http://www.agogme.com +1 212-674-3783 [...]

Just to give anybody the opportunity to verify for themselves how easy it would be to manage Koha documentation with asciidoc + git, I've set up a git repository. To browse it: http://git.tamil.fr/?p=kohadoc To clone it: git clone git://git.tamil.fr/git/kohadoc Manual source file is a plain text asciidoc file, easy to read, update and track with git: * en/manual.txt * http://git.tamil.fr/?p=kohadoc;a=blob_plain;f=en/manual.txt;hb=HEAD From this source file with 'asciidoc' command (asciidoc manual.txt), you get an html version of the documentation: * en/manual.html * http://git.tamil.fr/?p=kohadoc;a=blob_plain;f=en/manual.html;hb=HEAD From the same source file with "a2x -format manual.txt" command, you get a PDF version: * en/manual.pdf * http://git.tamil.fr/?p=kohadoc;a=blob_plain;f=en/manual.pdf;hb=HEAD -- Frédéric

On first reading, I had understood Frédéric Demains' comment quoted below without appreciating its potential effect. In case others may have passed over the comment with a similar mistaken appreciation, I will clarify Frédéric's comment now that I have understood properly. [First a simple statement clarifying my own previously given comments in which it should still be remembered that the documentation format should be a choice of those doing the most work on the documentation. AsciiDoc is merely a simple format for editing documentation for use in DocBook on export. AsciiDoc is not an alternative to DocBook as such. AsciiDoc is expressly designed to provide DocBook formatting, widely considered the preferred base format for free software documentation.] What Frédéric explained below gives an additional perspective on the ease of use encourages more contributions advantage which I had given as the first advantage for AsciiDoc in the list I had prepared of advantages and disadvantages, http://lists.katipo.co.nz/public/koha/2009-October/020807.html . . As a direct consequence of AsciiDoc using a plain text format, programmers may be inclined to use AsciiDoc to document their work as part of the programming process, perhaps even in the same patch. Otherwise, contributing to documentation is a separate process which programmers avoid completely. Any prospect of having the manual updated by those writing the programming code as their patches are applied to the code in one step is very significant advantage. Programmer changes to the manual as might be needed parallel to a code change would apply to the version of the manual corresponding to the version of the software in which the code change would be introduced. If even one programmer could be encouraged to document his work just a little as he coded it, there would be much less time spent identifying how things work in the first place for the manual. Less time of the documentation manager and others would be needed identifying what needs to be described in the manual. More time could be available for ensuring that the description is clear for all users and other good purposes. Using the DocBook format directly should not stop programmers from updating the manual, although, it might preclude updates to the manual in the same patch and would require a greater effort. In reality, any documentation editing format which requires much expenditure of time on the part of programmers would only increase the prevalent tendency of programmers not to document their own work. Programmers need any encouragement which may be obtained to better appreciate the importance of including comments in the code which they write, especially for the benefit other programmers. They also need any possible encouragement to document their own work for everyone. Thomas Dukleth Agogme 109 E 9th Street, 3D New York, NY 10003 USA http://www.agogme.com +1 212-674-3783 On Tue, October 20, 2009 20:32, Frederic Demians wrote:

Thomas, you can add that asciidoc operates very well with developers workflow. It means it can be directly integrated in Koha git main repository (or as submodule), and then, when a developer add a new functionally or modify an existing one he can document it immediately, being not intimated by DocBook schema and editing process. It works this way in git project itself where there is no wall between developers and technical redactors.

To get the picture, take a look at a patch like this one on git main repo:

http://tinyurl.com/yftmt2m

-- Frédéric