Re: GSoC: Publishing man/info pages

[Karsten Wade]

On Thu, 2007-03-22 at 11:50 -0700, MBurns wrote:
>  Hi all,
>  
>  I'm interested in working on one of the Fedora bounties, specifically
>  the 'publishing man pages' project [1]. For those that might not know,
>  the project is to have an automated way to grab all the man and info
>  pages from a release and put them on the web to be searched and
>  browsed online. Extending that, putting the documentation into a wiki
>  system is also possible (and open some interesting opportunities, in
>  my eyes). 
>  
>  I was wondering what some of the groups thoughts and goals of this
>  project might be. Both so that ideas can be brought out early, but
>  also to know what I might be getting myself into :) 
Good idea.  Having this discussion in the open makes sure we are all
working from a common ground.

>  So I pose the questions: 
>  *Would you like to see man/info pages be online? (broken down by
>  release version, etc, or not) 
Yes.  Able to be indexed for a search.

>  *Would you want them in a wiki? 
Depends.  If we could make the Wiki accept changes and write them to the
real man page source, then it makes sense.  That seems like a very hard
thing to accomplish.  Maybe just a subset of the man/info pages, such as
the ones where Fedora is the upstream (anaconda, system-config-*, etc.).

Otherwise, I'm not sure it makes sense to put in a wiki.  We could use
it as a way to accept edits/suggestions, but if we have to manually port
them to the man/info source ... well, we have to think if it is worth
it.  If that is a role this project wants to take.

My sense is that we want to see improvements in the man/info pages, but
cannot take on too much work around it without an improvement in the
basic tools.  Committing changes to TeX files in CVS does not sound like
an improvement. :)

>  *What about pushing changes on the wiki back to the maintainers of
> the
>  respective packages? 
Such as, have a mapping of content to who owns it?  Then issue an email
that is a diff or a patch?

That's not a bad idea.  It could get annoying, so maybe we need a way to
bundle up all the changes into one send, v. sending every time someone
saves a change to the wiki.
 
>  *Would this be a welcome addition or just more work? 
As detailed above.  If it is more work but gives a great benefit, we
should consider doing it.

>  *What would you like to see this project accomplish in terms of
> Fedora
>  Documentation? (hopefully beyond just googling for a man page and
>  having it return a fedoraproject.org URL) 
That is a really good question!  This project is fairly old, so maybe
the motivations are lost in the mists of time.

I think this stretches waaaaaay back to an old Red Hat Docs Team goal of
converting all the man pages to a DocBook format, and then work on
improving them.

The main motivations I can think of are:

1. Provide useful, Fedora-specific content (man/info pages that only
appear in Fedora)
2. Make this content available in many ways (CLI, WUI, but if they were
XML, they could appear in GNOME Yelp or KDE Help)
3. Contribute fixes back upstream to improve the state of all content

It is the latter that is truly the most interesting ... and also the
hardest to accomplish.

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\