Re: [Chicken-users] wiki->texi converter

[Alejandro Forero Cuervo]

> 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.

Excellent!  Thank you very much!

I just commited it, along with some tweaks, to the egg's trunk in the
Subversion repository.

> 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.

I don't have an easy fix for that.

Let me think about it for a while.

> 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".

I suppose the fix for this is to make sure that no two sections in a
set of files that is meant to be used to generate a single Texinfo
document (by appending them) are given the same name.  If Texinfo
can't support that, it should be a user's problem to try to do that.

And, as a fallback, you can use the id parameter that gets passed to
the “make header” procedure in the texi-node driver implemented in
texi-node-driver instead of the “name” parameter.  This is unique for
a given stream of characters that gets passed to wiki-parse (as long
as the "_" character does not occur in section names).  Basically, for
each section name found, if it is the first time it is found, it is
left as is; otherwise, the count of the number of sections with the
same name is appended.

> 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.

How about we simply specify the correct order for the files, instead
of passing them in alphabetical order?  Would that solve the problem?

> 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 am not sure I understand what you mean by "the driver interface in
stream-wiki does not provide for fold-like functionality".  Do you
think we should create a driver that can be instantiated and then used
to capture all the calls made to it and then, given another driver,
just replicate the calls it received?  This would require parsing the
document just once, capturing the calls with an instance of the
"caching" driver and then we would be able to use that one with the
two drivers we need for generating Texinfo.  Do you think that would
solve the problem?

Anyway, I don't think this is too big an issue.

Also, I made the following changes to your code:

1. Remove lots of unrequired calls to format, by changing things like
“(format #f "foo")” into “"foo"”.

2. Changes texi-menu so it won't hash in lookup the results of allll
the lookups (assuming it gets called multiple times).

3. Minor cosmetic changes to keep the style consistant with the rest
of the file.

I hope you don't mind.

Again, thank you very much for your improvements. :-)

Alejo.
http://azul.freaks-unidos.net/