From 735e83686ba2dd7a658ddcac44bb4d1bfd66de7f Mon Sep 17 00:00:00 2001 From: Brendan Dahl Date: Thu, 27 Jun 2013 16:22:20 -0700 Subject: [PATCH] Update and cleanup readme. --- README.md | 165 +++++++++++++++++++++++++----------------------------- 1 file changed, 75 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 850b23360..da27e67ba 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,51 @@ -# PDF.JS +# PDF.js -pdf.js is an HTML5 technology experiment that explores building a faithful -and efficient Portable Document Format (PDF) renderer without native code -assistance. +PDF.js is Portable Document Format (PDF) viewer that is built with HTML5. -pdf.js is community-driven and supported by Mozilla Labs. Our goal is to -create a general-purpose, web standards-based platform for parsing and -rendering PDFs, and eventually release a PDF reader extension powered by -pdf.js. +PDF.js is community-driven and supported by Mozilla Labs. Our goal is to +create a general-purpose, web standards-based platform for parsing and +rendering PDFs. - +## Contributing -# Getting started +PDF.js is an open source project and always looking for more contributors. To +get involved checkout: + ++ [Workflow](https://github.com/mozilla/pdf.js/wiki/Contributing) ++ [Style Guide](https://github.com/mozilla/pdf.js/wiki/Style-Guide) ++ [Good Beginner Bugs](https://github.com/mozilla/pdf.js/issues?direction=desc&labels=5-good-beginner-bug&page=1&sort=created&state=open) ++ [Priorities](https://etherpad.mozilla.org/pdfjs-priorities) ++ [Attend a Public Meeting](#weekly-public-meetings) + +For further questions or guidance feel free to stop by #pdfjs on +irc.mozilla.org. + +## Getting Started ### Online demo -For an online demo, visit: - + http://mozilla.github.io/pdf.js/web/viewer.html -This demo provides an interactive interface for displaying and browsing PDFs -using the pdf.js API. +### Browser Extensions -### Extension +#### Firefox -A Firefox extension is availble in two places: +PDF.js is built into version 19+ of Firefox, however two extensions are still +available that are updated at a different rate: -+ Stable Version: https://addons.mozilla.org/firefox/addon/pdfjs -+ Development Version: http://mozilla.github.io/pdf.js/extensions/firefox/pdf.js.xpi ++ [Development Version](http://mozilla.github.io/pdf.js/extensions/firefox/pdf.js.xpi) - This version is updated every time new code is merged into the PDF.js codebase. This should be quite stable but still might break from time to time. ++ [Stable Version](https://addons.mozilla.org/firefox/addon/pdfjs) - After version 24 of Firefox is released we no longer plan to support the stable extension. The stable version will then be considered whatever is built into Firefox. -The development extension should be quite stable but still might break from time to time. -Also, note that the development extension is updated on every merge and by default Firefox will -auto-update extensions on a daily basis (you can change this through the -`extensions.update.interval` option in `about:config`). +#### Chrome +The Chrome extension is still somewhat experimental but it can be installed two +ways: -For an experimental Chrome extension, get the code as explained below and issue `node make extension`. -Then open Chrome, go to `Tools > Extension` and load the (unpackaged) extension -from the directory `build/chrome`. ++ [Unofficial Version](https://chrome.google.com/webstore/detail/pdf-viewer/oemmndcbldboiebfnladdacbdfmadadm) - *This extension is maintained by a PDF.js contributor.* ++ Build Your Own - Get the code as explained below and issue `node make extension`. Then open +Chrome, go to `Tools > Extension` and load the (unpackaged) extension from the +directory `build/chrome`. -### Getting the code +## Getting the Code To get a local copy of the current code, clone it using git: @@ -50,8 +57,9 @@ PDF files for a file:// url: $ node make server -You can install Node via [nvm](https://github.com/creationix/nvm) or the -[official package](http://nodejs.org). If everything worked out, you can now serve +You can install Node via [nvm](https://github.com/creationix/nvm) or the +[official package](http://nodejs.org). If everything worked out, you can now +serve + http://localhost:8888/web/viewer.html @@ -59,18 +67,22 @@ You can also view all the test pdf files on the right side serving + http://localhost:8888/test/pdfs/?frame -### Building pdf.js. +## Building PDF.js -In order to bundle all `src/` files into a final `pdf.js` and build the generic viewer, issue: +In order to bundle all `src/` files into a final `pdf.js` and build the generic +viewer, issue: $ node make generic -This will generate the file `build/generic/build/pdf.js` that can be included in your final project. The pdf.js file is large and should be minified for production. Also, if you would like to support more browsers than firefox you'll also need to include `compatibility.js` from `build/generic/web/`. +This will generate the file `build/generic/build/pdf.js` that can be included in +your final project. The pdf.js file is large and should be minified for +production. Also, if you would like to support more browsers than Firefox you'll +also need to include `compatibility.js` from `build/generic/web/`. +## Learning -# Learning - -You can play with the PDF.js API directly from your browser through the live demos below: +You can play with the PDF.js API directly from your browser through the live +demos below: + Hello world: http://jsbin.com/pdfjs-helloworld-v2/edit#html,live + Simple reader with prev/next page controls: http://jsbin.com/pdfjs-prevnext-v2/edit#html,live @@ -79,77 +91,32 @@ The repo contains a hello world example that you can run locally: + [examples/helloworld/](https://github.com/mozilla/pdf.js/blob/master/examples/helloworld/) -For an introduction to the PDF.js code, check out the presentation by our contributor Julian Viereck: +For an introduction to the PDF.js code, check out the presentation by our +contributor Julian Viereck: + http://www.youtube.com/watch?v=Iv15UY-4Fg8 -Additional learning resources can be found at: - -+ https://github.com/mozilla/pdf.js/wiki/Additional-Learning-Resources - - -# Contributing - -pdf.js is a community-driven project, so contributors are always welcome. -Simply fork our repo and contribute away. Good starting places for picking -a bug are the top error messages and TODOs in our corpus report: - -+ http://people.mozilla.com/~bdahl/corpusreport/test/ref/ - -and of course our open Github issues: - -+ https://github.com/mozilla/pdf.js/issues - -For better consistency and long-term stability, please do look around the -code and try to follow our conventions. -More information about the contributor process can be found on the -[contributor wiki page](https://github.com/mozilla/pdf.js/wiki/Contributing). - -If you don't want to hack on the project or have little spare time, __you still -can help!__ Just open PDFs in the -[online demo](http://mozilla.github.io/pdf.js/web/viewer.html) and report -any breakage in rendering. - -Our Github contributors so far: - -+ https://github.com/mozilla/pdf.js/contributors -+ https://github.com/mozilla/pdf.js/blob/master/LICENSE - -You can add your name to it! :) - - -# Running the tests - -pdf.js comes with browser-level regression tests that allow one to probe -whether it's able to successfully parse PDFs, as well as compare its output -against reference images, pixel-by-pixel. - -More information about running the tests can be found on the -[contributor wiki page](https://github.com/mozilla/pdf.js/wiki/Contributing). - - -# Additional resources - -Gallery of user projects and modifications: - -+ https://github.com/mozilla/pdf.js/wiki/Gallery-of-user-projects-and-modifications - -You can read more about pdf.js here: +You can read more about PDF.js here: + http://andreasgal.com/2011/06/15/pdf-js/ + http://blog.mozilla.com/cjones/2011/06/15/overview-of-pdf-js-guts/ + +Even more learning resources can be found at: + + https://github.com/mozilla/pdf.js/wiki/Additional-Learning-Resources +## Questions + Talk to us on IRC: + #pdfjs on irc.mozilla.org -Join our mailing list: +Join our mailing list: + dev-pdf-js@lists.mozilla.org -Subscribe either using lists.mozilla.org or Google Groups: - +Subscribe either using lists.mozilla.org or Google Groups: + + https://lists.mozilla.org/listinfo/dev-pdf-js + https://groups.google.com/group/mozilla.dev.pdf-js/topics @@ -157,3 +124,21 @@ Follow us on twitter: @pdfjs + http://twitter.com/#!/pdfjs +## Weekly Public Meetings + ++ Bug Triage - Every Monday 1:00PM PDT\* ++ Engineering - Every Thursday 10:00AM PDT\* + +\*Meeting times can vary a bit, so check on IRC first if you plan to attend. + +### Connection Details + ++ 650-903-0800 or 650-215-1282 x92 Conf# 99363 (US/INTL) ++ 1-800-707-2533 (pin 369) Conf# 99363 (US toll free) ++ irc.mozilla.org #pdfjs for backchannel + +### Meeting Notes + +Follow the format of: ++ Triage - etherpad.mozilla.org/pdfjs-triage-YYYY-MM-DD ++ Engineering - etherpad.mozilla.org/pdfjs-YYYY-MM-DD