[Chicken-users] wiki->texi converter

[Ivan Raikov]

Greetings,

  I have improved on Graham Fawcett's wiki->texi conversion code in
stream-wiki, and now it is able to produce an almost usable Chicken
manual in Texinfo format. The modified stream-wiki.scm is attached,
along with a test file run.scm that assumes that the Chicken manual
wiki files are in a subdirectory called `chicken-manual', and it
generates an example Chicken Texinfo manual.

Currently, there are several problems with this converter; none of
them are fatal, but eliminating them would result in much better
Texinfo code:

1. All the references in the wiki documents must refer to sectional
units, such as chapters, sections, and subsections. Whereas in a wiki
document you could have a link like [[User's manual]], which points to
a wiki _page_ of that title, the wiki->texi converter does not know
about wiki pages (because the stream-wiki driver API is
stream-oriented, not page-oriented) so in order for a link to be valid
in the Texinfo document, it must point to a section or subsection.

2. There cannot be two sectional units of the same name, anywhere in
the set of wiki files: every sectional unit in the wiki document
becomes a node in the Texinfo document, and Texinfo does not permit
nodes of the same name. In other words, you cannot have a subsection
called "create-directory" in the e.g. wiki page "Unit posix" and the
wiki page "chicken-setup".

3. The ordering of sections in the Texinfo document depends on the
order in which the wiki files were parsed. In the example I have
attached, the files are processed in an alphabetical order, and that
results in an illogical section order. The wiki->texi converter is
able to recognize the Next: and Previous: links in the wiki, and it
updates the Texinfo navigational links accordingly, so navigation
works, but the top-level node index is in alphabetical instead of
logical order. Since circular links are allowed in the wiki, this
problem might be very difficult to fix.

4. Finally, the converter is rather slow, because it has to do two
passes over the content, one to build the navigational menu, and one
to actually convert the content to Texinfo format. This is a
consequence of the fact that the driver interface in stream-wiki does
not provide for fold-like functionality. 

I would much appreciate any feedback and further improvements of this
converter, and I hope we can have a Chicken Texinfo manual in the near
future. 


  -Ivan

stream-wiki.scm
Description: Text document

run.scm
Description: Text document