Hello Lists,
I think I finally managed to put the development version of pdfreaders in working order. Now I need your assistance to test the page on different platforms and devices, to prepare translations and to collect and refine suggestions for pdf reader software.
The working page is: http://pdfr.plutonium.fsfeurope.org and we are planning to switch it to the productive domain BY THE END OF THE WEEK.
The SVN branch is: https://svn.fsfe.org/pdfreaders/branches/2013
Here is how you can help:
== Add readers and refine reader information == What's to be done? - Some of the readers on the the list may not be maintained anymore. Find out which, and see to it, that they get kicked out, or marked accordingly. - Some of the readers don't have a working link to the project homepage yet, find the homepage and put it on record. - Some of the readers have incomplete or wrong information regarding platform support and browser integration. Find out which platforms are actually supported by a given reader and complete the list. - some contemporary readers are not yet on the list. Inform us about those, or better yet add them yourself.
How to do it? Readers are defined by json files - a generic file format which is slightly easier for humans to handle than xml. The reader files can be found here: https://svn.fsfe.org/pdfreaders/branches/2013/readers/ Each reader file contains basic information about the reader, a list of operating systems on which the reader runs (the link to an installer is assigned to the OS section), a list of web browsers for which a reader provides plugins, and a list of languages in which the reader is available. Adapt an existing reader file or create a new one and upload it to the svn repository, or send it to this mailing list, so someone else can upload it. Evince and Okular are the most completely defined readers and their definition files should provide good examples. Also see the description of the selection heuristics at the end of this email.
== Adapt translations == What's to be done? For the most part translations can be reused from the old page. However the file path is slightly different (each page got its own sub directory now) and some paragraphs in the "index" and "readers" page changed. In particular there is now some placeholder sections on these pages and the file readers/reader.??.snip has been created to hold some single words for translation. Some of this work can even be done without knowledge of the languages involved.
How to do it? Look at the file hirarchies of the old site: https://svn.fsfe.org/pdfreaders/trunk/src/ and the new site: https://svn.fsfe.org/pdfreaders/branches/2013/src/ Note that all the page files were renamed to index.??.page and moved to a sub directory corresponding to their old name. Note that this might affect hyper links contained in the pages. If you have access to the svn repository, see to it, that all language files get copied to the new position and check hyper links. If you can adapt the translation in one of the reader or index files, please do so and update the file or mail it to the list. The same goes for the new snippet file (reader.??.snip).
== Test the page == What's to be done? - Check hyper links on all translated pages. - Check reader suggestions on different platforms, with different browser configuration. - Whatever you come up with. - Report problems to this list.
How to do it? Get access to different Operating Systems and web browsers, including proprietary software setups. See if the page appears sensible with all setups. Hyperlinks are not setup dependent, except links to installers. For whitebox testing take a look into: https://svn.fsfe.org/pdfreaders/branches/2013/src/scripts/
------------------------------------------------------------------------ == Technical: How is reader selection done? == -- also: what can still be improved --
First thing we need to do is parse the user agent string of a web browser. From this we can identify the OS and browser of the visitor. Unfortunately the agent strings are pretty chaotic and all ready made software libraries we came up with failed in one way or another. So I wrote a new one... which is going to need occasional maintenance when new platforms appear in the wild. We detect the operating system and browser by matching the entire UA string against a sequence of regular expressions. The order of those regexes is important, since many systems include identifiers of other systems in their agent strings. On the first match we return a simplified system / browser identifier to which we refer as "canonical_name". The detection module contains the list of regexes and canonical names: https://svn.fsfe.org/pdfreaders/branches/2013/src/scripts/modules/AgentInfo....
At startup we read all the reader definition files and press them into useful data structures. That is: - One Hash containing all canonical OS names as keys. The value to each key is an array listing all readers that can be run on the corresponding OS. - One Hash containing all canonical browser names as keys. The value to each key is an array listing all readers that can be embedded in the corresponding browser.
Once we have identified the canonical name of the page visitors OS and browser, we just need to fetch the list with corresponding readers from those hashes. Thus we end up with an array, listing all sensible readers for the OS and a second array, listing all sensible readers for the browser.
Ideally we want to suggest a reader, which runs on the visitors platform and does also integrate with her browser. So we calculate the intersection of both lists and end up with a short list of all readers that fit this condition. This list may be empty, in which case we choose to continue working with only the OS based list. All readers have a priority assigned to them in the definition file. This is because we would rather recommend the fancy and fashionable readers (Evince, Okular) over the exotic (BePDF) and ugly (Motif/Xaw3D based) ones. So as a last step we sort the list by priority (lowest number is best number) and suggest the top most reader on the front page. The readers page contains the entire list of recommendable readers plus the list of all readers which won't work well with the visitors setup.
Most part of the reader selection is done in: https://svn.fsfe.org/pdfreaders/branches/2013/src/scripts/modules/Suggest.pm
The files index.pl and readers.pl are the main scripts that deliver the only two dynamic pages on the site. They can be viewed here: https://svn.fsfe.org/pdfreaders/branches/2013/src/scripts/
The language to which a reader has been translated does currently *not* affect the reader selection. Even though, the definition files list the software languages. All reader definition files are read at script startup, which currently means on each page impression. By porting the scripts to FastCGI/WSGI there is a *lot* of time to be saved. ---------------------------------------------------------------------- End Technical Notes
Thank you for your patience, for all the suggestions I didn't embrace yet, and for all the work you have put into pdfreaders.org so far. Now is the time, to introduce new reader software and to get around to giving the new site it's finish.
Sincerely,