Re: Documentation (was Re: [Chicken-users] How to use prelude?)

[F. Wittenberger]

Am Dienstag, den 30.05.2006, 14:19 -0500 schrieb Alejandro Forero
Cuervo:
> > So why not xml at the end?  At least as the canonical format.
> 
> Because wiki format is easier for humans to work with.

I thought I made that clear: what's human readable should IMHO be
decided based on personal preferences, task at hand etc.

Example: my dad is about 70 years and kowns latex.  I'd love to share
pages with him.  But I forgot latex.  What I mean: the syntax to use
should be chooses at the very moment you start editing.  Because there's
no one-size-fits-all especially not when it comes to syntax.  Therefore
I'd consider it very wise to carefully isolate the syntax decision (in
user interface) from the data format definition.

I could not even vote on wiki syntax (if there was a poll at all) since
I would want at least two options.

The other side:  What's to be stored "for ever" should not have to be
converted again.  Under absolutely no circumstances.  (Why?  Have you
ever heard of legal issues?  How do you keep your timestamps and
checksum when you convert you data?)  If you want svn/wiki to be useful
as a proof of authorship for instance, it would be smart to attach
tamper proof timestamps and author notices with the context's SHA1 -
under germany law.  And if you want it to be useful for german layers
document management, well, there's another law: use XML, ZIP, TIFF.  OK,
this doesn't have to bother you.  I just want to say: the data format
decision can easily exclude a lot of users.

Also eventually there's going to be such a huge amount of data to
convert when the data format support dies off, that there's no chance to
select which data to retain and convert and which to drop.  We've seen
this proprietary data format trap in the 80th.  As a result XML emerged.
Even in 2000 I made my money still from helping people out of that trap
(and in that case they even made the trap themself, i.e., they defined
the data format, which they suddenly could no longer read - a kind of
problem only possible in large enough corporations ;-).

> I know there are editors for XML, but I don't think they can compare
> with the ease of use of typing wiki-syntax in one's favorite text
> editor.  Since, as you point out, one can convert from wiki-format to
> XML and back, I don't see much gain in storing things inside the
> Subversion repository in XML.  Things live “svn diff” would break.

That's why I suggested to think about a line format based XML.  But than
again: the first thing I tell my clients: once you've got so much data
and your software suddenly stops working.  What's than?  If there's a
small programm with close to no dependencies converting that
proprietary/private line based format into XML...great.  We've got a
cheap exit strategy.  Let's continue.

Who's going to document the syntax.  And why invent yet another tag set?
There's dockbook, there's tei, there's this topic something of ibm,
where I lost the reference (but which I'd recommend most).  A lot of
effort went into these tag sets.  Ignoring them is costly.

And how many wiki syntax's is one willing to learn?  What's abut the
entry barrier and learning curve?

> I guess the reason to use wiki instead of XML is the same reason to
> store programs in Scheme (and Java, C, Perl, Python, Haskell, etc.)
> code rather than XML as their canonical form.
> 
> I think the canonical format should be the one that is easier for
> humans to work with (since (1) we expect humans to work on this a lot
> and (2) we can easily convert to formats that machines can work with).

Definately no.  The human editable format is a matter of taste like the
editor of choice is a matter of taste.  And a matter of the task and
hand.  If I suddenly understand that a svg editor could help me to lay
out the programm structure of a large system and then convert that
layout with a few function calls into an actual programm, why should I
use the emacs I'm used to?

No.  I'm just gaining this experience, when this tie between literal
syntax and respective tools and the abstract syntax tree in the head is
broken.  That's a becoming a new freedom to me.


> > This had the added advantage, that the tagset to be used and the
> > wiki syntax are independent decisions to make.
> 
> If you choose to store everything in XML and then let people convert
> to wiki, edit and convert back to XML, you still need your wiki format
> to reflect the semantics of your document.  Sure, the specific names
> of tags can be different, but that is also true if you make wiki your
> canonical format: you can always convert to XML and transform it to a
> different schema.  So I fail to see what the advantage is.

I don't really get that.  If I have an extensible, backward compatible
extensible data format, be it reference syntax xml, sxml or a diff
friendly line base xml (which are all xml info set compatible, short
xml) I'm at the safe site.

Users enjoy the freedom to choose an suitable edit syntax.  System level
can attach meta data as needed and the user experience is in no way
different from your proposal.  Therefore the discussion can be confined
to the question: which data format will be the easiest to read and use
in 200 years?

best regards

/Jörg