Last week was a lot about fighting with Texinfo. As I’ve probably said earlier as well, makeinfo –docbook is supposed to make DocBook XML. But it doesn’t really work that well. In the best case, it produces something that is well-formed XML but not really DocBook if you validate it against the DTD. Which means Moin can’t show an HTML rendering of it. In the worst case, makeinfo just segfaults.
In hopes of getting better HTML output from the pseudo-DocBook XML Texinfo files, I tried to use Moin with the latest Docbook XSL stylesheets, 1.73.1. And that resulted in a 4Suite error. See the Moin bug report I made.
So I joined #docbook and #4suite to report about my problems. Michael Smith, one of the DocBook XSL maintainers, was interested and made a workaround that will be in the next release of the stylesheets. See the SVN commit here. Thanks! Uche Ogbuji, a 4Suite developer was also interested to see if I hit a 4Suite bug. He knows the details now, so if it really is a bug, it’ll hopefully get fixed when he has the time to take a look.
In discussions with Michael Smith he convinced me to drop docbook2X and use the DocBook XSL stylesheets for DocBook refentry -> man source transformation. So I modified the ManSource action to use those via xsltproc. I also implemented caching, so that xsltproc doesn’t have to be called every time, if the same man source already exists. ManSource should handle concurrent requests too, but I haven’t done that much testing on it.
Michael had an idea that some of the pseudo-DocBook that makeinfo –docbook makes could be fixed to be valid DocBook with a stylesheet. So I have collected some of these XML files, see http://vpv.kapsi.fi/misc/tagsoups/, take a look if you’re interested. You can try validating those with e.g. xmllint --noout --valid xml-file.xml. If Michael has the time to come up with such a stylesheet, that would be great, since right now makeinfo –docbook produces only two valid DocBook XML files from the whole Fedora updates-released repository!
Yesterday I added support to collect these “well-formed XML but not DocBook” files to the manimport script, so anyone could do the same and take a look at what makeinfo –docbook outputs. I also added some logging to file via the python logging module, so that you can analyze what has append later on and don’t need to save the output that manimport gives to the console.
What I would desperately need is a better way to do Texinfo to DocBook conversions. So either makeinfo –docbook should be fixed or a new converter should be made. Maybe I could report some of these things to the GNU Texinfo people in hope of a better makeinfo. Ideas?
As this is the final full work week of Summercode, here’s a quick list of what will be and what won’t be done:
As the most important point, there won’t be wiki markup as the editing/storage format in the wiki, but DocBook. The main reason is that I won’t have the time to do it correctly, meaning without loss of information. This is mostly because of the problems I’ve had with external tools and conversions during my project. Having wiki markup is possible, though. Probably the best way would be to write a DocBook refentry -> wiki markup XSL stylesheet. Avoiding information loss could be handled by putting in Moin macros where the wiki markup isn’t enough, as suggested by Florian Festi. Those macros would then activate themselves when doing the wiki markup -> DocBook XML conversion. But if Moin macros would have to be used correctly by the users who edit the man pages in the wiki, would it actually be easier for them too to keep DocBook as the format?
Also, there won’t be that much testing during Summercode. Of course I’m testing all the time locally, but large scale testing will hopefully happen after Summercode.
(I’ll talk about only man pages here, info pages are also be mostly supported, but if makeinfo output can’t be fixed, there won’t be much info pages to use…)
Importing man pages from Fedora’s repositories, with support for repository updates and different releases works. Diffing between the same man pages in the different releases works. Getting the man source of a man page in the wiki works. Comparing the changes in the wiki to the original man source is not done yet, but that’s on my agenda for this week. There also aren’t index pages yet, you’ll have to find the man page you want with Moin’s search, but I’d like to add some index page generation to manimport this week too.
There won’t be any kind of official release of the stuff I’ve done yet. I’d like to have it all working on my public test instance, so that some of the features could be shown, though. The reason for not really releasing anything is that my work is based on Moin 1.7, which is still a quite fast moving target. It’ll hopefully be released some time next year and my goal is to have all of my stuff merged into 1.7 main in time for the release. That would also mean making some of the import code more general, as it’s quite Fedora/RPM specific right now. Still, none of this prevents Fedora to run my man/info wiki stuff, the underlaying Moin just won’t be officially stable, so there might be some bugs etc.
Here’s my plan for this week:
- Going through the logs of info importing I made yesterday and seeing if there’s something that could be done to improve info importing without touching makeinfo
- The “diff to upstream source” implementation
- Index pages
- Setting everything up to my public test instance
- Testing
Leave a Reply