[coyotos-dev] Doc Conversion -- content model?

[Jonathan S. Shapiro]

We need to decide whether to continue using OSDoc. The issue comes up
because I would like us to move to a more collaborative environment in
general. I'm not sure whether we will do it through the web or through
mercurial, but I want third parties to be able to help us with
documentation issues. Nobody knows OSDoc, and there is no web support
for it.

OSDoc came into existence because we needed good print output. HTML
wasn't designed for that. At the time, open source WYSIWYG editing
support for DocBook was (and remains) non-existent, and you have to be
*nuts* to do DocBook in a plain-text editor if you have any choice.
DocBook was explicitly *not* designed to be done in text editors (just
consider the number of characters you need to type to enter
"<paragraph>". OSDoc uses an element structure that was "mostly HTML
except where it absolutely has to be something else".

My current belief is that if we want to use web browsers as editing
tools, we can basically rule out both OSDoc and DocBook. We should be
using XHTML.

Comparing OSDoc to HTML, there are basically two differences: some
additional markup elements and some additional document structuring
metadata. If we are moving to a content management system such as
Drupal, most of the metadata simply moves into the content manager and
the issues are pretty much reduced to content markup. With *one*
exception, all of the content markup things *could* have been done with
html SPAN and DIV elements. In fact, a precursor to OSDoc *was* done
this way. We abandoned it because (1) it turned out to be hard to
remember which "class" attributes to use on which SPAN tags, and (2) we
had other things we wanted to get out of the "class" attributes. The
other thing was that we wanted to be able to capture some print-specific
attributes that were not legal XHTML.

The main issue was that hand editing couldn't be made robust enough
without new elements. At the time, editing this stuff from the web
wasn't an objective.

Fast forward:

Today, FCKeditor (and a couple of others) provide web-loadable WYSIWYG
editors for HTMl. Many of them (including FCKeditor) can be augmented
with additional "styles". With a little care, these can be used to
insert SPAN tags that the user never needs to know about. Given this, I
believe that we could now move to a web-based editing scheme. The only
part of that which could get interesting is footnote and image
processing, and I think I can see how to automate that now. Further,
given the experience built from OSDoc I am pretty confident that I can
get decent-looking output from it. I may have to munge some new
attributes into a hacked XHTML DTD, but that is probably feasible.

So: *assuming* that we are going to web-enabled editing, does anybody
have an objection to moving back to XHTML for these documents?



shap