announcing mdoc.su, short manual page URLs

[Constantine A. Murenin]

Paul Schenkeveld wrote:
> On Tue, Feb 19, 2013 at 12:27:01AM -0800, Constantine A. Murenin wrote:
>> Dear freebsd-{chat,current,doc}@,
>>
>> I would like to announce and introduce <URL:http://mdoc.su/>,
>> a deterministic URL shortener for BSD manual pages,
>> written entirely in nginx.conf.
>>
>> It supports several address schemes, for example:
>>
>> http://mdoc.su/f/zfs
>> http://mdoc.su/f/zfs.8
>> http://mdoc.su/f/8/zfs
>> http://mdoc.su/freebsd/zfs
>> http://mdoc.su/FreeBSD/zfs
>>
>> http://mdoc.su/d/hammer.5
>> http://mdoc.su/d/hammer.8
>>
>> etc.
>
> Very coooool!
>
> One question: is the os version accessible comewhere, i.e. can I ask for
> a manpage from a specific version of FreeBSD?

Not originally; this would be the first RfE. :-)

The problem is mostly UI design, consistency and the actual mappings.

How would you expect to specify a specific version of FreeBSD?

/f74/stat	?
/f74/stat.2	?
/f74/2/stat	? hmm

/f7/stat	?
/f7/stat.2	?
/f7/2/stat	?  that wouldn't be for 7.2, right?

/FreeBSD-7.4/stat	?
/FreeBSD-7.4/stat.2	?
/FreeBSD-7.4/2/stat	? hmm...

/FreeBSD-7/stat		?
/FreeBSD-7/stat.2	?
/FreeBSD-7/2/stat	? -- again, an ambiguity

/FreeBSD/9/8/zfs ?  not so bad, since the recent RE schedule, until:
/FreeBSD/9/2/stat ? nope, won't do, either
/FreeBSD/9/zfs	?  Wait, that'd be zfs(9), not zfs from "FreeBSD 9"!

So, it gets hairy rather quickly. :)

ATM, none of the above are supported.

Also, consider that this has to be mapped back to the options provided 
by man.cgi on FreeBSD.org, which only has "FreeBSD 9-current" as a 
single-digit-option, with all prior versions being two-number releases 
like "FreeBSD 4.8-RELEASE" (going back to "FreeBSD 1.0-RELEASE"), and a 
couple of "FreeBSD 9.1-stable" for only the latest release of the last 
couple of major versions, and going back to only "FreeBSD 6.4-stable" 
(which will probably soon itself be gone, too), so, I might have to 
maintain a separate mapping from "f4" to, say, "FreeBSD 4.11-RELEASE", 
and such fine-grained mappings is something I'd rather avoid, since the 
chain gets outdated fairly quickly.  Also, how would you distinguish 
between the latest "-RELEASE" and "-stable"?

Remember, this is a deterministic URL shortener, and I don't want it to 
become an "I'm Feeling Lucky"! :-)

I want to make sure to have some realistic mappings, for FreeBSD and 
NetBSD, before adding any such features.  OpenBSD, on the other hand, 
would be pretty easy, since every release is a two digit number, and 
DragonFly man-pages don't let you specify a release, so that's already 
supported. :-)

Adding support for two-digit releases with a scheme like "/f91/" and 
"/FreeBSD-9.1/" is something that's very doable, but do you want to have 
to specify "/f63/" instead of a simpler (though more ambiguous) "/f6/"? 
    What exactly is your usecase?  Mapping between "f91" or 
"(FreeBSD|freebsd)-9.1" and "FreeBSD 9.1-RELEASE", with "9" and "1" 
representing all possible FreeBSD releases (except for subreleases like 
5.2.1, or any releases before 4.0 in the abbreviated notation, e.g. to 
reserve "/f10/" for FreeBSD 10, instead of 1.0), should be very easy to 
add; would that be sufficient?

Best regards,
Constantine.

>
> I have to disagree with Darren Pilgrim however, this is not "slight abuse"
> of rewrite rules but putting rewrite rules to "better use" :-)
>
> Kind regards,
>
> Paul Schenkeveld
>