Use the new readonly_safe_field where appropriate
Patch by: Sverre Rabbelier
====================================How to read the Django documentation====================================We've put a lot of effort into making Django's documentation useful, easy toread and as complete as possible. Here are a few tips on how to make the bestof it, along with some style guidelines.(Yes, this is documentation about documentation. Rest assured we have no plansto write a document about how to read the document about documentation.)How documentation is updated============================Just as the Django code base is developed and improved on a daily basis, ourdocumentation is consistently improving. We improve documentation for severalreasons: * To make content fixes, such as grammar/typo corrections. * To add information and/or examples to existing sections that need to be expanded. * To document Django features that aren't yet documented. (The list of such features is shrinking but exists nonetheless.) * To add documentation for new features as new features get added, or as Django APIs or behaviors change.Django's documentation is kept in the same source control system as its code.It lives in the `django/trunk/docs`_ directory of our Subversion repository.Each document is a separate text file that covers a narrowly focused topic,such as the "generic views" framework or how to construct a database model... _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docsWhere to get it===============You can read Django documentation in several ways. They are, in order ofpreference:On the Web----------The most recent version of the Django documentation lives athttp://www.djangoproject.com/documentation/ . These HTML pages are generatedautomatically from the text files in source control every 15 minutes. Thatmeans they reflect the "latest and greatest" in Django -- they include the verylatest corrections and additions, and they discuss the latest Django features,which may only be available to users of the Django development version. (See"Differences between versions" below.)A key advantage of the Web-based documentation is the comment section at thebottom of each document. This is an area for anybody to submit changes,corrections and suggestions about the given document. The Django developersfrequently monitor the comments there and use them to improve the documentationfor everybody.We encourage you to help improve the docs: it's easy! Note, however, thatcomments should explicitly relate to the documentation, rather than askingbroad tech-support questions. If you need help with your particular Djangosetup, try the `django-users mailing list`_ instead of posting a comment to thedocumentation... _django-users mailing list: http://groups.google.com/group/django-usersIn plain text-------------For offline reading, or just for convenience, you can read the Djangodocumentation in plain text.If you're using an official release of Django, note that the zipped package(tarball) of the code includes a ``docs/`` directory, which contains all thedocumentation for that release.If you're using the development version of Django (aka the Subversion "trunk"),note that the ``docs/`` directory contains all of the documentation. You can``svn update`` it, just as you ``svn update`` the Python code, in order to getthe latest changes.You can check out the latest Django documentation from Subversion using thisshell command:: svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docsOne low-tech way of taking advantage of the text documentation is by using theUnix ``grep`` utility to search for a phrase in all of the documentation. Forexample, this will show you each mention of the phrase "edit_inline" in anyDjango document:: grep edit_inline /path/to/django/docs/*.txtFormatting~~~~~~~~~~The text documentation is written in ReST (ReStructured Text) format. Thatmeans it's easy to read but is also formatted in a way that makes it easy toconvert into other formats, such as HTML. If you're interested, the script thatconverts the ReST text docs into djangoproject.com's HTML lives at`djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ inthe Django Subversion repository... _djangoproject.com/django_website/apps/docs/parts/build_documentation.py: http://code.djangoproject.com/browser/djangoproject.com/django_website/apps/docs/parts/build_documentation.pyDifferences between versions============================As previously mentioned, the text documentation in our Subversion repositorycontains the "latest and greatest" changes and additions. These changes ofteninclude documentation of new features added in the Django development version-- the Subversion ("trunk") version of Django. For that reason, it's worthpointing out our policy on keeping straight the documentation for variousversions of the framework.We follow this policy: * The primary documentation on djangoproject.com is an HTML version of the latest docs in Subversion. These docs always correspond to the latest official Django release, plus whatever features we've added/changed in the framework *since* the latest release. * As we add features to Django's development version, we try to update the documentation in the same Subversion commit transaction. * To distinguish feature changes/additions in the docs, we use the phrase **New in Django development version**. In practice, this means that the current documentation on djangoproject.com can be used by users of either the latest release *or* the development version. * Documentation for a particular Django release is frozen once the version has been released officially. It remains a snapshot of the docs as of the moment of the release. We will make exceptions to this rule in the case of retroactive security updates or other such retroactive changes. Once documentation is frozen, we add a note to the top of each frozen document that says "These docs are frozen for Django version XXX" and links to the current version of that document. * Once a document is frozen for a Django release, we remove comments from that page, in favor of having comments on the latest version of that document. This is for the sake of maintainability and usability, so that users have one, and only one, place to leave comments on a particular document. We realize that some people may be stuck on a previous version of Django, but we believe the usability problems with multiple versions of a document the outweigh the benefits. * The `main documentation Web page`_ includes links to documentation for all previous versions... _main documentation Web page: http://www.djangoproject.com/documentation/