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

[Ivan Raikov]

Hello, Alejandro,

  I figured you would respond to this sooner or later :) Thanks for the 
detailed section on generating Texinfo from wiki format. I did in fact
discover Graham's code, and I wrote some code to fill in the missing
functionality, however I haven't tested it yet, because I couldn't 
figure out how to use the code from svn-wiki-post-commit-hooks to run
the wiki->texi converter on the files from the Chicken manual. How 
would you suggest that I go about creating a test harness for wiki->texi
without having to create my own svnwiki site? I really just need to
be able to test the converter code on a bunch of wiki files, without 
having to
go through an svn repository and all that. 

   Also, you might want to consider implementing the eggdoc tags, which 
I find immensely useful when writing egg documentation -- perhaps this
would facilitate the development of egg documentation on the wiki. I 
also like how eggdoc uses SXML -- why not follow its approach and just 
have a wiki->sxml converter and then converters for sxml to whatever. 

 -Ivan

On Thu, May 31, 2007 at 03:38:27AM +0000, Alejandro Forero Cuervo wrote:
> I wish I had seen the thread about the Chicken manual before.  Anyway,
> here are my thoughts.  I'll use a bit of wiki format for this message,
> heh.  I'll try to keep it short.
> 
> == Improving the contents of the manual:
> 
> I agree with the people that think the manual should be improved to
> make it more useful for people not already familiar with Scheme.  I
> think Felix would agree as well (but I'm not sure).
> 
> If you have time to help us improve the manual, by all means do!
> Think you can reorganize it all to have a far better structure?
> Please help!  There is no need to start from scratch.
> 
> Would anyone oppose adding more information about Scheme to the
> manual, even though it may be obvious for advanced users?  I think
> some introductory section or two about Scheme would be great.
> 
> As a matter of fact, Nelson Castillo and I had already started one
> such document (an Unofficial Manual):
> 
>     http://chicken.wiki.br/manual
> 
> Any help integrating it with the official manual would be welcome (I
> think; Felix, what do you say?).
> 
> BTW, if you plan to spend some hours working on the manual, you may
> want to work on it through your text editor (instead of the web
> interface): http://chicken.wiki.br/svn%20checkout
> 
> == Format of the authoritative version
> 
> 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.
> 
> == Generating texinfo from wiki format
> 
> The stream-wiki egg was designed to make it reasonably easy to define
> new output formats that are generated from the wiki file.  Basically,
> you need to define a table of functions (a ??driver??) for the different
> syntactic constructs.  These functions receive as parameters the
> inputs from the wiki format and should return a stream with the actual
> output.  The generic wiki-parse function receives the driver that is
> used to produce the output (wiki->html, for example, is just a wrapper
> that calls wiki-parse with the HTML driver).
> 
> So far the following output drivers haven been defined:
> 
>     ODF:
> 
>         Extremely incomplete.  But, at some point, I'll probably take
>         the time to finish it, since ODF is just XML.
> 
>     HTML:
> 
>         This is the most stable driver.
> 
>     Text:
>    
>         This produces a text document from the wiki.  You can think of
>         it as removing the wiki formatting, though sometimes it does
>         clever things.  For example, the wiki string
> 
>             [[http://opwifi.com|OpWifi Project]]
> 
>         becomes
> 
>             OpWifi Project [http://opwifi.com]
> 
>     Links:
> 
>         This is a variation of the usual driver.  It doesn't really
>         generate any output.  However, it calls a function once for
>         each and every link in the wiki file.  Along with
>         iterator->stream from the stream-ext egg, it gets you a stream
>         with all the links in a wiki file.
> 
>     Tags:
> 
>         This is similar to links.  Gets a list of tags in the file (as
>         in ???[[tags: foo bar quux]]???).  This is soon to be deprecated
>         (the tags should be stored separate from the contents of the
>         files, not as part of them).
> 
>     LaTeX:
> 
>         Works for most constructs, but there are some that it doesn't
>         get well.  I guess it is ok.
> 
>     Texi:
> 
>         Mostly the work of Graham Fawcett.  It is still incomplete.  I
>         think getting this to work should be far less work than
>         starting from scratch.
> 
> I list the drivers here just to reinforce the point that the code in
> stream-wiki egg was written to support multiple outputs and I think
> generating texi directly from wiki should *not* be regarded as ???an
> ugly hack???.
> 
> == Workflow for generating the manual
> 
> The manual should reside in its current Subversion repository.  This
> is a separate discussion as to what format it should use, since it
> could be stored there and still somewhat managed by Svnwiki if it
> became a Texinfo (or whatever) document.  Keeping it there allows most
> of us who have the repository checked out to make improvements easily
> with our favorite text editors.  It also allows casual contributions,
> which are welcome.  I think this supports a very good workflow.
> 
> The only drawback I see is that Svnwiki sometimes becomes unstable
> because of bugs.  While this has not happened in the last months (or,
> if it has, I haven't noticed), I'm almost certain it will occur again
> in the future, as we keep adding features to svnwiki.
> 
> == Generating an index
> 
> We can define any new constructions for extending the wiki syntax in
> SGML-like ways.  Currently, we have this:
> 
>     (define (chicken-egg-html env)
>       (let-from-environment env (params parse path-in)
>         (or
>           (and-let* ((name-stream (assoc 'name params))
>                      (name (stream->string (cdr name-stream)))
>                      (description (assoc 'description params))
>                      (license (assoc 'license params))
>                      (author (assoc 'author params)))
>             (parse
>               (html-stream  
>                 (tr (td (if (file-exists? (svnwiki-make-pathname path-in 
> name))
>                           (format #f "[[~A]]" name)
>                           (format #f "[[~A~A.html|~A]]" *url-eggs* name 
> name)))
>                     (td (cdr description))
>                     (td (cdr license))
>                     (td "[[" (cdr author) "]]")))))
>           stream-null)))
>     
>     (define *extensions*
>       `((chickenegg (code-break ,chicken-egg-html))))
>  
> What that does is replace the string
> 
>     <chickenegg name="chairthrow" description="The best egg ever" 
> license="non-free" author="steve ballmer" />
> 
> with HTML for a table.
> 
> We could, similarly, define support for other tags.  For example,
> 
>     <procedure name="with-input-from-file" parameters="file tunk" />
> 
> could be expanded to something else.  This would allow us to embed
> more semantics in the wiki format, and we could use this to generate
> indexes.
> 
> If we can agree on some templates for the tags we should support and
> the wiki-code the should expand to, I would gladly code them.
> 
> Thanks.
> 
> Alejo.
> http://azul.freaks-unidos.net/