Questions regarding my man/info summer project
vpivaini at cs.helsinki.fi
Tue Jun 12 12:33:45 UTC 2007
(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:
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!
vpivaini at cs.helsinki.fi
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: not available
More information about the fedora-docs-list