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@xxxxxxxxxxxxxx
Attachment:
pgpVMDKgwxyeu.pgp
Description: PGP signature
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
