search

OpusVL / perldoc.perl.org

perldoc.perl.org website
26 stars 10 forks source link

Please can we forward perldoc.perl.org to the already stable replacement perldoc.pl ? #45

Closed shadowcat-mst closed 5 years ago

shadowcat-mst commented 5 years ago

Since perldoc.perl.org development basically stopped the community got together and figured out what we wanted from a replacement - and built perldoc.pl, complete with link compatibility to make switching over smooth.

I've been trying to get in touch for over a year to arrange this now - there simply doesn't seem any point to trying to migrate to a half-a-rewrite like this repo when we already have a complete superior rewrite that's proven in production and addresses many issues that have been brought up by users.

The original perldoc.perl.org was a fantastic contribution, and I'd hope that it's understood that the building of a version 2 and my choice to be involved in the feature/spec process for that should be taken as a massive compliment in terms of the original'is utility, but at this stage I genuinely believe it's time to move on (and avoid duplicating work already done and deployed).

shadowcat-mst commented 5 years ago

(note we've been trying to discuss this with JJ for a while but have had a lot of trouble getting in touch; I'm sorry that a bunch of effort has gone into this repository that turned out to be pointless but please don't let the sunk cost fallacy push you into trying to carry on with this anyway - at least all of the IRC channels I'm in have switched to using perldoc.pl for every link we provide and I find it unlikely they're going to go back at this point)

genio commented 5 years ago

:+1: for making perldoc.perl.org a CNAME to perldoc.pl

tm604 commented 5 years ago

The new design looks good, any chance of taking the perldoc.pl webapp and adapting the work on layout/CSS to that?

perldoc.pl already has search and working links (e.g. pages such as perlandroid which aren't found in either perldoc.perl.org or perldoc2.perl.org), so it seems like a better base than the static site build approach.

shadowcat-mst commented 5 years ago

The more I look at this the more I think "the design is divine, the implementation is a WOFMAT".

Suggestion: do what @tm604 said in terms of the design stuff, use a static export (i.e. dancer/wallflower style) to get static files out of perldoc.pl for everything except search, and then accept that working search is good and share the existing deployment with perldoc.pl

I don't honestly see why the "static files ONLY" hard requirement still matters when we already have a volunteer for running the dynamic version, that has proven uptime and works fine. Kinda feels like you're reskinning search.cpan.org after metacpan was already live here.

Grinnz commented 5 years ago

As the author of perldoc.pl: I hope it's now clear the number of issues you will need to resolve that myself and the Perl community have already hammered out on perldoc.pl. I also think it would be much preferable to have "the official Perl documentation site" have a modern full featured search as similarly has been iterated on for perldoc.pl, which would be incredibly complex to reinvent and difficult to maintain for a static HTML site. So while I am not emotionally attached to whether perldoc.pl is used or not, I think it is both an unnecessary duplication of work and a disservice not to.

tm604 commented 5 years ago

Is there a better place to discuss this? Given that the new site has now replaced the original one and that means the official Perl documentation no longer has search, that's not a great advert for the language. It's a bit disappointing not to see any response at all, we were told that issues raised on this repo would be posted internally and visible to the OpusVL team?

If hosting is an issue for a dynamic site, I'm sure there are companies and people who would be very willing to contribute server space or accounts.

NetworkNode commented 5 years ago

I'm a casual user (i.e. not involved in the perl-lang community) and I didn't know about perldoc.pl until just now. So this is my first impression:

For comparison, here are the function indices:

In particular, notice how the old page lists functions vertically (so you can scan down the list), and also includes a one-line description (so you can figure out which one you're looking for). The perldoc.pl style is practically unusable.

So :-1: for redirecting to perldoc.pl in its current form. If you improve the style and usability a bit (and rewrite /functions) then I'd definitely be in favor.

Grinnz commented 5 years ago

If you feel like opening issues for discussion of improvements, it would be appreciated. Thanks for the feedback.

JohnMica commented 5 years ago

@Grinnz @tm604 @shadowcat-mst

As its been already discussed on this repo https://github.com/OpusVL/perldoc.perl.org/issues (which is the repository ideal for raising issues to the project)

feedback is appreciated and the more specific the issue the better would be to replicate and solve.

PaulGWebster commented 5 years ago

Could anyone who would like to raise additional issues please do so on https://github.com/OpusVL/perldoc.perl.org

Grinnz commented 5 years ago

For what it's worth, I have opened issues for perldoc.pl based on the items mentioned by @NetworkNode that I can act on. Please feel free to add feedback to any issues labeled "question" or open new issues for other concerns. Casual users are a primary target audience but feedback from them is rare so far.

JohnMica commented 5 years ago

this does not seem to be the right place to discuss issues about a different project.

feel free to reference such issues between projects but discuss the issues where they belong.

Grinnz commented 5 years ago

Apologies for the sidetrack, but that was not the purpose of this ticket.

nuclight commented 5 years ago

https://perldoc.pl is banned in some countries, at least Russia (governments are blocking entire segments in war with e.g. Telegram, many innocent sites are also affected). And if one need web-docs (instead of usual local perldoc), then most likely tools to circumvent censorship (VPN, etc.) are not available at that place. So just forwarding is not an option.

Grinnz commented 5 years ago

@nuclight I have not forgotten that issue (https://github.com/Grinnz/perldoc-browser/issues/7). CNAME is not a redirect. If it's IP based, additional servers can easily be deployed to mitigate the issue should this path be chosen.