Forum OpenACS Q&A: Best markup language? DocBook, Scribe, Wiki, HTML, LaTex, or etc.

Collapse
29: Best markup language? DocBook, Scribe, Wiki, HTML, LaTex, or etc. (response to 10)
Posted by Andrew Piskorski on 10/04/05 11:42 PM
Well, just how bad is DocBook? I've never attempted to use it, so I am genuinely curious. Malte and others who have, can you give us a rough idea please: How much time did it take you to come up to speed on DocBook, and once you were there, how pleasant and efficient was using DocBook compared to other markup tools?

As far as markup languages that can emit multiple output formats (HTML, PDF, man pages, etc.) go, has anyone used Scribe? It sounds very powerful.

Also, how do all these Wiki syntaxes compare to simply using straight good-old HTML? Or LaTeX, for that matter? In other words, what is the win with using one of the various specialized (but rather ad-hoc?) Wiki syntaxes?

Collapse
33: Re: Best markup language? DocBook, Scribe, Wiki, HTML, LaTex, or etc. (response to 29)
Posted by Malte Sussdorff on 10/05/05 07:43 AM
Getting up to speed on docbook took me half a day for being good enough to write OpenACS documentation. Then it took me again half a day to figure out how to use the provided scripts to generate HTML out of the docbook file. So it is not a problem of the Docbook format. It is more a problem of the steps involved which will scare the casual user from editing documentation.
  1. Download the documentation source code
  2. Use a decent editor for docbook (I used emacs) to edit the documentation. Make sure you keep up the markup
  3. Generate the HTML out of it
  4. CVS commit both files to the repository
  5. Make sure you are on the correct branch. Commit again 😊
  6. Write an email to Joel to update the documentation on openacs.org
  7. Realize Joel is busy, login to openacs.org and do the update yourself (This steps used to work for OCT members, now this is restricted to even less people).
Compared with
  1. Login to openacs.org/wiki/documentation
  2. Edit the documentation
  3. Reflect in glory about your excellent work
it seriously lacks user friendliness.