Updated 2009-05-15: Correction on some WikiText conversion.
I've spent most of the day the last two days taking some legacy Word documents and converting them into nicely formatted, semantically marked up DocBook files. I hear some kringing already. The WikiText fan boys are already gearing up, shouting it's praises as the silver bullet to all your document creation needs (tongue firmly planted in cheek) (Where I work we happen to use PMWiki to run our main website, so it has it's uses). Okay it's not a silver bullet, sorry, I'm not a huge Wiki markup fan even though I do use it. It reminds me too much of RegExp and Perl. Powerful, but very cryptic. In many ways wiki can make text even harder to read when editing.
Inconceivable!
Sample Wiki Table with italics and SuperScript.
{||-
|<i>x</i><sup>2</sup>
| width=20px | || width=20px | ≥0 || true.
|-
| a || || b
|}
Wait! I thought this was wiki, what is XML markup doing in there! Can't wiki do everything? Honestly XML has it's good and bad markups as well...Don't even get me going on how much I hate DTDs.
Yeah, I know, some will say that the DocBook dialect is overly verbose, that there is too many tags. However like Wiki markups in their many flavors and sizes, you only truly need about 10% of the DocBook markup to write a good document.
Inconceivable!
Honestly...if you look at most documents you have it broken down into the following semantics:
- Book
- Chapters
- Sections
- Paragraphs
- ItemizedLists
- OrderedLists
- Emphasis
- Figures
- Images
- Tables, Rows and Columns.
Inconceivable!
Okay maybe I live in a dream world, but for those that just want to get things done. There are options like the eclipse VEX project, OxygenXML's Author, and my personal favorite at the moment XMLMind. WikiText is great for developers, but in the end one of the formats it converts to is good old DocBook. It also converts directly to other formats. Personally, XML semantics still hit that sweet spot. Besides I'd rather learn one DocBook markup than hope that somebody has created a plugin for WikiText that understands my flavor of Wiki markup, with my particular extensions, and additions. Hopefully, the wiki world will standardise. Some work has already started around this with the work of WikiCreole. Standards...what a concept.
I know...I know....Inconceivable!
Posts
Well, I am not a big fan too of Wiki syntax for writing documentation. I do agree that "[authors] should only have to worry about the content they are writing". I have just written too The wiki syntax is crappy - Death to the wiki! Long live the wiki! for expressing my views.
David, I have just released the 1.0 version of the Scroll Wiki Exporter. It is an extension for Atlassian's Confluence wiki, and it does transform wiki syntax to DocBook. We are currently supporting only article and DocBook 5.0, but hey! it's the 1.0 release.
@Dominique D - thanks I hadn't found your post yet and I was looking for something like that when I was writing this entry.
@skleinei - here's a question...WikiText also converts to DocBook before converting to another format. Why not just write in DocBook then? For some people they just can't get around the XML markup, but what is funny is that most Wiki conversions eventually convert to DocBook or XHTML, so they leverage XML anyways. It just trades one markup for another. In the end it all becomes XML. :)
@David Carver It's great to see WikiText getting so much attention! ;)
I've used DocBook for many, many years. It has it's place. It's versatile, has mature tooling, and can be used to express semantics separately from presentation. In practice however I've found that I rarely care about the semantics -- in the end it's the presentation that matters.
The main issue that I have with DocBook is that content is largely obscured by XML markup. This makes it very hard to author DocBook without excellent tooling that hides or minimizes the markup. Unfortunately these tools suffer from the leaky abstraction problem and the complexity of DocBook always seems to shine through.
Even with all of that I still do use DocBook for some things. The key is to use the right tool for the right job. Use lightweight wiki markup where it makes sense, and XML languages such as DITA and DocBook when necessary.
BTW, I have to say: please get your facts straight about WikiText. WikiText converts directly to HTML, Eclipse Help, XSL-FO, and DITA without first converting to DocBook. And yes, it can also convert to DocBook.
@David Green: Thanks for pointing out the conversion inconsistency, I've updated the entry accordingly.
What I've learned from using DocBook or any other type of markup language like Wiki is that people either like them or they don't. In general people want visual tooling regardless of what the underlying markup is doing. People in most cases just want to write content and get the information displayed. Whether that be writing a itemized list as:
<itemizedList>
<listitem>
<para>Some Item</para>
<listitem>
<itemizedList>
or
* Some Item
Depends on some personal taste. Granted the latter is definitely smaller, but also requires some specialized parsers and RegExp processors to write. The former uses a standardized parser, and then it's based on the semantics of the language how it's implemented.
One of my favorite Word processors still is Wordperfect. Why? Because of the Reveal Codes functionality. Many a problem was fixed by showing what the underlying markup was underneath and directly editing that markup.
I've been using XMLMind and am working on VEX. Many of the complications you say are there with DocBook are made into a WYSIWYMG editor. It provides that visual look. I think for WikiText in Mylyn, that is the next step. Hide the actual wiki markup, and go to more of a visual editor. Then the markup becomes just another file format, and the author can just get back to what they want to do. Write content.
I think WikiText is great, however, I don't think it fits all of the documentation needs. With that said...things change...maybe I'll be won over. :)
Dave, I do not think that word means what you think it means.
:D
Great post, thanks!
- Don
@Donald Smith: Bingo! Finally somebody got it. :)
@David Carver re: "I think WikiText is great, however, I don't think it fits all of the documentation needs.", I agree fully, which is why WikiText is designed to integrate with other toolchains. No need to be won over.... just use wikitext when it feels right!
Dave, Dave, Dave. "You Fool! You fell victim to one of the classic blunders. The most famous is 'Never get involved in a land war in Asia,' but only slightly less well known is this: 'Never go in against a Sicilian when death is on the line.'"