Changeset 3005 in products for quintagroup.plonegooglesitemaps/trunk/quintagroup/plonegooglesitemaps/filters.txt

Timestamp:

Nov 12, 2010 1:07:34 PM (13 years ago)

Author:

olha

Message:

doc files updated

File:

• quintagroup.plonegooglesitemaps/trunk/quintagroup/plonegooglesitemaps/filters.txt (modified) (22 diffs)

quintagroup.plonegooglesitemaps/trunk/quintagroup/plonegooglesitemaps/filters.txt

@@ -3 +3 @@
 ==================
 
-Filtering introductioin
-=======================
-
-Sitemap portal type has an option, designed to filter out
-objects which should be excluded from a sitemap. This option is
-accessable in sitemap edit form and is labeled as
-"Blackout entries".
+Introduction
+============
+
+Sitemap portal type has an option that filters objects that
+should be excluded from a sitemap. This option is accessable
+on sitemap edit form and is labeled as "Blackout entries".
 
 In earlier versions of the package (<4.0.1 for plone-4 branch
 and <3.0.7 for plone-3 branch) this field allowed to
-filter objects only by their ids, and looked like:
+filter objects only by their ids, and it looked like:
 
 <pre>
@@ -20 +19 @@
 </pre>
 
-So, all objects with "index.html" or "index_html" ids were
-excluded from the sitemap.
-
-In the new versions of GoogleSitemaps filtering was remade
-to pluggable architecture. Now filters became named multi
-adapters. There are only two default filters - "id" and
-"path".
+As a result, all objects with "index.html" or "index_html" ids 
+were excluded from the sitemap.
+
+In the new versions of GoogleSitemaps filtering was refactored
+to pluggable architecture. Now filters turned to be named multi
+adapters. There are only two default filters: "id" and "path".
 
 Since different filters can be used - new syntax was applied
@@ -34 +32 @@
   [<filter name>:]<filter arguments>
 
-If no <filter name> is specified - "id" filter will
-be used. If <filter name> is specified - system will look
-for <filter name>-named  multiadapter to IBlackoutFilter
-interface. If such multiadapter is not found - filter
-will be ignored without raising any errors.
-
-
-Following parts demonstrate working of the filtering.
-Aspects of default filters ("id" and "path")
-are considered yet.
-
-Setup demonstration environment
+* If no <filter name> is specified - "id" filter will be used. 
+* If <filter name> is specified - system will look for 
+  <filter name>-named  multiadapter to IBlackoutFilter interface. 
+  If such multiadapter is not found - filter ill be ignored without
+  raising any errors.
+
+The following parts demonstrate how to work with filtering.
+Aspects of default filters ("id" and "path") will also be 
+considered.
+
+Demonstration environment setup
 ===============================
 
-First, we must perform some setup. We use the testbrowser that is
+First, we have to do some setup. We use testbrowser that is
 shipped with Five, as this provides proper Zope 2 integration. Most
 of the documentation, though, is in the underlying zope.testbrower
@@ -57 +54 @@
     >>> portal_url = self.portal.absolute_url()
 
-The following is useful when writing and debugging testbrowser tests.
-It lets us see all error messages in the error_log.
+This is useful when writing and debugging testbrowser tests. It lets
+us see all error messages in the error_log.
 
     >>> self.portal.error_log._ignored_exceptions = ()
@@ -88 +85 @@
 =============
 
-First create some content for demonstrations.
+First, create some content for demonstration purpose.
 
 In the root of the portal
@@ -105 +102 @@
     >>> browser.getControl('Add Content Sitemap').click()
     
-Now we bring-up to edit form of the newly created content sitemap.
-We are interested in two things: "Blackout entries" field must
-present in the form and by default it should be empty.
+Now we are landed on the newly-created sitemap edit form.
+What we are interested in is "Blackout entries" field on the edit 
+form, it should be empty by default settings.
 
     >>> file("/tmp/browser.0.html","wb").write(browser.contents)
@@ -121 +118 @@
 
 
-Click on "Save" button lead us to result sitemap view.
+Clicking on "Save" button will lead us to the sitemap view.
 
     >>> print browser.contents
@@ -127 +124 @@
 
 
-"sitemap.xml" link should appear in "Settings" page of the
-Plone Google Sitemap configlet when "Content Sitemap"
+"sitemap.xml" link should appear on "Settings" page of the
+Plone Google Sitemap configlet after "Content Sitemap"
 was added.
 
@@ -135 +132 @@
     >>> smedit_url = smedit_link.url
 
-This link points to edit form of the newly created sitemap.xml.
-Let prepare view link to simplifier following demonstrations.
+This link points to the newly-created sitemap.xml edit form.
+Let's prepare view link to simplify the following demonstrations.
 
     >>> smedit_url.endswith("sitemap.xml/edit")
@@ -146 +143 @@
 ==========
 
-Created sitemap has no filters and all documents should appear in it.
+The created sitemap has no filters applied and all documents should appear in it.
 
     >>> browser.open(smview_url)
@@ -152 +149 @@
     >>> no_filters_content = browser.contents
 
-Check if resulted page really is sitemap...
+Check if result page is really a sitemap...
 
     >>> print browser.contents
@@ -158 +155 @@
 
 
-Create regular expression, which help us to test which urls pass the filters.
+Create regular expression, which will help us to test which urls pass the filters.
 
     >>> reloc = re.compile("<loc>%s([^\<]*)</loc>" % self.portal.absolute_url(), re.S)
 
-Test if all 4 documents and default front-page present in the sitemap
-without filters.
+Test if all 4 documents and default front-page are in the sitemap without filters.
 
     >>> no_filters_res = reloc.findall(no_filters_content)
@@ -178 +174 @@
 =================
 
-Go to the edit form of the sitemap and add "doc1"
-and "front-page" lines with "id:" prefix to the
-"Blackout entries" field.
+Go to the sitemap edit form and add "doc1" and "front-page" lines with "id:" 
+prefix to the "Blackout entries" field.
 
     >>> browser.open(smedit_url)
@@ -191 +186 @@
     >>> id_filter_content = browser.contents
 
-"doc1" and "front-page" documents should be excluded from the
+"doc1" and "front-page" documents should now be excluded from the
 sitemap.
 
@@ -204 +199 @@
 ===================
 
-Suppouse we wont to exclude the "front_page" from portal root
-and "doc2" document, located in test_user_1_ home folder,
-but leave untouched "doc2" in portal root with all other objects.
+Suppose we want to exclude "front_page" from portal root and "doc2"
+document, located in test_user_1_ home folder, but leave "doc2" 
+untouched in portal root with all other objects.
 
     >>> browser.open(smedit_url)
@@ -231 +226 @@
 ====================
 
-Now I have the question: "What filter will be used when no 
-filter name prefix was specified (old-fashion filters for
-example)?"
-
-Go to the edit form of the sitemap and add "doc1" and
-"front-page" lines without any filter name prefix to the
-"Blackout entries" field.
+Now I have a question: "What filter will be used when no 
+filter name prefix is specified (e.g. old-fashion filters)?"
+
+Go to the sitemap edit form and add "doc1" and "front-page"
+lines without any filter name prefix to the "Blackout entries" 
+field.
 
     >>> browser.open(portal_url + "/sitemap.xml/edit")
@@ -248 +242 @@
     >>> default_filter_content = browser.contents
 
-"id" filter must be used as default filter. So all "doc1" and
+"id" filter must be used as default filter. So, all "doc1" and
 "front-page" objects should be excluded from the sitemap.
 
@@ -258 +252 @@
 
 
-Creation own filters
-====================
-
-Suppouse we want to create own blackout filter, 
-which behave like id-filter, but has some differencies.
-Our fitler has following format:
+Create your own filters
+=======================
+
+Suppose we want to create our own blackout filter,  which will
+behave like id-filter, but will have some differences. Our fitler 
+has the following format:
 
   (+|-)<filtered id>
 
-  - when 1st sign is "+" then only objects with <filtered id>
-    should be leaved in sitemap after filetering;
-  - if 1st sign is "-" then all objects with <filtered id>
-    should be excluded from the sitemap (like default id
-    filter).
-
-You need create new IBlckoutFilter multi-adapter,
-and register it with unique name.
+- if the 1st sign is "+" then only objects with <filtered id>
+  should be left in sitemap after filetering;
+- if the 1st sign is "-" then all objects with <filtered id>
+  should be excluded from the sitemap (like default id filter).
+
+You need to create new IBlckoutFilter multi-adapter, and register
+it with unique name.
 
     >>> from zope.component import adapts
@@ -302 +295 @@
     ...                name=u'signedid')
 
-So that's all what needed to add new filter.
-Now test newly created filter.
+So that's all what needed to add new filter. Now test newly-created
+filter.
 
 Check whether white filtering ("+" prefix) works correctly.
-Go to edit form of the sitemap and add "signedid:+doc1"
+Go to the sitemap edit form and add "signedid:+doc1"
 to the "Blackout entries" field.
 
@@ -317 +310 @@
     >>> signedid_filter_content = browser.contents
 
-Only objects with "doc1" id should be leaved in the sitemap.
+Only objects with "doc1" id should be left in the sitemap.
 
     >>> signedid_filter_res = reloc.findall(signedid_filter_content)
@@ -326 +319 @@
 
 
-And for the last - check wheter black filtering ("-" prefix)
-works correctly.
-Go to the edit form of the sitemap and add "signedid:-doc1"
-to the "Blackout entries" field.
+Finally, check whether black filtering ("-" prefix) works correctly.
+Go to the sitemaps edit form and add "signedid:-doc1" to the "Blackout 
+entries" field.
 
     >>> browser.open(smedit_url)
@@ -339 +331 @@
     >>> signedid_filter_content = browser.contents
 
-All objects except those having "doc1" id must be included in
+All objects, except those having "doc1" id, must be included in
 the sitemap.