Changeset 2997 in products

Timestamp:

Nov 11, 2010 1:16:53 PM (13 years ago)

Author:

mylan

Message:

#228: reviewed explanation, correct grammar for filters doctest

File:

• quintagroup.plonegooglesitemaps/branches/blacklist/quintagroup/plonegooglesitemaps/filters.txt (modified) (21 diffs)

quintagroup.plonegooglesitemaps/branches/blacklist/quintagroup/plonegooglesitemaps/filters.txt

@@ -3 +3 @@
 ==================
 
-Sitemaps has option to filterout objects, which shouldn't present
-in a sitemap. This option is accessable in sitemap edit form
-and present as "Blackout entries" lines field.
-
-In earlier (<3.0.7 and <4.0.1) versions of the package the field
-filter-out objects only by its ids, and looks like:
+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".
+
+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:
 
 <pre>
@@ -15 +20 @@
 </pre>
 
-So all objects with "index.html" or "index_html" ids excluded
-from the sitemap.
-
-In the new versions of GoogleSitemaps filtering was remaked
-to pluggable architecture. Now filters are named mutli adapters.
-By default there are only two most useful filters - "id" and
+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".
 
-Because of different filters can be used - new syntax applied
+Since different filters can be used - new syntax was applied
 to the "Blackout entries" field. Every record in the field
-should follow the spec:
+should follow the specification:
   
   [<filter name>:]<filter arguments>
 
-By default (if no <filter name> specified) - "id" filter will
-be used. If <filter name> specified - system looking for 
-<filter name> name  multiadapter to IBlackoutFilter interface.
-If such multiadapter was not found - it's ignored silently.
-
-
-Setup 
-=====
-
-First, we must perform some setup. We use the testbrowser that is shipped
-with Five, as this provides proper Zope 2 integration. Most of the 
-documentation, though, is in the underlying zope.testbrower package.
+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
+===============================
+
+First, we must perform some setup. We use the testbrowser that is
+shipped with Five, as this provides proper Zope 2 integration. Most
+of the documentation, though, is in the underlying zope.testbrower
+package.
 
     >>> from Products.Five.testbrowser import Browser
@@ -46 +57 @@
     >>> 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.
+The following 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 = ()
 
-With that in place, we can go to the portal front page and log in. We will
-do this using the default user from PloneTestCase:
+With that in place, we can go to the portal front page and log in.
+We will do this using the default user from PloneTestCase:
 
     >>> from Products.PloneTestCase.setup import portal_owner, default_password
@@ -74 +85 @@
 
 
-
 Functionality
 =============
 
-First create several documents for demonstrations.
+First create some content for demonstrations.
 
 In the root of the portal
@@ -90 +100 @@
     >>> self.addDocument(self.folder, "doc2", "Member Document 2 text")
 
-We need add sitemap, of corse, for demonstration.
+We need to add sitemap for demonstration.
 
     >>> browser.open(portal_url + "/prefs_gsm_settings")
@@ -96 +106 @@
     
 Now we bring-up to edit form of the newly created content sitemap.
-We interested in two things: "Blackout entries" field must present
-in the form and it should be empty by default.
-    
-    
+We are interested in two things: "Blackout entries" field must
+present in the form and by default it should be empty.
+
     >>> file("/tmp/browser.0.html","wb").write(browser.contents)
     >>> blackout_list = browser.getControl("Blackout entries")
@@ -118 +127 @@
 
 
-After adding "Content Sitemap", "sitemap.xml" link will appear
-on "Settings" tab page of Plone Google Sitemap configlet.
+"sitemap.xml" link should appear in "Settings" page of the
+Plone Google Sitemap configlet when "Content Sitemap"
+was added.
 
     >>> browser.open(portal_url + "/prefs_gsm_settings")
@@ -125 +135 @@
     >>> smedit_url = smedit_link.url
 
-This link lead to edit form of the newly created sitemap.xml.
-Also prepare view link to simplifier following demonstrations.
+This link points to edit form of the newly created sitemap.xml.
+Let prepare view link to simplifier following demonstrations.
 
     >>> smedit_url.endswith("sitemap.xml/edit")
@@ -136 +146 @@
 ==========
 
-Resulted sitemap has no filters - all document should present in it.
+Created sitemap has no filters and all documents should appear in it.
 
     >>> browser.open(smview_url)
@@ -142 +152 @@
     >>> no_filters_content = browser.contents
 
-Check if resulted page is real sitemap...
+Check if resulted page really is sitemap...
 
     >>> print browser.contents
@@ -148 +158 @@
 
 
-To check urls, which pass filters - create regular expression...
+Create regular expression, which help us to test which urls pass the filters.
 
     >>> reloc = re.compile("<loc>%s([^\<]*)</loc>" % self.portal.absolute_url(), re.S)
 
-With help of reloc regular expression - check if all 4 documents + default
-front-page present in the sitemap without filters.
+Test if all 4 documents and default front-page present in the sitemap
+without filters.
 
     >>> no_filters_res = reloc.findall(no_filters_content)
@@ -181 +191 @@
     >>> id_filter_content = browser.contents
 
-As result - all "doc1" and "front-page" documents must be
-filtered-out from the sitemap.
+"doc1" and "front-page" documents should be excluded from the
+sitemap.
 
     >>> id_filter_res = reloc.findall(id_filter_content)
@@ -194 +204 @@
 ===================
 
-Suppouse we wont to filter-out doc2 of the test_user_1_'s (but 
-not from the portal root) and the front-page from the portal root.
+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.
 
     >>> browser.open(smedit_url)
@@ -206 +217 @@
     >>> path_filter_content = browser.contents
 
-As result - "doc2" of the pointed member and "front-page" documents
-must be filtered-out from the sitemap.
+"/Members/test_user_1_/doc2" and "/front_page" objects should
+be excluded from the sitemap.
 
     >>> path_filter_res = reloc.findall(path_filter_content)
     >>> path_filter_res.sort()
     >>> print "\n".join(path_filter_res)
-    /Members/test_user_1_/doc1
+    /Membe rs/test_user_1_/doc1
     /doc1
     /doc2
@@ -220 +231 @@
 ====================
 
-Lets check what filter should be used for old-feshion filters
-(without any filter name prefixes)?
-
-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 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.
 
     >>> browser.open(portal_url + "/sitemap.xml/edit")
@@ -236 +248 @@
     >>> default_filter_content = browser.contents
 
-By default "id" filter must be used, so all "doc1" and "front-page"
-objects must be filtered-out from the sitemap.
+"id" filter must be used as default filter. So all "doc1" and
+"front-page" objects should be excluded from the sitemap.
 
     >>> default_filter_res = reloc.findall(default_filter_content)
@@ -250 +262 @@
 
 Suppouse we want to create own blackout filter, 
-which behave like id-filter, but with some differencies.
+which behave like id-filter, but has some differencies.
 Our fitler has following format:
 
   (+|-)<filtered id>
 
-  - when 1st sign "+" then only objects with <filtered id>
-    must leave after filetering,
-  - if 1st sign is "-" or  all objects with <filtered id> must be
-    filtered-out (like default id filter)
+  - 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,
@@ -289 +302 @@
     ...                name=u'signedid')
 
-So thet's all what neede to add new filter.
-No test if newly added filter really take into consideration.
-
-Check if white filtering ("+" prefix) work correctly.
-Go to the edit form of the sitemap and add "signedid:+doc1"
+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"
 to the "Blackout entries" field.
 
@@ -304 +317 @@
     >>> signedid_filter_content = browser.contents
 
-As result - only objects with "doc1" id must present in the sitemap.
+Only objects with "doc1" id should be leaved in the sitemap.
 
     >>> signedid_filter_res = reloc.findall(signedid_filter_content)
@@ -313 +326 @@
 
 
-An for the last - check black filtering ("-" prefix) is working.
+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.
@@ -325 +339 @@
     >>> signedid_filter_content = browser.contents
 
-As result - all except objects with "doc1" id must present in the sitemap.
+All objects except those having "doc1" id must be included in
+the sitemap.
 
     >>> signedid_filter_res = reloc.findall(signedid_filter_content)