Merge branch 'juneau-merge' (updates to ch 1-5 only)

This pulls changes into ch 1-5 from the repository posted by Josh Juneau.
It partly resolves #14. Chapter file
names are taken from Josh's repo, and applied to corresponding files even
those where the content is yet to be updated.

ExceptionHandlingDebug.rst

@@ -1,4 +1,4 @@
-Chapter 6: Exception Handling and Debugging
+Chapter 7: Exception Handling and Debugging
 +++++++++++++++++++++++++++++++++++++++++++
 
 Any good program makes use of a language’s exception handling mechanisms.  There is no better way to frustrate an end-user then by having them run into an issue with your software and displaying a big ugly error message on the screen, followed by a program crash.  Exception handling is all about ensuring that when your program encounters an issue, it will continue to run and provide informative feedback to the end-user or program administrator.  Any Java programmer becomes familiar with exception handling on day one, as some Java code won’t even compile unless there is some form of exception handling put into place via the try-catch-finally syntax.  Python has similar constructs to that of Java, and we’ll discuss them in this chapter.

ModulesPackages.rst

@@ -1,4 +1,4 @@
-Chapter 7: Modules and Packages
+Chapter 8: Modules and Packages
 +++++++++++++++++++++++++++++++
 
 Up until this chapter we have been looking at code at the level of the

ObjectOrientedJython.rst

@@ -1,4 +1,4 @@
-Chapter 5:  Object Oriented Jython
+Chapter 6:  Object Oriented Jython
 ==================================
 
 This chapter is going to cover the basics of object oriented

README.md

@@ -11,8 +11,6 @@ This book is formatted for and available at https://jython.readthedocs.io/en/lat
 
 This book is licensed under CC-BY-SA http://creativecommons.org/licenses/by-sa/3.0/ . Contributions in the form of pull requests are welcome, and are covered by the same license under the "inbound=outbound" part of the github terms of service https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license . More detail on the open book license can be found in the book index and preamble (index.rst).
 
-
-
 ## Version History
 
 
@@ -21,32 +19,66 @@ This book is licensed under CC-BY-SA http://creativecommons.org/licenses/by-sa/3
 | Jython 2.5     | 1.0          | Juneau, J., Baker, J., Wierzbicki, F., Muoz, L. S., Ng, V., Ng, A., & Baker, D. L. (2010). The definitive guide to Jython: Python for the Java platform. Apress. |
 
 
-# Build
+# How to Build the Jython Book from Source
 
 ## Install and Build
 
-Building locally requires Python 3.5 or above. These instructions are for windows. Other platforms should be similar.
+Building locally requires Python 3.5 or above.
+Use of a virtual environment is recommended in order to to isolate this project’s dependencies (the tools).
+All you need to begin with is an installed Python.
 
-1. Clone into a new project directory. 
+### Instructions for Windows Powershell.
 
-`git clone <repo>`
-
-These instructions assume you cloned into the directory `book`. The build needs to be run from the parent of the source folder `book`: it will create sibling directory `build` to hold the generated files.
+1. Create a working directory, say `dg-jython`, and `cd` into it.
+There, clone this repository:
+```
+PS dg-jython> git clone https://github.com/jython/book.git
+```
 
-2. (Optional) Use virtualenv to isolate this project's dependencies 
+These instructions assume you cloned into the directory `book`, a sub-directory of your working directory.
+Do *not* `cd` into `book`: the build runs from the current directory: it will create a sub-directory `build` to hold the generated files.
 
+2. If you do not have `virtualenv`, install it:
 ```
-virtualenv venv
-.\venv\Scripts\activate
+PS dg-jython> python3 -m pip install virtualenv
 ```
+(You may need to specify ``python3`` explicitly as shown, or `py -3`, or it may just be `python` depending on your set-up.)
 
-3. `pip install -r book\requirements.txt`
+3. Now create a virtual environment, activate it and install the tools.
+```
+PS dg-jython> python3 -m virtualenv venv
+...
+PS dg-jython> .\venv\Scripts\activate
+(venv) PS dg-jython> pip install -r .\book\requirements.txt
+...
+```
 
-4. `sphinx-build -N -b html .\book build\html`
+4. You can now build the book as HTML in `./build` with the command:
+```
+(venv) PS dg-jython> sphinx-build -N -b html book build\html
+```
+(The option `-N` suppresses output formatting that impedes reading on a PoSH console.) 
 
 Open `build\html\index.html` with your browser to view the generated documentation.
 
+### Instructions for Linux.
+
+On Linux, it looks like this:
+```
+$ python3 -m pip install virtualenv
+...
+$ python3 -m virtualenv venv
+Using base prefix '/usr'
+...
+$ source venv/bin/activate
+(venv) $ pip install -r book/requirements.txt
+(venv) $ sphinx-build -b html book build/html
+...
+```
+Open `build/html/index.html` with your browser to view the generated documentation.
+
+
 ## Edit and Build
 
-After edits to the markdown files, rerun `sphinx-build -N -b html .\book build\html` to regenerate the documentation.
+After edits to the restructured text files, rerun `sphinx-build -b html book build/html` to regenerate the documentation.
 

Scripting.rst

@@ -1,4 +1,4 @@
-Chapter 8:  Scripting With Jython
+Chapter 9:  Scripting With Jython
 +++++++++++++++++++++++++++++++++
 
 In this chapter we will look at scripting with jython.  For our purposes, I

attribution.rst

@@ -1,26 +1,184 @@
-Attribution
-===========
+Acknowledgment and Dedications
+==============================
 
-Throughout the process of writing this book, many individuals from the community have taken time out to help us out.
-We'd like to give a special thanks to the Python and Jython community as a whole for actively participating in the
-feedback and contributions for this book via the mailing lists.
+Josh Juneau
+-----------
+
+First and foremost, I would like to thank my wife Angela for standing beside me
+throughout my career and writing this book. She has been my inspiration and
+motivation for continuing to improve my knowledge and move my career forward.
+She is my rock, and I dedicate this book to her. I also thank my wonderful
+children: Katie, Jake, Matt, and our new addition Zachary, for always making me
+smile and for understanding on those weekend mornings when I was writing this
+book instead of playing games. I hope that one day they can read this book and
+understand why I spent so much time in front of my computer.
+
+I’d like to thank my parents and grandparents for allowing me to follow my
+ambitions throughout my childhood. My family, including my in-laws, have always
+supported me throughout my career and authoring this book and I really
+appreciate it. I look forward to discussing this book with my family at future
+gatherings as I’m sure they will all read it soon.
+
+My co-workers, especially Roger Slisz, Necota Smith, and Matt Arena, who showed
+me the ropes in IT. Without that knowledge I wouldn’t have ventured into
+learning about Oracle and PL/SQL, which ultimately led to this! I’d like to
+especially thank Roger Slisz and Kent Collins for trusting me to guide and
+develop the applications for our department, and for allowing me the freedom to
+manage my projects and provide the necessary time and resource toward our
+applications and databases.
+
+I’d really like to thank Jim Baker for providing me with the opportunity to
+become the lead author for this book. I appreciate that he believed in me to
+provide the leadership and knowledge to make this book a reality. Jim Baker is
+a great person and a scholar; without him, this book may not have been written.
+Jim and I collaborated to find the other great authors that helped us write
+this book. In the end, I believe that the team of authors that was chosen
+provides the perfect blend of knowledge and skills that went into authoring
+this book. I thank each of the authors for devoting their time and effort
+towards this book; I think that it will be a great asset to the community!
+Thanks for everything, I look forward to writing the second edition soon!
+
+I owe a huge thanks to Duncan Parkes of Apress for providing excellent support
+and advice. I also wish to thank all of our technical reviewers and our Apress
+project coordinator, Mary Tobin. All of their efforts helped to make this book
+complete and we couldn’t have done it without you. Last, but definitely not
+least, I’d like to thank the Jython developers and the community as a whole.
+The developers work hard to provide us with this great technology allowing us
+to write Python on the JVM. Frank Wierzbicki has done an excellent job in
+leading the core of Jython developers to produce 2.5.1, and I know that he’ll
+continue to do a great job leading into the future. Thanks to the community for
+using Jython and providing great ideas and support via the mailing lists;
+without this help I could not provide the newsletter and podcast.
+
+
+Jim Baker
+---------
+
+This book is dedicated to my kids, Zack and Zoe, who are just about the best
+children a dad could hope for: happy, loving, and fun to be with. Fundamentally
+what I love to do is create, so it's wonderful watching you grow!
+
+Three years ago we had this audacious idea in reviving Jython. We would jump to
+supporting the 2.5 version of the Python language. And we would focus on make
+it a suitable platform for running the increasingly large apps that are being
+developed. This meant a renewed focus on compatibility for Jython. Fortunately
+we could leverage the new reality that developers of Python applications,
+frameworks, and libraries increasingly have a committment to strong testing.
+Our problem was tractable because we could use this testing to converge on a
+robust implementation.
+
+This book documents that we in fact achieved this goal, while still preserving
+the ability for you to interactively explore and script the Java platform. In
+other words, Jython has grown up, but it hasn't forgotten what made it both
+useful and fun in the first place.
+
+To my good friend Frank Wierzbicki, we made it happen; Charlie Nutter, for his
+committment to collaboration; Bruce Eckel and Albert Wenger, who both convinced
+me that working on Jython was important; Leslie Hawthorn of the Google Open
+Source Programs Office; Dorene Beaver; John Rose, Brian Goetz, and Ted Leung at
+Sun, for their support of alternative languages on the JVM; Glyph Lefkowitz,
+Jacob Kaplan-Moss, Chris Perkins, and Mark Ramm, for their support of a robust
+Python ecosystem; my fellow Jython developers, Alan Kennedy, Charlie Groves,
+Josh Juneau, Nicholas Riley, Oti Humbel, and Phil Jenvey, not to mention many
+other contributors. And especially to my Google Summer of Code students, now
+also Jython committers, Leo Soto and Tobias Ivarsson: it's been wonderful
+watching you grow as both developers and individuals.
+
+
+Victor Ng
+---------
 
-We also thank the Python and Jython developers for producing this great programming language.  So much hard work
-has gone into the Python language that it has become one of the most solid and widely used object oriented
-programming languages available today.  The Jython developers have done a tremendous job bringing the Jython
-of today up-to-speed with current versions of the Python language.  The Jython community seems to be working
-harder than ever before at making it a viable option for programming modern Python and Java
-applications alike.  Special thanks to those developers who have helped out with this book and still kept Jython
-advancing.
+Thanks to Liz and Rosie for putting up with far too many side projects this
+year. Special thanks to everyone in the Jython and Python developer community
+for making life as a programmer much less painful than it could be.
 
-The authors of The Definitive Guide to Jython would like to offer an extra special thanks to the rest of the
-individuals in this section.  Without your insight or contributions portions of this book may not have
-been possible.
+Leo Soto
+--------
+
+First, thanks to my family for having the patience with me for having taking yet
+another challenge which decreases the amount of time I can spend with them.
+Specially Eliana, my mother, who has taken a big part of that sacrifice, and
+also Nicolás, my brother, who gives encouragement in his particular way. They
+and Leocadio, my father, who rests in peace, forged my personality and share
+credit on every goal I achieve.
+
+Thanks to all my friends for sharing my happiness when starting this project and
+following with encouragement when it seemed too difficult to be completed. I
+would have probably give up without their support and example on what to do
+when you really want something.
+
+Speaking of encouragement, I must mention that Jim Baker is responsible for
+having me on the team who wrote this book: first by mentoring me on Jython and
+later by insisting that I should share part of what I have learned on this
+book. He is a great person and I can only be grateful to have met him.
+
+Thanks to Josh Juneau, our lead author. He coordinated our numerous team and
+made sure we all were on the right track. He did that while also working on a
+lot of chapters and also handling the paperwork. I have no idea how he managed
+to do it. All I know is that he rocks.
+
+Thanks to Duncan Parkes, our editor, and all the technical reviewers who worked
+on this book. Not only by catching mistakes but also by suggesting those
+additions that can seem obvious in hindsight but that would never occurred to
+you.
+
+On the first half of the Django chapter I received a lot of help from Jacob
+Fenwick who discovered some problems on specific platforms and offered valuable
+suggestions to overcome them. Thanks to him many readers won't experience the
+frustration caused when the code shown on the book doesn't work on their
+environment. By the way, while working on Django integration with Jython I've
+met a lot of nice people on the Django community. Special thanks to Jacob
+Kaplan-Moss for his outstanding support when I was working on that area.
+
+And thanks to the Jython community! Starting with our leader, Frank Wierzbicki,
+who has played a crucial role to move Jython forward in the last years. The
+core Jython developers are also really awesome people and I'm immensely happy
+to work with them on the project. And every person of the Jython community I've
+talked to has been nice and even when criticizing they know how to be
+constructive. I'm grateful to work with this community and hope their members
+will find this book useful!
+
+
+Frank Wierzbicki
+----------------
+
+First and foremost, I want to thank my wife, Jill Fitzgibbons, for all of the
+support she has given through all of these years of Jython work. Most of that
+work occurred on weekends, nights, while on vacation, and other times
+inconvenient to my family. My daughter, Lily, who is five at the time of
+writing, has also needed to show patience when her dad was working on Jython
+and on this book. I want to thank my parents, who brought a Commodore 64 into
+the house when I was still impressionable enough to get sucked into a life of
+programming. I also want to thank all of the contributors and users of Jython.
+They make my work on Jython and this book worth doing.
+
+
+Special Thanks
+==============
+
+Throughout the process of writing this book, many individuals from the community
+have taken time out to help us out. We'd like to give a special thanks to the
+Python and Jython community as a whole for actively participating in the
+feedback and contributions for this book via the mailing lists.
 
+We also thank the Python and Jython developers for producing this great
+programming language.  So much hard work has gone into the Python language that
+it has become one of the most solid and widely used object oriented programming
+languages available today.  The Jython developers have done a tremendous job
+bringing the Jython of today up-to-speed with current versions of the Python
+language.  The Jython community seems to be working harder than ever before at
+making it a viable option for programming modern Python and Java applications
+alike.  Special thanks to those developers who have helped out with this book
+and still kept Jython advancing.
 
-**James Gardner** - Thanks to James Gardner for his help in providing us with a working toolset and knowledge to convert
-from restructured text format to MS Word for the Apress editing process.  The open source book was written
-completely in restructured text, and converted to .doc format for the Apress drafts and editing procedures.
-James offered great insight on how he used this process with The Pylons Book, and he also provided us with
-a conversion utility that was used for his book.
+The authors of The Definitive Guide to Jython would like to offer an extra
+special thanks to the rest of the individuals in this section.  Without your
+insight or contributions portions of this book may not have been possible.
 
+**James Gardner** - Thanks to James Gardner for his help in providing us with a
+working toolset and knowledge to convert from restructured text format to MS
+Word for the Apress editing process.  The open source book was written
+completely in restructured text, and converted to .doc format for the Apress
+drafts and editing procedures. James offered great insight on how he used this
+process with The Pylons Book, and he also provided us with a conversion utility
+that was used for his book.