Skip to content

Loading…

Duplicate proposals for download filenames #13

Closed
rebos opened this Issue · 7 comments

3 participants

@rebos

The app proposes the same download filename for certain documents althoug they have a totally different content. For example the requests to convert the documents "perlunitut" and "perlreftut" both lead to the proposed download filename "perl-5.14.2.epub". This behaviour can be observed with all tutorials and most of the FAQ documents, for instance.

It seems to me, as if this could be a problem caused by the returning JSON data from MetaCPAN - or rather the app interpretating this data.

The request for "perlunitut" (http://api.metacpan.org//v0/search/autocomplete?&q=perlunitut) returns the following data (extract):

"fields" : {
  "documentation" : "perlunitut",
  "release" : "perl-5.14.2",
  "author" : "FLORA",
  "distribution" : "perl"
},

In contrast the request for "Data::Dumper" (http://api.metacpan.org//v0/search/autocomplete?&q=data++dumper) generates this response (extract)

"fields" : {
  "documentation" : "Data::Dumper",
  "release" : "Data-Dumper-2.131",
  "author" : "SMUELLER",
  "distribution" : "Data-Dumper"
},

I think the app uses the value of the key "release" as a part of the filename to send to the client. In the mentioned cases above, this unfortunately is ambiguous: There are several (tutorial) documents that have "perl-5.14.2" as their release.

Besides, this issue is an addition or special case to issue #12, because the content is not as expected as well.

Nevertheless a great app - please keep improving it!

Greetings,
rebos

@borisdaeppen
Collaborator

Hello rebos,

thanks a lot for your report!

Your analysis is correct, we use the release for the filename... but not only for the filename, also for the content.
This means, that both "perlunitut" and "perlreftut" should result in the very same e-book, which in this case is "perl".

The reason why we do it like this is, that a lot of code on CPAN comes with several modules (which seems to be the field "documentation" in the JSON). If you look e.g. at Mojolicious or Moose you will see that there are plenty of modules inside the distribution. By putting the complete distribution (versioned: release) into the e-book, a reader can now read everything about this distribution that he may want to know. He can jump from one module to another by using the table of contents. Otherwise he would need to download like 100 e-books to have all the documentation for some big distributions. Often the POD from one Module is so small that is seems silly to put just that into one single e-book.

So... this is why we did it like that. But you are completely right, for all the stuff related to the perl-release this sucks somethimes.
We are not very sure what we should do to make things better.

@reneeb
Owner

Maybe for "perl" we need a specific logic:

  • For dual-life modules grab the CPAN version
  • For other modules that live only in core, grab the docs for that module
  • Define "Bundles" for the rest. So that "perlunitut" creates an ebook with all unicode related doc.
@borisdaeppen
Collaborator

A general solution which is not specific to any distribution would maybe be better, since there are so many things on CPAN that it seems an endless task to take care of them all... there will always be another distribution with special needs for rendering.

How about this idea:

We add a checkbox, with a name similar to

[x] merge distribution

the checkbox would be active by default.
If the user does not want to have the complete release he un-checks it, so he just gets the documentation of the one module he types.

With this solution we would give great flexibility and control to the user. He can solve his problems on his own.

Ps: In a second step we could also support lists of module::namespaces, so that users could create own compositions. But I think the first step is already enough to solve the problems mentioned.

@borisdaeppen
Collaborator

I'm working on this idea:

cpan2ebook -> at branch "issue13"
epublisher-source-plugin-metacpan -> at branch "perlybook_issue13"
@borisdaeppen
Collaborator

@reneeb,

I implemented everything.

Can you please do the following steps:

(1) Update the Repo "epublisher-source-plugin-metacpan" (from master-branch) and release my changes to CPAN
(2) Install the new plugin from CPAN on the server
(3) Test my changes to cpan2ebook (this project here) at master-branch and pull them - if you are ok with them - to the server.

With this changes, the user gets lot more options and control... with one single checkbox.
Regards
Boris

@borisdaeppen
Collaborator

Thanks to @rebos for reporting, and @reneeb for deployment of the fix.
There is now an option to choose if the complete release should be fetched or not.
Issue closed.

@rebos

Thank you for your detailed explanations and the fix! I have just downloaded several tutorial documents from the brand new Perl v5.16 release via perlybook.org. Unchecking the newly available checkbox it works as expected and without problems now. Thanks again for your time and work!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.