Announcing the Ubuntu Manpage Repository

Dotan Cohen dotancohen at gmail.com
Tue Sep 9 17:55:04 BST 2008


2008/9/9 Dustin Kirkland <kirkland at ubuntu.com>:
> 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.
>

That is a good reason to start a project, but it was not clear at the
beginning exactly what needs of yours were not suited. I should stress
that I am not being argumentive to troll, but rather to identify what
killer feature this new manpage site will provide, that is unavailable
elsewhere.

>> 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.
>

That is because those websites is not designed to be friendly to web
crawlers. Web crawlers use up bandwidth that is meant for humans. You
can see this fact in their link structure, and they specifically
request that web crawlers do not access them:
<META name="robots" content="nofollow">

robots.txt:
# Please don't hammer the server, thanks
User-agent: *
Disallow: /


>>>  * 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.
>

I actually see very few manpages available. If they are automatically
generated from the current packages, then why are they not available
on the site? For instance, in the /en folder of both hardy and
intrepid there are only one manpage each. This is not a fundamental
issue as were the previous issues that I mention, so if it is a
temporary error than no big deal.

>> 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.
>

The end-user documentation in the form of How-Tos and guides in Ubuntu
is getting better and better all the time. However, it is the
traditional documentation sources that are marginalized, and if you
can address that then I support you 100%. But if you are simple
duplicating efforts then obviously I discourage 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
>

I am not familiar with these utilities but I doubt that the
professional, proprietary applications that I mentioned would need
them. Also, I should note that being Debian-based does not help to
foster the interest of proprietary vendors, as the Debian community
has traditionally been very hostile to non-FOSS software. However,
that is not an issue that you can address with this project, in fact,
I do not know if promoting Ubuntu to such communities is one of your
goals, even if documentation would attract them.

>> 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.
>

It is the truth. Sorry. You are very nice in making the documentation
free for mirroring, but with your documentation already available
online, the biggest motivation for mirroring it is for free spider
food. If you are unfamiliar with the them I advise you to stay naive!
The world is full of scum.

> 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 not, but you might want to tap that resource.

> 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.

A, here it is! Now I see the added value.

>  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....
>

Like said, I am all for the effort if it adds value to Ubuntu. If it
reduplicates efforts with no added value, then I would encourage you
to rethink your effort but I do no oppose. That is why I asked what
the added value is, and did not attack your efforts that looked like
reduplication. Now that I know what the added value is, I support your
position.

Good luck!

-- 
Dotan Cohen

http://what-is-what.com
http://gibberish.co.il
א-ב-ג-ד-ה-ו-ז-ח-ט-י-ך-כ-ל-ם-מ-ן-נ-ס-ע-ף-פ-ץ-צ-ק-ר-ש-ת

ä-ö-ü-ß-Ä-Ö-Ü


More information about the ubuntu-devel mailing list