metacpan / metacpan-web

Web interface for MetaCPAN

• Getting Started
  • Installing Manually
    • Installing on macOS
  • Running Tests
  • Running the App
  • Local Git and testing considerations
  • Local Configuration Changes
  • Compatibility Notes

Getting Started

We strongly recommend using metacpan-docker. This will give you a virtual machine already configured and ready to start developing on.

If you prefer not to use Docker, the following commands will get you started:

Installing Manually

carton install
npm install
export PATH="$(realpath ./node_modules/.bin):$PATH"

Installing on macOS

If you like, you can install carton via Homebrew:

brew install carton

If your carton install is having issues with SSL-related modules, you may need to use an OPENSSL_PREFIX. Something like:

OPENSSL_PREFIX="/usr/local/Cellar/[email protected]/1.1.1q" carton install

You may need to check /usr/local/Cellar/[email protected] to find the latest installed path on your system.

Running Tests

You can use the supplied wrapper around prove to run tests:

./bin/prove t

To run the tests in parallel, add -j8 (or however many CPUs you have) to the prove command.

Running the App

carton exec plackup -p 5001 -r

If you'd like to use Gazelle rather than the default Plack server:

carton exec plackup -p 5001 -s Gazelle -r

Local Git and testing considerations

You will want to set up the supplied pre-commit Git hook like so:

./git/setup.sh

which causes precious to be run before each commit. You can manually run this with precious path/to/file

Local Configuration Changes

The back end defaults to fastapi.metacpan.org. Running a local API server is optional and not required to hack on the front end. The address to the API being used can be changed in the metacpan_web.conf file. Ideally you would create a new file called metacpan_web_local.conf that contains

api                 http://127.0.0.1:5000

which will be loaded on top of the existing config file.

Compatibility Notes

On Win32 (and possibly also on other platforms) when using Perl < 5.12, the server started with plackup will generate warnings relating to date parsing. These are caused by Plack due to a bug in the gmtime implementation and can be removed by upgrading to Perl 5.12.

metacpan-web's Issues

finetune result scoring

Hi there! terrific job with the new MetaCPAN!

As we discussed on #metacpan, the results scoring needs to handle some edge cases like exact matches. For example, searching for "Data::Printer" without quotes gives "Printer" as the first result, and "Data::Printer" as the second. The same goes for "data printer" without the quotes. However, if you add the quotes to either of them, you get Data::Printer first.

Thanks again for such a nice interface to CPAN :)

=for line in =head treated as heading text

See:

http://beta.metacpan.org/release/Imager

and note the =for headings

incorrect breadcrumb

http://beta.metacpan.org/module/Test::More

appears under BioPerl

search on mirrors page seems to be a noop

When I visit the mirrors page and enter a search term and click search the search term has no effect.

Duplicate Pod files cause confusion

When a dist contains a README.pod file which is a copy of the main module's Pod, then metacpan.org will think that README.pod is the source file for the module in question.

Example: http://beta.metacpan.org/module/Hailo

The "Source" and "raw" links point to README.pod instead of lib/Hailo.pm. Another problem which results from this is that "Module version" will be empty. The site should give higher priority to .pm files which match the NAME section in the Pod, or just prefer .pm files over .pod in general.

translated cpan urls need the author name upcased

Urls like this:

http://search.cpan.org/~flora/Data-Stream-Bulk-0.08/lib/Data/Stream/Bulk.pm

get translated to:

http://beta.metacpan.org/module/flora/Data-Stream-Bulk-0.08/lib/Data/Stream/Bulk.pm

This should be:

http://beta.metacpan.org/module/FLORA/Data-Stream-Bulk-0.08/lib/Data/Stream/Bulk.pm

Allow browser caching

Currently, a bunch of the resources making up a page appear to me to be non-cacheable. Changing that would be nice.

Some META.json files show up as empty files

http://beta.metacpan.org/source/BINGOS/Acme-Working-Out-Dependencies-From-META-yml-Or-META-json-Will-Be-Wrong-At-Some-Point-Like-This-Module-For-Instance-6.66/META.json

Fix locked panel on the left

Via blog:

One small comment: the sidebar doesn't work well on small screens. I
can't see the lower part of it ("activity") on my laptop because it
doesn't have enough vertical pixels. Can you please disable this
locking thingie you're doing?

I find the sticky panel very helpful, but will fix it to scroll if the screen is not big enough

Font size

The fonts are too small for my screen. Instead of setting them to 12px, try 80%

Search for author:ANDK returns nothing

On the homepage I entered author:andk and author:ANDK and got no results.

Interestingly, author:andk told me "0 results (0.001 seconds)" whereas author:ANDK left the area below the search box white

Line Numbers in Code Snippets

I'm not sure the line numbers are that helpful in code snippets on the Pod pages. On the source code for sure, but I think they tend to clutter the Pod. You may want to consider adding "gutter: false" to the JS config on the Pod pages.

Enable gzip

Link to @metacpan on Twitter

metacpan has a Twitter account: https://twitter.com/#!/metacpan Would be helpful to link to that somewhere on the site so that we can push notifications to users etc

Add Settings panel

Small icon in the top right corner should do. Things you can enable/disable there:

• relative dates
• locked left panel
• hide TOC
• Ellipsis
• more?

Bad summary display

http://beta.metacpan.org/search?q=list%20member

The summary includes the synopsis.

Same goes for http://beta.metacpan.org/search?q=apache2 cookie

perlapi is messed up

http://beta.metacpan.org/module/perlapi

The full pod is generated as part of the make all process. Not sure if/how we should support that.

"search distribution" seems broken...

Incorrect/Incomplete dependencies list

The dependencies list (for example: http://beta.metacpan.org/module/Plack::App::File) is a little confusing...
it doesn't reflect the dependencies of that file, but rather the distribution that it comes packaged in.
It looks like that list comes straight from the dist's META.yml

However, all the modules listed aren't actually used by Plack::App::File (except for parent.pm)
and some modules that are used (like HTTP::Date and Cwd) are not shown.

I see the usefulness in showing the dependencies required for installing that module,
but I also think it's useful to see which ones are required for using that module (which can be completely different).

Perhaps the heading should be changed to "Distribution Dependencies" to reflect where the list comes from?
Actual file dependencies could be shown using something like Perl::PrereqScanner,
or perhaps just link to deps.cpantesters.org (Issue #46).

no id set on items for L<> to link to in pod

Because the id or name isn't set for items in the POD.

eg. on search.cpan.org:

http://search.cpan.org/~tonyc/Imager-0.83/Imager.pm

follow link to the method index and click on the circle() link - you're taken directly to the circle entry in Imager::Draw

on metacpan, the link at

http://beta.metacpan.org/module/Imager

points to:

http://beta.metacpan.org/module/Imager::Draw#circle-

but there's no id set for the circle() dt element.

"Provides" list doesn't seem to be sorted

See http://beta.metacpan.org/release/Git-PurePerl for an example.

Doubly encoded UTF-8?

http://beta.metacpan.org/search?q=%E5%90%8D%E5%89%8D

via comment on http://blogs.perl.org/users/mo/2011/06/introducing-betametacpanorg---a-better-search-for-the-cpan.html

Update Google Groups link

Update Google Groups link in footer, looks like Google closes existing service soon, and moved everything to the new one.
https://groups.google.com/forum/#!forum/cpan-api

"tags with variable width font. Argh."

via http://www.reddit.com/r/perl/comments/htm0h/introducing_metacpanorg_a_better_search_for_the/

Show version dependencies

The right-hand side dependency list in the dist/module view is excellent, but it could be made better. First of all, how about showing the minimum required version, if any? Something like "Capture::Tiny (>=0.11)". Second, can you please list the perl version dependency as well, if one is specified? E.g. "perl (>= v5.14.0)".

Add an "Problem? Open an issue" link on every page

badly formed POD files not indexed

The page

 http://beta.metacpan.org/release/Pod-PseudoPod 

doesn't refer to:

 http://beta.metacpan.org/module/CHROMATIC/Pod-PseudoPod-0.17/lib/Pod/PseudoPod/Tutorial.pod

apparently because it is missing the "NAME" section. While this could arguably be considered a bug in the documentation, such bugs will happen (and that one happened in a Pod:: doc is suggestive). search.cpan.org does index these, by filename.

Fix directory listing

Either disable it or embed the source as HTML:

http://beta.metacpan.org/source/RJBS/Perl-PrereqScanner-1.003/

Left hand search box too wide

In my Firefox on Linux, with my font settings, the left hand search box is too wide and overflows the left column.

Set the width to 95%

Results page - show description, put Synopsis in mouse over

At the moment on beta.metacpan the results page has

-

But it's almost impossible to read the synopsis as it's not formatted, instead it might be better to replace the synopsis with the start of the (first X characters or X sentences maybe).

However showing the synopsis from the result page when a user either clicks a button or mouse over's a link (like you get on https://www.pivotaltracker.com/projects/252059 when you mouse over a speech bubble) would be really useful - even better if it's syntax hi-lighted....

metacpan/metacpan-api#97

Searching for mistyped class name - no results, and search term not displayed

I'm using Opera 11.00, on Linux.

I (accidentally) typed "dbix ckass", and got a results page with 0 results (no "did you mean?") .. I was expecting that my mistyped search term would be displayed so I could fix it, but the search box was also empty.

(I'm told this works in FF.. so maybe its an anti-Opera-ism? ;)

Don't highlight plain files like Changes

You should really only be applying Perl syntax highlighting to Perl source files (pl, pm, t), and certainly not to plain files like the changelog.

Show author results

I often type in an author's name into the search box, and find it annoying that I have to then click somewhere else to do an author search.

How about doing two searches, one for modules, one for authors, and showing both results (or at least the top results for authors)

The site needs a favicon to help those poor people with 200 tabs find the metacpan

As it says on the tin. :)

Search for "html" returns nothing

http://beta.metacpan.org/search?q=html

No not found page for authors

http://beta.metacpan.org/author/does-not-exist gives me a skeleton of an author page (apparently they even have activity!), I expect a not found or similar message.

Allow conflicting files in CPAN distributions

Some CPAN distributions have conflicting files. That is not a problem if they are not both installed on a given system.
But it looks like it is a problem for MetaCPAN.

Example : http://beta.metacpan.org/search?q=which
I would like to be able to read the POD of CWEST/ppt-0.14, not just Win32::App:which (of which I'm the author by the way).
However when I click on the 'which' link for CWEST/ppt-0.14 I'm sent to a link which is not distribution dependent which displays which.pm from Win32::App::which.

UTF-8 links don't work (Acme-ǝmɔA)

I'd hardly consider this important, as the distribution is mostly an experiment in how things handle Unicode, however the second link down on http://beta.metacpan.org/author/dgl links to http://beta.metacpan.org/release/Acme-%C7%9Dm%C9%94A which returns a Not found error.

-dg

"install" link with explanation

Many beginner who are not yet familiar with the way how perl modules can be installed would click on the "download" link and then are puzzled what's next. There could be a link to "install" that when clicked will show some explanation on the various ways how to install CPAN modules.
e.g.

If you are on a linux distribution you should try using the native installer (aptitude, yum etc.
Otherwise explain how to configure and use the various cpan clients. Maybe even pointing at local::lib

Provide permalink for pod sections

See http://packages.python.org/svgwrite/

Each section has a small link next to which can be used as permalink to that exact section.

Code has variable-width font if javascript disabled

If Javascript is disabled, the synopsis at (for example) http://beta.metacpan.org/module/Mojolicious is rendered with a variable-width font.

Expected behaviour would be simply to lose the syntax highlighting, but have a fixed-width font and whatever other styling a JS-enabled user would see.

Source view gives source of a directory listing

e.g. http://beta.metacpan.org/source/ELLIOTJS/Perl-Critic-1.116/lib/Perl/Critic/Policy/ValuesAndExpressions/

I was actually thinking it would be nice if the source view had breadcrumbs along the top linking to directory listings, but obviously that needs directory listings implemented...

/source does not 404 for non-existent files

This is similar to /author - if the file does not exist, the template is rendered with empty content. We should output a 404 page instead.

Broken links to other modules

http://beta.metacpan.org/module/PGXN::API

For example, the link to WWW::PGXN on this page is incomplete:

<a href="WWW::PGXN">WWW::PGXN</a>

We should pull @ioncache into this conversation as this link design was part of search.metacpan.org. Can't remember the exact reason for it. We should just figure something out that works for both sites.

Please make author's dist lists sortable by date and name

Author pages, such as http://beta.metacpan.org/author/FLORA, contain a list of the authors dists. They're already sorted by name. I'd appreciate if optional sorting by release date would be supported as well.

Add link to deps.cpantesters.org

For example http://deps.cpantesters.org/?module=Dist%3A%3AZilla;perl=latest

via rjbs

search for "pod simple xhtml" broken

http://beta.metacpan.org/search?q=pod+simple+xhtml

Doesn't return Pod::Simple::XHTML as first result.

Make dist: a synonym for distribution: in search

distribution: is nice, but long. Please make dist: another way of saying the same thing.

Add "Fork Me on Github" graphic

Distributions which have Github repos could benefit from the familiar "fork me on github" on the top right of the page:

<a href="http://github.com/elasticsearch">
<img alt="Fork me on GitHub" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" style="position: absolute; top: 0; right: 0; border: 0;">
</a>

More prominent links to human-readable special files

When browsing modules on search.cpan.org, it is very easy to find the dist's changelog and readme in the header near the top of the page. On metacpan.org, one has to scroll all the way down to "Other files" in the dist view and wade through a list of unrelated files.

How about adding a list to the right hand side, above the Dependencies, containing links to the dist's human-readable files (Changes/CHANGES,ChangeLog, README, HACKING, TODO)? It would be nice if the list were also visible when viewing a specific module within the dist, as the Dependencies list is.