[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 [...]