Questions regarding my man/info summer project

[Ville-Pekka Vainio]

Hi,

(I'm CCing fedora-docs-list and Ivana Varekova who seems to maintain Fedora's 
man-pages package, I hope that's ok)

As some of you may have noticed already, I'm working on a summer coding 
project that's about man/info page publication and editing with MoinMoin. 
There's a more detailed description here: 
<http://fedoraproject.org/wiki/SummerOfCode/2007/VillePekkaVainio>

I've hit a problem now and I'd like to get your feedback, I assume there are 
some people here who maintain man or info pages with their software.

The problem is choosing the correct storage format for the man/info pages in 
MoinMoin. Publication of those pages is relatively simple, but editing them 
and getting the edits upstream is a completely other thing. For brevity, I'll 
be talking about man pages here only.

It's possible to store the man pages "as such" (as described in man.7) and 
then display them through a Moin parser. But then users editing the pages 
through the wiki would have to know *roff, which probably isn't very newbie 
friendly. On the other hand, Moin would generate "upstream compatible" 
patches from the edits (almost) automatically.

Another possiblity is to store the man pages in wiki markup. That would be 
very easy for the users to edit, as they probably already know it and it's 
simple. But how to get the changes upstream then? A wiki markup -> man source 
exporter would be possible to make, but it's probable that the man source 
generated automatically from the wiki markup would differ a lot from the 
original upstream man page source. So producing meaningful and clean patches 
that could be easily applied would be difficult this way.

The main question here concerning this whole project is: what do we want from 
the project? Do we want the system to be an information source to man page 
maintainers ("this man page could have these points") where they could take 
material from and then add it to the corresponding man pages themselves? Or 
do we want the system to be a tool for the maintainers where they just take 
patches from and apply them with minimal human interaction?

Of course the latter sounds better, but it's also a lot more difficult to 
implement. That's why I'd want some feedback from those who maintain man/info 
pages for their projects. If the system only produced wiki markup or plain 
text diffs, would you still incorporate the changes into your man pages 
(assuming they are reasonable content-wise)?

Also, how would you maintainers describe your workflow when it comes to 
updating man pages? Do you usually get ideas from users and if so, how do you 
incorporate them into your man pages? Or are the man pages usually written by 
the same individual who maintains that specific piece of code?

Even though it seems that the main "audience" for this system would be the 
users and administrators, it definitely wouldn't hurt if it helped the 
developers/maintainers in their work too :)

Thanks in advance for your input!

-- 
Ville-Pekka Vainio
vpivaini at cs.helsinki.fi
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-devel-list/attachments/20070612/d2e4e1da/attachment.sig>