[Feature]: Add a cookbook to the website

[arun-mani-j]

Is the feature relevant to the Firefox PDF Viewer?

No

Feature description

PDF.js is a very big library with a lot of features. But the examples in the website is so limited. This leads users confused on common stuff like getting ToC (#19421), tinting pages (#19420) etc. Sometimes API page helps, but it suffers from discovery problem, that is one needs to know that something is there in order to use it. Currently the only way to find things is to read source code of the viewer implementation. But this is not easy or simple.

I think having something like PyMuPDF's docs - https://pymupdf.readthedocs.io/en/latest/the-basics.html will be super helpful. The idea is to have a section called Cookbook where we explain how to do common tasks. Sure we can't list all tasks but we can explain the common ones related to PDFs like:

• Displaying a page
• Displaying a page in HiDPI
• Displaying multiple pages efficiently
• Zooming in and out
• Rotating pages
• Changing colors
• Displaying text of a page
• Searching a PDF
• Getting outline and resolving it
• Get attachments from a PDF (like images)
• Handle links within a document

If the PDF.js team wishes, I'm very much happy to create a PR for the initial version of cookbook.

Please let me know your thoughts.

Other PDF viewers

NA

[Snuffleupagus]

While we probably should have more/better documentation, writing good documentation takes a lot of time/effort and the problem is that once added someone[1] then has to spend time maintaining/updating it with future changes to the library.

---

[1] Given the number of regular contributors, this could become yet another task that the core contributors are essentially "forced" to spend a lot of time on.

[arun-mani-j]

While we probably should have more/better documentation, writing good documentation takes a lot of time/effort and the problem is that once added someone[1] then has to spend time maintaining/updating it with future changes to the library.

[1] Given the number of regular contributors, this could become yet another task that the core contributors are essentially "forced" to spend a lot of time on.

Agreed, this is an unfortunate truth in open source :(

My idea was like - the Display API is relatively stable (compared to Core). And the cookbook's aim is to give an idea of how to do things. So even if it goes outdated, one can always find how to do it through the latest API because they have a rough understanding of things now.

So (ideally) this would not give more trouble to the regular contributors.

[Snuffleupagus]

So (ideally) this would not give more trouble to the regular contributors.

Well, the thing is that it'd still require a whole bunch of work upfront with testing/reviewing and then we'd essentially be "stuck" with maintaining it.[1]

---

[1] This is something that e.g. the TypeScript definitions have unfortunately shown repeatedly, since despite a large number of users wanting that feature it has on many occasions been difficult for us to get help with TypeScript-related problems.

[arun-mani-j]

So (ideally) this would not give more trouble to the regular contributors.

Well, the thing is that it'd still require a whole bunch of work upfront with testing/reviewing and then we'd essentially be "stuck" with maintaining it.[1]

[1] This is something that e.g. the TypeScript definitions have unfortunately shown repeatedly, since despite a large number of users wanting that feature it has on many occasions been difficult for us to get help with TypeScript-related problems.

Ohhh. The type definitions are helpful too but they are a little incomplete like few types are still Object and any.

Anyway if you have a solution on how one can improve the docs and at the same time ensure it does not trouble contributors much, I can help as much as I can.

Though I can't guarantee, since I'm using PDF.js in my product, and most of the steps in my cookbook are directly used in this product, I can at least keep them up-to-date.

Rest assured, no issues ✌️ .