[Koha] Koha Manual in Git

[Thomas Dukleth]

[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

[...]