Announcing the Ubuntu Manpage Repository

[Dustin Kirkland]

On Mon, Sep 8, 2008 at 4:12 AM, Dotan Cohen <dotancohen at gmail.com> wrote:
> That's why I don't think that there is need for _yet_ _another_.

I respectfully disagree.  None of the others suited my needs.  I
decided to settle my needs, and make the results available to the
Ubuntu community and others.

> Google can index cgi-generated content just as well as your web
> browser can read it. HTML is HTML no matter in what format the
> original data was stored or who (human or perl) wrote it.

That's not always true.  Google for "site:manpages.debian.net":
 * http://www.google.com/search?q=site%3Amanpages.debian.net

One hit.

On the other hand, go to http://manpages.debian.net and search for a
manpage, such as "dash".
 * http://manpages.debian.net/cgi-bin/man.cgi?query=dash&apropos=0&sektion=0&manpath=Debian+Sid&format=html&locale=en

I saw this same problem with other CGI-based manpage repositories.

>>  * it is entirely free of advertisements and commercials
>
> So are the resources on tldp.

TLDP, yes.  Some of the other alternatives to manpages.ubuntu.com, no.  Such as:
 * http://linuxmanpages.com/man1/ls.1.php

>>  * it contains the precise revision of each manpage as found in the
>> various Ubuntu releases
>
> If you maintain it properly. In my experience with Linux
> documentation, this is rarely the case.

See the documentation by starting at:
 * http://manpages.ubuntu.com/manpages/
and click/browse from there.  There is a cronjob which synchronizes
this with our archives daily.  It looks for packages that have newer
versions available, and it extracts and overwrites the manpages
contained within.

For any given manpage, you can even see the precise package name and
version from which it was extracted.  For instance:
 * http://manpages.ubuntu.com/manpages/intrepid/man1/ecryptfs-setup-private.html
was extracted from "ecryptfs-utils_53-1ubuntu8_i386", as indicated at
the top of that page.  That being the most current version of the
ecryptfs-utils package in the repository.  If I update that package
(and the manpages within), the updates will be published on the site
within 24 hours.

> If fact, if you can pull this
> off consistently for a few years, then you will be king of the docs
> and you will find that devs will write specifically for Ubuntu. I know
> that large software houses (LabView as a recent example that I've
> worked with) currently support SUSE and RedHat but not Ubuntu because
> of the documentation. It's not an issue of deb vs rpm as many people
> like to make it seem to be.

Here here!  Let's solve that problem for sure!  I was initially drawn
toward Ubuntu, in part, due to the outstanding documentation available
at help.ubuntu.com and wiki.ubuntu.com.  If that truly is a barrier
for adoption of Ubuntu, that's one we can certainly solve.

>>  * there are some subtle (and no so subtle) differences between Ubuntu
>> manpages and core utilities from other Debian, Red Hat, SuSE, et al.
>> distributions
>>
>
> And my Ubuntu machine (stock 8.04 Kubuntu install) currently has the
> Debian manpages, because no one ever pays attention to that.

What about utilities that do not exist in Debian or Red Hat or SuSE,
but are firmly rooted in Ubuntu?  Until very recently, Upstart would
fit into that category.  There's ufw.  And hundreds in universe, such
as update-motd which I only wrote very recently.
 * http://manpages.ubuntu.com/manpages/intrepid/man8/ufw.html
 * http://manpages.ubuntu.com/manpages/intrepid/man1/update-motd.html

>> In terms of contribution, all of the source code necessary to generate
>> the repository is available under the GPLv3 in a project on Launchpad,
>> and I welcome extensions of the work:
>>  * https://launchpad.net/ubuntu-manpage-repository
>>
>
> This adds exactly zero benefit to anyone but google spammers at this stage.

That's not a very constructive statement, and totally against the
spirit of open source development and collaboration.

>> As for direct contribution to The Linux Documentation Project, I'm not
>> sure I understand your suggestion.
>>
>
> I will rephrase it:
> Do not invest your time duplicating efforts, instead invest your time
> contributing to existing projects.

If you're looking to recruit new tech writers, see the Ubuntu-Doc
mailing list archives.  There are probably 10+ people *per week*
volunteering to give their time writing documentation, literally
begging for direction and advice as to where their skills could be put
to use.

I'm a developer who quite simply sometimes wanted to read manpages in
a web browser that I may, or may not have installed on my system, and
specifically the version of the manpage that shipped with a particular
version of Ubuntu.  That was my itch, I scratched it, entirely
voluntarily.  When I showed it to a few people, they liked it, and
thus I open sourced the code, sought, and received approval for
Ubuntu.com to host the resource.  The response has been overwhelmingly
positive, and most of the criticism being constructive feedback on how
to make the utility better.  Obviously, not everyone feels that way.
But hey, no one is forcing anyone to use it....

:-Dustin