Commits

Patrick Samson committed d2f109b

wording

Comments (0)

Files changed (7)

 
 === Direct write to ===
 
-In your site pages, you can put links to initiate the recipient name(s).
+In the pages of your site, you can put links containing the recipient name(s).
 
 Example:
 {{{
 
 === Prefilled fields ===
 
-You may initiate some field contents by providing a query string in the link.
+You may prefill the contents of some fields by providing a query string in the link.
 
 Example:
 {{{
 
 === Recipients Min/Max ===
 
-If you need to constraint the maximum number of recipients in the forms, you can pass the optional
-{{{max}}} parameter to the view.
-There is no parameter for a minimum number, but you can code a custom form and pass a {{{min}}} parameter
-to the recipient field (see Advanced Usage below for details).
+If you need to constraint the maximum number of recipients in the forms,
+you can pass the optional {{{max}}} parameter to the view.
+There is no parameter for a minimum number, but you can code a custom form
+and pass a {{{min}}} parameter to the recipient field (see Advanced Usage below for details).
 
 Views supporting the parameter are: {{{write}}}, {{{reply}}}.
 
 But this parameter does not apply to the default {{{AnonymousWriteForm}}} for visitors:
-The maximum is enforced to 1 (see Advanced Usage below to know how),
-as we want the features available to anonymous users kept to the strict minimum.
+The maximum is enforced to 1 (see Advanced Usage below for knowing how),
+in order to keep the features available to anonymous users to a strict minimum.
 
 Example:
 {{{
 
 ==== Advanced usage ====
 
-If you define your own custom form, you may specify {{{min}}} and {{{max}}} parameters to the recipients field.
+If you define your own custom form, you may specify a {{{min}}} parameter and a {{{max}}} parameter
+to the recipients field.
 
 For example:
 {{{
         recipients = CommaSeparatedUserField(label="Recipients", min=2, max=5)
 }}}
 
-If you do not want the fixed {{{max}}} parameter of the recipients field in your custom form to be superseded
-by the parameter passed to the view, set the form atttribute {{{can_overwrite_limits}}} to False.
+If you do not want the fixed {{{max}}} parameter of the recipients field in your custom form,
+to be superseded by the parameter passed to the view, set the {{{can_overwrite_limits}}}
+form attribute to {{{False}}}.
 
 For example:
 {{{
 
 ==== Advanced usage ====
 
-If you define your own custom form, you may specify a user filter into it.
+If you define your own custom form, you may specify a user filter inside.
 
 For example:
 {{{
     )
 }}}
 
-The filter will be called for each couple to validate that the exchange is possible.
+The filter will be called for each couple, to validate that the exchange is possible.
 
 //Inputs//:
 
 
 ==== Advanced usage ====
 
-If you define your own custom form, you may specify an exchange filter into it.
+If you define your own custom form, you may specify an exchange filter inside.
 
-For example::
+For example:
 {{{
     def my_exchange_filter(sender, recipient, recipients_list):
         # ...
 
 == Auto-complete field ===
 
-An auto-complete fonctionality may be useful on the recipients field.
+An auto-complete functionality may be useful on the recipients field.
 
-To activate the option, set at least the {{{arg_default}}} key in the {{{POSTMAN_AUTOCOMPLETER_APP}}} dictionary.
-If the default ajax_select application is used, define a matching entry in the {{{AJAX_LOOKUP_CHANNELS}}} dictionary.
+To activate the option, set at least the {{{arg_default}}} key in the
+{{{POSTMAN_AUTOCOMPLETER_APP}}} dictionary.  If the default ajax_select application is used,
+define a matching entry in the {{{AJAX_LOOKUP_CHANNELS}}} dictionary.
 
 Example:
 {{{
     }
 }}}
 
-Support for multiple recipients is not turn on by default by django-ajax-selects.
+Support for multiple recipients is not turned on by default by django-ajax-selects.
 To allow this capability, you have to pass the option {{{multiple: true}}}.
 
-Make your own templates, based on these two files, provided as implementation examples:
+Make your own templates, based on these two files, given as implementation examples:
 
 * postman/templates/autocomplete_postman_multiple.html
 * postman/templates/autocomplete_postman_single.html
 
 ==== Advanced usage ====
 
-If you define your own custom form, you may specify an autocomplete channel into it.
+If you define your own custom form, you may specify an autocomplete channel inside.
 
 For example:
 {{{
 
 This is an application for [[http://www.djangoproject.com|Django]]-powered websites.
 
-Basically, the purpose is to allow authenticated users of a site to exchange private //**messages**// within the site.
-In this documentation, the word user is to be understood as an instance of a User, in the django.contrib.auth context.
+Basically, the purpose is to allow authenticated users of a site to exchange private //**messages**//
+within the site.  In this documentation, the word //user// is to be understood as an instance of a User,
+in the django.contrib.auth context.
 
 So it is mainly for a User-to-User exchange.
-But it may be beneficial for a subscriber to receive inquiries from any visitor, that is even if non authenticated.
+But it may be beneficial for a subscriber to receive inquiries from any visitor, ie even if non authenticated.
 For instance, a subscriber as a service provider wants an ask-me-details form on a presentation page
 to facilitate possible business contacts.
-In this case, the visitor is presented a compose message form with an additional field to give an email address
-for the reply. The email is obfuscated to the recipient.
+In this case, the visitor is presented a compose message form with an additional field to give
+an email address for the reply. The email is obfuscated to the recipient.
 
 What is a message ? Roughly a piece of text, about a subject, sent by a sender to a recipient.
 Each user has access to a collection of messages, stored in folders:
 
 In folders, messages can be presented in two modes:
 
-* by **thread**, for a compact view: the original message and its replies are grouped in a set to constitute one sole entry.\\
-  The lastest message (time deposit related) is the representative of the set.
-* by **message**, for an expanded view: each message is considered on its own.
+* by **thread**, for a compact view: the original message and its replies are grouped in a set
+  to constitute one sole entry.
+  The lastest message (based on the time) is the representative of the set.
+* by **message**, for an expanded view: each message is considered by itself.
 
 Here is a summary of features:
 * A non-User (email is undisclosed) can write to a User and get a reply
 * Exchanges can be moderated (with auto-accept and auto-reject plug-ins)
 * Optional recipient filter plug-ins
 * Optional exchange filtering plug-ins (blacklists)
-* Multi-recipients writing is possible (can be disabled by configuration)
+* Multi-recipient writing is possible (can be disabled by configuration)
   with min/max constraints
 * Messages are managed in threads
 * Messages in folders are sortable by sender|recipient|subject|date
 
 It has support for optional additional applications:
 * Autocomplete recipient field (default is 'django-ajax-selects'),
-  with multiple recipients support
-* New-message notification (default is 'django-notification')
+  with multiple recipient management
+* New message notification (default is 'django-notification')
 * Asynchronous mailer (default is 'django-mailer')
 
 === Moderation ===
-As an option, messages may need to be validated by a moderator before to be visible to the recipient.
-Possible usages are:
+As an option, messages may need to be validated by a moderator before to be visible
+to the recipient.  Possible usages are:
 
-* control there is no bad words in the text fields.
-* make sure that no direct contact means are exchanged when the site is an intermediary and delivers services based on subscription fees.
+* to control there is no unwanted words in the text fields.
+* to make sure that no direct contact informations are exchanged when the site is an intermediary
+  and delivers services based on subscription fees.
 
-Messages are first created in a //pending// state. A moderator is in charge to move them to a //rejected// or //accepted// state.
-This operation can be done in two ways:
+Messages are first created in a //pending// state. A moderator is in charge to change them to
+a //rejected// or //accepted// state.  This operation can be done in two ways:
 
-* By a person, through the Admin site. A special simplified change view is provided, with one-click buttons to accept or reject the message.
+* By a person, through the Admin site. A specially simplified change view is provided,
+  with one-click buttons to accept or reject the message.
 * Automatically, through one or more auto-moderator functions.
 
 === Filters ===
 As options, custom filters can disallow messages, in two ways:
 * **user filter**: a user is not in a state to act as a recipient
-* **exchange filter**: criteria for a message between a specific sender and a specific recipient are not fulfilled
+* **exchange filter**: criteria for a message between a specific sender
+  and a specific recipient are not fulfilled
 
 ----
 

Management_Commands.wiki

 
 === postman_cleanup ===
 
-When a user deletes a message, the object is not deleted from the database right away, it is moved to a //trash// folder.
+When a user deletes a message, the object is not deleted from the database right away,
+it is moved to a //trash// folder.
 One reason is to allow a message to be undeleted if the user wants to retrieve it.
-Another reason is that there is only one copy of a message for both the sender and the recipient, so the message must
-be marked for deletion by the two parties before to be considered for a withdraw.
-An additional constraint is that a message may be a part of a thread and the reply chain must be kept consistent.
+Another reason is that there is only one copy of a message for both the sender and the recipient,
+so the message must be marked for deletion by the two parties before to be considered for a withdraw.
+An additional constraint is that a message may be a member of a thread and the reply chain
+must be kept consistent.
 
-So there are some criteria to fulfill for a record to be really deleted from the database:
+So there are some criteria to fulfill by a record to be really deleted from the database:
 
 * both the sender and the recipient must have marked the message as deleted
 * if the message is in a thread, all the messages of the thread must be marked for deletion
-* the delete action must be old enough
+* the action of deletion must have been done enough time ago
 
 A management command is provided for this purpose:
 
 **{{{django-admin.py postman_cleanup}}}**
 
-It can be run as a cronjob or directly.
+It can be run as a cron job or directly.
 
-The {{{--days}}} option can be used to specify the minimal number of days a message/thread must have been marked for deletion.
-Default is 30 days.
+The {{{--days}}} option can be used to specify the minimal number of days a message/thread
+must have been marked for deletion.
+Default value is 30 days.
 
 === postman_checkup ===
 
-A management command to run a test suite on the messages currently in the database.
-It checks messages and threads for possible inconsistencies, in a read-only mode. No change is made on the data.
+A management command to run a test suite on the messages presently in the database.
+It checks messages and threads for possible inconsistencies, in a read-only mode.
+No change is made on the data.
 
 **{{{django-admin.py postman_checkup}}}**
 
-It can be run directly or more profitably as a nightly cronjob.
+It can be run directly or better as a nightly cron job.
 
 ----
 <-//[[Tags and Filters|Previous]]// //[[Home]]// //[[Frequently Asked Questions|Next]]//->
 == Moderation ==
 
-When created, a message is in a //pending// state. It is not delivered to the recipient immediately.
-By default, some human must review its contents and either accept or reject the message.
+When created, a message is in a //pending// state. It is not delivered to the recipient
+immediately.  By default, some person must review its contents and must either accept
+or reject the message.
 
-Moderation is done through the Admin site. To ease the action, a special message type is available:
-PendingMessage. It's nothing but the classic Message type but:
+Moderation is done through the Admin site. To ease the action, a special message type
+is available: PendingMessage. It's nothing else but the classic Message type, but:
 
-* It is intended to collect only messages in the pending state
+* It is intended to collect only messages in the //pending// state
 * A dedicated simplified change view is available, with two main buttons: Accept and Reject
 
 The moderator can give a reason in case of the rejection of the message.
 
 === Auto moderators ===
 
-You may automate the moderation by giving zero, one, or many auto-moderator functions to the views.
-The value of the parameter can be a single function or a sequence of functions as a tuple or a list.
+You may automate the moderation by giving zero, one, or many auto-moderator functions
+to the views.  The value of the parameter can be one single function or a sequence of
+functions as a tuple or a list.
 
 Views supporting an {{{auto-moderators}}} parameter are: {{{write}}}, {{{reply}}}.
 
 }}}
 
 Each auto-moderator function will be called for the message to moderate,
-in the same order as defined in the parameter.
+in the same order as the one set in the parameter.
 
 //Input//:
 
 * an integer between 1 and 99
 
 {{{reason}}} is a string, giving a specific reason for a rejection.
-If not provided, a default reason will be taken from the attribute {{{default_reason}}} of the function,
-if any. Otherwise, there will be no reason.
+If not provided, a default reason will be taken from the {{{default_reason}}} attribute
+of the function, if any. Otherwise, there will be no reason.
 
 The processing of the chain of auto-moderators is managed by these rules:
 
 # If return is {{{None}}} or outside the range 0..100, the auto-moderator is neutral
 # If return is 0, no other function is processed, the message is rejected
 # If return is 100, no other function is processed, the message is accepted
-# Otherwise, the rating will count for an average amongst the other returns
+# Otherwise, the rating will count for an average among the full set of returned ratings
 
 At the end of the loop, if the decision is not final, the sequence is:
 
 # If there was no valid rating at all, then the {{{POSTMAN_AUTO_MODERATE_AS}}} setting applies.
 # An average rating is computed: if greater or equal to 50, the message is accepted.
-# The message is rejected. The final reason is the comma separated collection of reasons
-   related to moderators having returned a rating lesser than 50.
+# The message is rejected. The final reason is a comma separated collection of reasons
+   coming from moderators having returned a rating lesser than 50.
 
 ----
 <-//[[Quick Start Guide|Previous]]// //[[Home]]// //[[Views|Next]]//->

Quick_Start_Guide.wiki

 ==== Optional settings ====
 
 If you want to make use of a {{{postman_unread_count}}} context variable in your templates,
-add {{{postman.context_processors.inbox}}} to the {{{TEMPLATE_CONTEXT_PROCESSORS}}} setting of your project.
+add {{{postman.context_processors.inbox}}} to the {{{TEMPLATE_CONTEXT_PROCESSORS}}} setting
+of your project.
 
 You may specify some additional configuration options in your {{{settings.py}}}:
 
 **{{{POSTMAN_DISALLOW_ANONYMOUS}}}**
 
-    Set it to True if you do not allow visitors to write to users. That way, messaging is restricted to a User-to-User exchange.
+    Set it to True if you do not allow visitors to write to users.
+    That way, messaging is restricted to a User-to-User exchange.
 
     //Defaults to//: False.
 
 
 **{{{POSTMAN_NOTIFIER_APP}}}**
 
-    A notifier application name, used in preference to the basic emailing, to notify users of their rejected or received messages.
+    A notifier application name, used in preference to the basic emailing,
+    to notify users of their rejected or received messages.
 
     //Defaults to//: 'notification', as in django-notification.
 
     If you already have a notifier application with the default name in the installed applications
-    but do not want it to be used by this application, set the option to None.
+    but you do not want it to be used by this application, set the option to None.
 
 **{{{POSTMAN_MAILER_APP}}}**
 
     //Defaults to//: 'mailer', as in django-mailer.
 
     If you already have a mailer application with the default name in the installed applications
-    but do not want it to be used by this application, set the option to None.
+    but you do not want it to be used by this application, set the option to None.
 
 **{{{POSTMAN_AUTOCOMPLETER_APP}}}**
 
-    An auto completer application specification, useful for recipient fields.
+    An auto-completer application specification, useful for recipient fields.
     To enable the feature, define a dictionary with these keys:
 
     * 'name'\\
-        The name of the auto completer application.\\
+        The name of the auto-completer application.\\
         Defaults to 'ajax_select'
     * 'field'\\
         The model class name.\\
         The name of the argument\\
         Defaults to 'channel'
     * 'arg_default'\\
-        No default value. This is a mandatory default value, but you may supersede it in the field definition of a custom form or
-        pass it in the url pattern definitions.
+        No default value. This is a mandatory default value, but you may supersede it in the field
+        definition of a custom form or pass it in the url pattern definitions.
 
     //Defaults to//: an empty dictionary.
 
 ==== Templates ====
-A complete working set of templates is provided with the application.
-You may use it as it is with a CSS design of your own, reuse or extend some parts of it, or only view it as an example.
+A complete set of working templates is provided with the application.
+You may use it as it is with a CSS design of yours, re-use it or extend some parts of it,
+or only view it as an example.
+
+Relations between templates:
+{{{
+    base.html
+    |_ base_folder.html
+    |  |_ inbox.html
+    |  |_ sent.html
+    |  |_ archives.html
+    |  |_ trash.html
+    |_ base_write.html
+    |  |_ write.html
+    |  |_ reply.html
+    |_ view.html
+}}}
+
+If the django-ajax-selects application is used, the following URLs are referenced by this set:
+
+* {% admin_media_prefix %}js/jquery.min.js
+* {{ MEDIA_URL }}js/jquery.autocomplete.min.js
+* {{ MEDIA_URL }}css/jquery.autocomplete.css
+* {{ MEDIA_URL }}css/indicator.gif
+
+The {{{postman/base.html}}} template extends a {{{base.html}}} site template,
+in which some blocks are expected:
+
+* title: in <html><head><title>, at least for a part of the entire title string
+* extrahead: in <html><head>, to put some <script> and <link> elements
+* content: in <html><body>, to put the page contents
+* postman_menu: in <html><body>, to put a navigation menu
 
 ==== Medias ====
-A CSS file is provided with the application, for the Admin site. It is not mandatory.
+A CSS file is provided with the application, for the Admin site: {{{postman/css/admin.css}}}.
+It is not mandatory but makes the display more confortable.
+
+The file is provided under ``postman/medias/``. It's up to you to make it visible to the URL resolver.
+
+For example:
+
+* In a production environment, set /<MEDIA_URL>/postman/ as a symlink to <Postman_module>/medias/postman/
+* In a development environment (django's runserver), you can put in the URLconf, something like:
+{{{
+    ('^' + settings.MEDIA_URL.strip('/') + r'/(?P<path>postman/.*)$', 'django.views.static.serve',
+        {'document_root': os.path.join(imp.find_module('postman')[1], 'medias')}),
+}}}
+
+See also [[Views]] for the stylesheets of views.
 
 === Examples ===
 
         # ...
         'postman',
         # ...
+        # 'pagination'
+        # 'ajax_select'
+        # 'notification'
+        # 'mailer'
     )
     # POSTMAN_DISALLOW_ANONYMOUS = True # default is False
     # POSTMAN_DISALLOW_MULTIRECIPIENTS = True # default is False

Tags_and_Filters.wiki

 == Tags and Filters ==
 
+The following tags and filters are available to your templates by loading the library:
+{{{
+    {% load postman_tags %}
+}}}
+Here are the other special libraries in the {{{postman/templatetags/}}} directory,
+that are not intended for your site design:
+
+* {{{postman_admin_modify.py}}}: a library exclusively designed for a customized change_form
+  template used in the Admin site for the moderation of pending messages.
+
+* {{{pagination_tags_for_tests.py}}}: a mock of the django-pagination application template tags,
+  only usable for the test suite in case the real application is not installed.
+  To rename to {{{pagination_tags.py}}} during the test session.
+
 === Tags ===
 
 ==== postman_unread ====
 
-Give the number of unread messages for a user.
-Return nothing (an empty string) for anonymous users.
+Gives the number of unread messages for a user.
+Returns nothing (an empty string) for anonymous users.
 
 Storing the count in a variable for further processing is advised, such as:
 {{{
 
 ==== postman_order_by ====
 
-Return a formatted GET query string, usable to have the messages list presented in a specific order.
-This string must be put in the href attribute of a <a> HTML tag.
+Returns a formatted GET query string, usable to have the messages list presented in
+a specific order.  This string must be put in the href attribute of a <a> HTML tag.
 
-One argument is required: a keyword to tell the field used for the order. Supported values are:
+One argument is required: a keyword to specify the field used for the sort.
+Supported values are:
 
 * sender
 * recipient
 * subject
 * date
 
-If the list is already ordered by the keyword, the returned value will specify the reversed order.
-If there are other existing parameters, such as a page number, they are preserved in the resulting output.
+If the list is already sorted by the keyword, the returned value will specify
+the reversed order.  If there are other existing parameters, such as a page number,
+they are preserved in the resulting output.
+
+Example:
+{{{
+    <a href="{% postman_order_by subject %}">...</a>
+}}}
 
 === Filters ===
 
 {{{
     {{ message.obfuscated_sender|or_me:user }}
 }}}
-and the sender is the currently logged-in user, the output is compacted to show only the simple pattern '<me>'.
+and the sender is the currently logged-in user, the output is compacted to show only
+the simple pattern '<me>'.
 
-Note that this pattern cannot be confused with the username of a real user, as the brackets are not in the valid character set
-for a username.
+Note that this pattern cannot be confused with the username of a real user,
+because the brackets are not in the valid character set for a username.
 
 ==== compact_date ====
 
 Output a date as short as possible. The argument must provide three date format patterns.
-The pattern used depends on how far the date is from the current datetime:
+The pattern used depends on how the date compares to the current instant:
 
 * pattern 1 if in the same day
 * pattern 2 if in the same year
 * pattern 3 otherwise
 
-For example::
+For example:
 {{{
-    {{ message.sent_at|compact_date:_("G:i,j b,j/n/y") }}
+    {{ message.sent_at|compact_date:_("g:i A,M j,n/j/y") }}
 }}}
 With a message sent on "5 dec 2010, 09:21:58":
 
 |=for the day: |=the output is:
-|5 dec 2010    |9:21
-|6 dec 2010    |5 dec
-|1 jan 2011    |5/12/10
+|5 dec 2010    |9:21 AM
+|6 dec 2010    |Dec 5
+|1 jan 2011    |12/5/10
 
 ----
 <-//[[Features|Previous]]// //[[Home]]// //[[Management Commands|Next]]//->
 == Custom views ==
 
+=== styles ===
+
+Here is a sample of some CSS rules, usable for {{{postman/views.html}}}:
+{{{
+    .pm_message.pm_deleted             { text-decoration: line-through; }
+    .pm_message.pm_deleted .pm_body    { display: none; }
+    .pm_message.pm_archived            { font-style: italic; color: grey; }
+    .pm_message.pm_unread .pm_subject  { font-weight: bolder; }
+    .pm_message.pm_pending .pm_header  { background-color: #FFC; }
+    .pm_message.pm_rejected .pm_header { background-color: #FDD; }
+}}}
 === forms ===
 
 You can replace the default forms in views.
 
 === after submission ===
 
-You can supersede the default view to return to after a successful submission.
+You can supersede the default view where to return to, after a successful submission.
 
 The default algorithm is:
 
 
 Example:
 {{{
-    <a href="{% url postman_reply message.id %}?next={{ next_url|urlencode }}">Reply</a>
+    <a href="{% url postman_reply reply_to_pk %}?next={{ next_url|urlencode }}">Reply</a>
 }}}
 
 === reply formatters ===