From fcaccd6f487da29afb4865cb2d10f29d30562aaf Mon Sep 17 00:00:00 2001 From: Yorhel Date: Sun, 9 Oct 2016 09:23:16 +0200 Subject: [PATCH] Document some URLs + add URLs to link to specific man pages --- www/index.pl | 106 +++++++++++++++++++++++++++++++++++++++++++++++---- www/man.css | 6 ++- 2 files changed, 103 insertions(+), 9 deletions(-) diff --git a/www/index.pl b/www/index.pl index d5062c3..164dc28 100755 --- a/www/index.pl +++ b/www/index.pl @@ -49,7 +49,10 @@ TUWF::register( qr{pkg/([^/]+)} => \&pkg_list, # pkg/$system/$category/$name (/$version); $category may contain a slash, too. - qr{pkg/([^/]+)/(.+)?} => \&pkg_info, + qr{pkg/([^/]+)/(.+)} => \&pkg_info, + + # Redirects for canonical URLs + qr{man/([^/]+)/(.+)} => \&man_redir, # Redirects for old URLs. # /browse/ has been moved to /pkg/ with the package category added to the path @@ -154,11 +157,61 @@ sub about { _ end; + h2 'URL format'; + lit <<' _'; +

You can link to specific packages and man pages with several URL formats. + These URLs will keep working in the future, so you should not have to worry + about eventual dead links.

+

Man pages

+

The following URLs are available to refer to an individual man page:

+
+
/<name>/<8-hex-digit-hex>
+ This is the permalink format for a specific man page (e.g. /ls/910be0ed).
+
/<name>[.<section>]
+ Will try to get the latest and most-close-to-upstream version of a man + page (e.g. /socket or /socket.7). Note that this may fetch the man page + from any available system, so may result in confusing scenarios for + system-specific documentation.
+
/man/<system>/<name>[.<section>]
+ Will get the latest version of a man page from the given system (e.g. /man/ubuntu-xenial/rsync)
+
/man/<system>/<category>/<package>/<name>[.<section>]
+ Will get the latest version of a man page from the given package (e.g. /man/ubuntu-xenial/net/rsync/rsync)
+
/man/<system>/<category>/<package>/<version>/<name>[.<section>]
+ Will get the man page from a specific package version (e.g. /man/ubuntu-xenial/net/rsync/3.1.1-3ubuntu1/rsync)
+
+

Currently, the last three URLs will perform a redirect to the + appropriate permalink URL, but this may change in the future.
+ In all URLs where an optional .<section> can be provided, + the search is performed as a prefix match. For example, /cat.3 will provide the cat.3tcl man page if + no exact cat.3 version is available. Linking to the full + section name is also possible: /cat.3tcl. If no + section is given and multiple sections are available, the lowest section + number is chosen.

+

Packages

+

Linking to individual packages is also possible. These pages will show a + listing of all manual pages available in the given package.

+
+
/pkg/<system>/<category>/<package>
+ For the latest version of a package (e.g. /pkg/arch/core/coreutils).
+
/pkg/<system>/<category>/<package>/<version>
+ For a particular version of a package (e.g. /pkg/arch/core/coreutils/8.25-2).
+
+

Note that this site only indexes packages that actually have manual + pages; Linking to a package that doesn't have any will result in a 404 + page.

+ _ + h2 'The indexing process'; p; lit <<' _'; All man pages are fetched right from the (binary) packages available on the public repositories of Linux distributions. In particular:
-
Arch Linux
The core, extra and community repositories are fetched from a local @@ -191,7 +244,7 @@ sub about { restricted and multiverse) from the $release, $release-updates and $release-security repositories are indexed. Backports are not included at the moment. Indexing started around mid June 2012.
-

+ Only packages for a single architecture (i386 or i686) are scanned. To my knowledge, packages that come with different manuals for different architectures either don't exist or are extremely rare. It does happen that @@ -432,6 +485,39 @@ sub pkg_info { } +sub man_redir { + my($self, $sys, $path) = @_; + + # Path can be: + # 1. + # 2. // + # 3. /// + + $sys = $self->{sysbyshort}{$sys}; + return $self->resNotFound if !$sys; + + my $man; + if($path !~ m{/}) { # (1) + ($man) = $self->dbManPrefName($path, sysid => $sys->{id}); + + } else { + $path =~ s{/([^/]+)$}{}; + my $name = $1; + + my($pkg, $ver) = pkg_frompath($self, $sys->{id}, $path); # Handles (2) and (3) + return $self->resNotFound if !$pkg; + + my $verid = $ver && $self->dbPackageVersions($pkg->{id}, $ver)->[0]{id}; + return $self->resNotFound if $ver && !$verid; + + ($man) = $self->dbManPrefName($name, sysid => $sys->{id}, pkgid => $pkg->{id}, pkgver => $verid); + } + return $self->resNotFound if !$man; + + $self->resRedirect("/$man->{name}/".substr($man->{hash}, 0, 8), 'temp'); +}; + + sub manjslist { my($self, $m) = @_; @@ -798,15 +884,19 @@ sub dbPackageGet { sub dbPackageVersions { - my($s, $id) = @_; + my($s, $id, $version) = @_; + + my %where = ( + 'package = ?' => $id, + $version ? ('version = ?' => $version) : (), + 'EXISTS(SELECT 1 FROM man m WHERE m.package = v.id)' => 1, + ); return $s->dbAll(q{ SELECT id, version, released - FROM package_versions v - WHERE package = ? - AND EXISTS(SELECT 1 FROM man m WHERE m.package = v.id) + FROM package_versions v !W ORDER BY released DESC}, - $id) + \%where) } diff --git a/www/man.css b/www/man.css index 42ba3f6..c4efe8b 100644 --- a/www/man.css +++ b/www/man.css @@ -9,12 +9,14 @@ h1 { font-size: 24px; font-weight: normal; color: #abc; } h1 a { font-size: 12px; vertical-align: top } h2 { font-size: 21px; margin-top: 40px; color: #468; font-weight: normal; clear: left } h2 + i { font-size: 12px; } +h3 { font-size: 16px; margin-top: 20px; color: #468; font-weight: normal } dd { margin-left: 15px; } a { color: #048; } a:hover { text-decoration: underline; color: #48B;} table { background: #eee; border: 5px solid #f8f8f8; margin: 10px 0; border-collapse: collapse; } thead tr { font-weight: bold; border-bottom: 1px solid #ccc } td { padding: 1px 5px; font-size: 12px; border-left: 1px solid #ccc; } +code { font-family: "Lucida Console", Monospace; font-size: 12px; background-color: #f0f8ff } #header { padding: 4px 20px; border-bottom: 1px solid #888; font: 24px "Arial"; background: url('images/gradients.png') repeat-x; -webkit-border-radius: 8px 8px 0 0; -moz-border-radius: 8px 8px 0 0; border-radius: 8px 8px 0 0; } @@ -53,8 +55,10 @@ td { padding: 1px 5px; font-size: 12px; border-left: 1px solid #ccc; } i.grayedout { color: #aaa; font-size: 13px; } #about { max-width: 900px } +#about dt { margin-top: 5px } +#about dl { margin-bottom: 5px } #about p, #about dd { text-align: justify } -#about ul { padding-left: 20px } +#about ul { padding: 5px 0 5px 20px } #systems li { display: block; float: left; width: 300px; min-height: 70px; margin: 20px 10px; padding-left: 60px } #systems span { display: block; margin-left: -55px; float: left; width: 50px; height: 50px; background-repeat: no-repeat; }