Re: [Chicken-users] Chicken manual in Texinfo format

[Joerg F. Wittenberger]

Adhi Hargo wrote:
> --- Alejandro Forero Cuervo <address@hidden>
> wrote:
> 
> > It's best to keep the authoritative version of the manual in wiki
> > format instead of Texinfo.  I think this makes it easier for most
> > to contribute to it.  I also think a Texinfo version should be
> > generated from it.
[...]
> apply the right tag. in the long run, wiki->texi
> conversion loses a lot more semantic information than
> the other way around, so much so that wiki != quality
> reference.
> 
> *But* I agree, that the main focus should be ease of
> contribution.

My 0.02 cent, for what it's worth to consider.

a) Taking the ease of contribution argument one step further: I have
always seen wiki syntax as kind of a non-authoritative visual
respresentation intented for a certain editing task.  (Because I've
never been able to decide upfront, which wiki syntax I like most,
since each of them has it's merits.)  So most of the time I - as an
authro - would like to choose the syntax I'm most familar with...which
implies that the abstract contributer needs to be able to choose the
syntax per edit session, not per page and upon page creation time (for
all future contributers and contribution).

b) Data formats, if not strictly defined and widely deployed (in
different applications), have a tendency to develop over time.
Eventually you end up like "word": backward compatible for about one
version and a half.  Prepare to keep converting you old documents!

c) Therefore I'd always recomment to *store* some strictly checked
format, while serializing to the fashion-of-the-day, human readably
syntax in the very moment of delivery for edit/display.

d) Example: Long ago (in '96 cvs said) I wrote "sdc" (Sgml Document
Comipler) in Scheme (bigloo).  Using James Clarks nsgmls parser it
converts SGML into a lazy evaluated stream of tag events and applies
stream operators from a template in a way very simillar to sxml-tool's
prep-post-order tree traversal.  This saved my day.  I could type in
my own SGML syntax (oh boy, I *loved* those data tag and minimization
features) patterned after LaTeX documents.  Sdc would convert that via
latex or lout into postscript, into gnu info files (directly in
scheme, no texinfo involved), man pages and html.  It did the indexing
and cross referencing.  And it did even allow me to mix my prefered
table syntax (roff) with lout graphics and LaTeX formulars in one SGML
source file.  (For reference
http://login.softeyes.net/jfw/CC/sdc.tar.gz )

But the advantage of that approach: I always knew the "way out": dump
the tag stream in simple SGML (which later got the name XML) and read
that in whatever tool I'll ever like.

(BTW: sdc was not that bad of a deal for me: once I've been asked "we
have this huge amount of GML documents at that IBM Host machine and we
want to get rid of the 1M bugs a year it costs us.  sdc got a new
frontend and a specialized style sheet.  Now they have docbook.)


  So I'd recomment to enfore strict checks on canonicalized wiki
  content.  Store that as S-Expressions or XML, no fancy parsers.

  Hint: the canonicalization process could add sensible defaults for
  mandatory items to give the user an idea, what to complete/change.


The Askemos website works that way too.
http://www.askemos.org/A849640f672ed0df0958abc0712110f3c/HowToEditThisPage
The wiki stores some html plus some wiki specific tags (cross
references seen as back links, "include that other page here
literally" to compose big pages from componets and cross references
into other wikis [the askemos wiki allows to be stacked]).  The
"source" template will show the page source in text/xml by default and
present an option to change into some wikipedia style (not exactly, I
tried to parse the syntax using lalr, so I needed to modify the syntax
anyway; and I'm not yet satisfied with the result of the "serialize as
wikipedia" procedure).

best regards

/Joerg