On Tue, 2007-06-19 at 15:39 +0200, Florian Festi wrote:
Hi!
I have to admit that I don't have any idea how (or better if) our man pages
are kept up2date.
After having a short look at the groff format I am very sure that no one
wants to edit that. (Info pages are a different thing).
So the question is how can the man pages transformed into wiki markup and
back without loss of information. There is some groff markup that naturally
translates into wiki markup. For all other stuff you could write MoinMoin
macros. For creating the diffs you should be able to translate the wiki page
back to groff and do the diffs between the groff versions insted of the wiki
markup pages. That way the patches are much more likely to be useful for
updating the man pages.
The easiest way of translating page content is using an Formatter. But that
won't help for the non MoinMoin markup features you'd modeled as macros. The
way out is special casing the output of the macros depending on the
formatter used. If they get an groff formatter they return the groff source
otherwise they use the formatter to highlight the text properly.
If you have questions feel free to ask my on #moin or #moin-dev.
Florian Festi
Oddly enough, I just started working on a site with similar
requirements. The bash command I used to convert the man pages to
WikiMedia markup looked something like this:
for i in `ls /usr/share/man/man3/*.bz2` ; do bunzip2 -c $i | man2html
| html2wiki --dialect MediaWiki --encoding iso-8859-1
--base-uri
http://wikux.org --wiki-uri
http://wikux.org/
/home/lyz/Programming/Web/Wikux.org/man3bz2/$i.wiki ; done
As you can see, the main tools used were man2html and html2wiki.
I never considered going the other way around, but did keep the markup
results handy so they could be diffed to check for updated pages.
There was also some sedding going on to get the links to work properly.
The end result is at
wikux.org if anyone is interested or wants to help
out.
Please CC me on emails that reply to this as I don't follow the very
closely.
~tom