[Checkins] SVN: zope3docs/ Cleanup.
Christian Theune
ct at gocept.com
Thu Feb 19 12:28:22 EST 2009
Log message for revision 96781:
Cleanup.
Changed:
_U zope3docs/
U zope3docs/source/codingstyle/zcml-style.rst
-=-
Property changes on: zope3docs
___________________________________________________________________
Modified: bzr:revision-info
- timestamp: 2009-02-19 11:50:21.924999952 +0100
committer: Christian Theune <ct at gocept.com>
properties:
branch-nick: zope3docs.bzr
+ timestamp: 2009-02-19 11:50:34.569000006 +0100
committer: Christian Theune <ct at gocept.com>
properties:
branch-nick: zope3docs.bzr
Modified: bzr:file-ids
- source/codingstyle/python-style.rst 96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Fpython-style.rst
+ source/codingstyle/zcml-style.rst 96696 at 62d5b8a3-27da-0310-9561-8e5933582275:zope3docs:source%2Fcodingstyle%2Fzcml-style.rst
Modified: bzr:revision-id:v3-single-zope3docs
- 16 ct at gocept.com-20090219095131-k60befy2nrfx9q99
17 ct at gocept.com-20090219101837-g1g0cg0op0o8a104
18 ct at gocept.com-20090219104745-nh3531xbm8hsd2v9
19 ct at gocept.com-20090219105006-0mre3cx94v8awk9m
20 ct at gocept.com-20090219105021-qywg1ei5q6a21223
+ 16 ct at gocept.com-20090219095131-k60befy2nrfx9q99
17 ct at gocept.com-20090219101837-g1g0cg0op0o8a104
18 ct at gocept.com-20090219104745-nh3531xbm8hsd2v9
19 ct at gocept.com-20090219105006-0mre3cx94v8awk9m
20 ct at gocept.com-20090219105021-qywg1ei5q6a21223
21 ct at gocept.com-20090219105034-je5udw7hy1r7xel5
Modified: zope3docs/source/codingstyle/zcml-style.rst
===================================================================
--- zope3docs/source/codingstyle/zcml-style.rst 2009-02-19 17:28:15 UTC (rev 96780)
+++ zope3docs/source/codingstyle/zcml-style.rst 2009-02-19 17:28:22 UTC (rev 96781)
@@ -1,165 +1,210 @@
-ZCML style conventions
-======================
+ZCML
+====
-ZCML file naming conventions
+File naming conventions
+-----------------------
- zcml configuration for a package should, in general, be placed in a
- file named 'configure.zcml'. If a package performs meta
- configuration (defines new configuration directives), the
- metaconfiguration should go in a file named meta.zcml. The code
- that implements the metaconfiguration directives should (again, in
- general) go in a file named metaconfiguration.py.
+ZCML configuration for a package should, in general, be placed in a file
+named ``configure.zcml``. If a package performs meta configuration
+(defines new configuration directives), the meta configuration should go
+in a file named ``meta.zcml``. The code that implements the meta
+configuration directives should (again, in general) go in a file named
+``metaconfiguration.py``.
-ZCML file placement conventions
+File placement conventions
+--------------------------
- Anything outside of zope.app needs to be usable outside of the
- application server. This means it should have no dependencies on
- zope.app. In addition, anything outside of zope.app should have
- mimimal dependencies on other zope packages.
+Anything outside of zope.app needs to be usable outside of the
+application server. This means it should have no dependencies on
+zope.app. In addition, anything outside of zope.app should have mimimal
+dependencies on other zope packages.
- Therefore, there should be no zcml in packages outside of zope.app and
- zope.configure.
+Therefore, there should be no ZCML in packages outside of zope.app and
+zope.configure.
-ZCML style guide
+Style guide
+-----------
- Status: first draft
+The ZCML style guide has been developed with the following qualities in
+mind:
- Contact: "Steve Alexander":mailto:steve at cat-box.net
+* Lines under 80 characters wherever possible
-Problem
+* Indentation to reflect nesting
- ZCML in Zope 3 will be easier to maintain if it all follows the same
- style.
-
- In this page, I propose such a style. I've considered the following
- qualities:
-
- * Lines under 80 characters wherever possible
-
- * Indentation to reflect nesting
-
- * Ease of maintenance
-
- * Easy visual scanning through zcml
-
-Proposal
+* Ease of maintenance
- Tabs and spaces
-
- * All whitespace to be made up of space characters. No chr(9) hard tabs.
-
- * Indentation of 2 characters to show nesting, 4 characters to list
- attributes on separate lines. This distinction makes it easier to
- see the difference between attributes and nested elements.
-
- * Skip the first indentation level. That is, don't indent the
- tags that are immediately inside the 'configure' element.
+* Easy visual scanning through ZCML
- If a configuration file has many logical sections, then mark
- the sections with comments and indent the sections relative to
- the comments. For example::
- <configure xmlns='http://namespaces.zope.org/zope'>
+Tabs and spaces
+~~~~~~~~~~~~~~~
- <!-- Configuration registries -->
+All whitespace to be made up of space characters. No chr(9) hard tabs.
- <content
- class="zope.app.services.configuration.ConfigurationRegistry"
- >
- <require
- permission="zope.ManageServices"
- interface="zope.app.interfaces.services.configuration.IConfigurationRegistry"
- />
- </content>
+Indentation of 2 characters to show nesting, 4 characters to list
+attributes on separate lines. This distinction makes it easier to see
+the difference between attributes and nested elements.
- <!-- Adapter Service -->
- <content class="zope.app.services.adapter.AdapterService">
- <implements
+Logical sections
+~~~~~~~~~~~~~~~~
+If a configuration file has many logical sections, then mark the
+sections with comments and indent the sections relative to the comments.
+For example::
-
- Namespaces
-
- * Always use the "usual" names for namespaces in the document
-
- * default (no qualification needed) for http://namespaces.zope.org/zope
-
- * browser for http://namespaces.zope.org/browser
-
- * zmi for http://namespaces.zope.org/zmi
-
- * security for http://namespaces.zope.org/security
+ <configure xmlns='http://namespaces.zope.org/zope'>
- * xmlrpc for http://namespaces.zope.org/xmlrpc
-
- * whatevername for http://namespaces.zope.org/whatevername
-
- * Only define those namespaces used in the document. This is a similar
- rule to what imports to use in a Python module.
-
- Tags
-
- * Opening tags
-
- * Close a one-line tag on the same line
+ <!-- Configuration registries -->
- * Close a multi-line tag on a new line, at the same level of
- indentation as the tags attributes.
-
- * Empty tags
-
- * Close a one-line tag on the same line
-
- * Close a multi-line tag using " />" on a new line at the
- same level of indentation as the tag's attributes,
-
- * Elements
-
- * Indent closing tags at the same level of indentation as the
- opening tags.
-
- * Attributes
-
- * If all the attributes fit on one line with the tag name, do that
-
- * If all the attribute fit on one line without the tag name, do
- that on the line after the tag, indented 4 spaces along from
- the tag.
-
- * Otherwise, put the first attribute on a new line, and use one
- line per attribute.
+ <content
+ class="zope.app.services.configuration.ConfigurationRegistry"
+ >
+ <require
+ permission="zope.ManageServices"
+ interface="zope.app.interfaces.services.configuration.IConfigurationRegistry"
+ />
+ </content>
- * Use double quotes for attributes unless single quotes are
- needed to enclose double quotes.
-
- * Comments
-
- * Comments should be placed immediately above the declarations they
- apply to. Keep comments to one line where possible, and open and
- close the comment on the same line.
-
- * using XXX in comments to mark the unfinished, broken or crufty
-
-Examples
+ <!-- Adapter Service -->
- Example one, good style::
-
- <configure
- xmlns='http://namespaces.zope.org/zope'
+ <content class="zope.app.services.adapter.AdapterService">
+ <implements
+
+ ...
+
+
+Namespaces
+~~~~~~~~~~
+
+Always use the "usual" names for namespaces in the document:
+
+default (no qualification needed)
+ for http://namespaces.zope.org/zope
+
+browser
+ for http://namespaces.zope.org/browser
+
+zmi
+ for http://namespaces.zope.org/zmi
+
+security
+ for http://namespaces.zope.org/security
+
+xmlrpc
+ for http://namespaces.zope.org/xmlrpc
+
+whatevername
+ for http://namespaces.zope.org/whatevername
+
+Only define those namespaces used in the document. This is a similar
+rule to what imports to use in a Python module.
+
+
+Opening tags
+~~~~~~~~~~~~
+
+Close a one-line tag on the same line::
+
+ <class class="Foo">
+
+Close a multi-line tag on a new line, at the same level of indentation
+as the tags attributes::
+
+ <browser:pages
+ name="index.html"
+ class=".index.Index"
>
- <adapter
- factory=".AttributeAnnotations."
- provides=".IAnnotations."
- for=".IAttributeAnnotatable."
+
+Empty tags
+~~~~~~~~~~
+
+Close a one-line tag on the same line, insert a space after the last
+attribute:::
+
+ <subscriber handler=".foo.OnFoo" />
+
+Close a multi-line tag on a new line at the same level of indentation as
+the tag's attributes::
+
+ <browser:page
+ name="index.html"
+ class=".index.Index"
/>
+
+Closing tags
+~~~~~~~~~~~~
+
+Indent closing tags at the same level of indentation as the opening
+tags::
+
+ <class class=".foo.Foo">
+ ...
+ </class>
+
+Attributes
+~~~~~~~~~~
+
+If all the attributes fit on one line with the tag name, do that::
+
+ <class class=".foo.Foo">
+
+If all the attribute fit on one line without the tag name, do that on
+the line after the tag, indented 4 spaces along from the tag::
+
+ <browser:page
+ name="index.html" class=".foo.Foo" permission="zope.View"
+ />
+
+Otherwise, put the first attribute on a new line, and use one line per
+attribute::
+
+ <browser:page
+ name="index.html"
+ class=".foo.Foo"
+ permission="zope.View"
+ template="foo.pt"
+ />
+
+Use double quotes for attributes unless single quotes are needed to
+enclose double quotes.
+
+
+Comments
+~~~~~~~~
+
+Comments should be placed immediately above the declarations they apply
+to. Keep comments to one line where possible, and open and close the
+comment on the same line.
+
+The rules for adding TODO comments apply.
+
+.. note::
+ TODO Insert sphinx reference to the TODO comment document.
+
+
+Comprehensive examples
+~~~~~~~~~~~~~~~~~~~~~~
+
+Example one, good style::
+
+ <configure
+ xmlns="http://namespaces.zope.org/zope"
+ >
+
+ <adapter
+ factory=".AttributeAnnotations."
+ provides=".IAnnotations."
+ for=".IAttributeAnnotatable."
+ />
+
</configure>
+Example two, could be better::
- Example two, could be better::
-
<configure
xmlns='http://namespaces.zope.org/zope'
xmlns:security='http://namespaces.zope.org/security'
@@ -217,65 +262,65 @@
</configure>
- This example could be rewritten taking into account
-
- * Only defining the namespaces that are used
-
- * Better formatting of security permission declarations
-
- * Using 2 space and 4 space indents, not 3 space.
-
- Example two rewritten::
-
+The second example could be rewritten taking into account:
+
+* Only defining the namespaces that are used
+
+* Better formatting of security permission declarations
+
+* Using 2 space and 4 space indents, not 3 space.
+
+Example two, rewritten::
+
<configure
- xmlns='http://namespaces.zope.org/zope'
- xmlns:security='http://namespaces.zope.org/security'
+ xmlns="http://namespaces.zope.org/zope"
+ xmlns:security="http://namespaces.zope.org/security"
>
- <!-- Standard configuration directives -->
- <include package=".Configuration" file="configuration-meta.zcml" />
- <include package=".App" file="app-meta.zcml" />
- <include package=".I18n" file="i18n-meta.zcml" />
- <include package=".Publisher" file="publisher-meta.zcml" />
- <include package=".Event" file="event-meta.zcml" />
- <include package=".StartUp" file="startup-meta.zcml" />
+ <!-- Standard configuration directives -->
+ <include package=".Configuration" file="configuration-meta.zcml" />
+ <include package=".App" file="app-meta.zcml" />
+ <include package=".I18n" file="i18n-meta.zcml" />
+ <include package=".Publisher" file="publisher-meta.zcml" />
+ <include package=".Event" file="event-meta.zcml" />
+ <include package=".StartUp" file="startup-meta.zcml" />
- <!-- Standard Permissions -->
- <security:permission id="zope.View" title="View" />
- <security:permission id="zope.Security" title="Change security settings" />
- <security:permission id="zope.ManageContent" title="Manage Content" />
- <security:permission
- id="zope.ManageBindings" title="Manage Service Bindings"
- />
- <security:permission id="zope.ManageServices" title="Manage Services" />
- <security:permission
- id="zope.ManageApplication" title="Manage Application"
- />
+ <!-- Standard Permissions -->
+ <security:permission id="zope.View" title="View" />
+ <security:permission id="zope.Security" title="Change security settings" />
+ <security:permission id="zope.ManageContent" title="Manage Content" />
+ <security:permission
+ id="zope.ManageBindings" title="Manage Service Bindings"
+ />
+ <security:permission id="zope.ManageServices" title="Manage Services" />
+ <security:permission
+ id="zope.ManageApplication" title="Manage Application"
+ />
- <!-- XXX What is this for? -->
- <security:permission
- id="zope.I18n" title="Manage Application"
- />
+ <!-- XXX What is this for? -->
+ <security:permission
+ id="zope.I18n" title="Manage Application"
+ />
- <!-- Configuration -->
- <include package=".App" file="app.zcml" />
- <include package=".I18n" file="i18n.zcml" />
- <include package=".Publisher" file="publisher.zcml" />
- <include package=".Event" file="event.zcml" />
- <include package=".StartUp" file="startup-registry.zcml" />
+ <!-- Configuration -->
+ <include package=".App" file="app.zcml" />
+ <include package=".I18n" file="i18n.zcml" />
+ <include package=".Publisher" file="publisher.zcml" />
+ <include package=".Event" file="event.zcml" />
+ <include package=".StartUp" file="startup-registry.zcml" />
</configure>
-
- Example three, could be better::
-
+
+Example three, could be better::
+
<configure
- xmlns='http://namespaces.zope.org/zope'
- xmlns:security='http://namespaces.zope.org/security'
- xmlns:zmi='http://namespaces.zope.org/zmi'
- xmlns:browser='http://namespaces.zope.org/browser'
+ xmlns="http://namespaces.zope.org/zope"
+ xmlns:security="http://namespaces.zope.org/security"
+ xmlns:zmi="http://namespaces.zope.org/zmi"
+ xmlns:browser="http://namespaces.zope.org/browser"
>
- <browser:defaultView
+ <browser:defaultView
for="zope.i18n.interfaces.ITranslationService."
name="index.html"
/>
@@ -315,118 +360,117 @@
</configure>
- Example three reformatted::
-
+Example three reformatted::
+
<configure
xmlns='http://namespaces.zope.org/zope'
xmlns:zmi='http://namespaces.zope.org/zmi'
xmlns:browser='http://namespaces.zope.org/browser'
>
- <browser:defaultView
- for="zope.i18n.interfaces.ITranslationService" name="index.html" />
+ <browser:defaultView
+ for="zope.i18n.interfaces.ITranslationService" name="index.html" />
- <browser:view
- permission="zope.ManageServices"
- for="zope.i18n.interfaces.ITranslationService"
- factory="zope.app.browser.i18n.Translate"
- >
+ <browser:view
+ permission="zope.ManageServices"
+ for="zope.i18n.interfaces.ITranslationService"
+ factory="zope.app.browser.i18n.Translate"
+ >
- <browser:page name="index.html" attribute="index" />
+ <browser:page name="index.html" attribute="index" />
- <browser:page name="editMessages.html" attribute="editMessages" />
+ <browser:page name="editMessages.html" attribute="editMessages" />
- <browser:page name="deleteMessages.html" attribute="deleteMessages" />
+ <browser:page name="deleteMessages.html" attribute="deleteMessages" />
- <browser:page name="addLanguage.html" attribute="addLanguage" />
- <browser:page name="addDomain.html" attribute="addDomain" />
+ <browser:page name="addLanguage.html" attribute="addLanguage" />
+ <browser:page name="addDomain.html" attribute="addDomain" />
- <browser:page
- name="changeEditLanguages.html" attribute="changeEditLanguages"
- />
- <browser:page
- name="changeEditDomains.html" attribute="changeEditDomains"
- />
- <browser:page
- name="changeFilter.html" attribute="changeFilter"
- />
+ <browser:page
+ name="changeEditLanguages.html" attribute="changeEditLanguages"
+ />
+ <browser:page
+ name="changeEditDomains.html" attribute="changeEditDomains"
+ />
+ <browser:page
+ name="changeFilter.html" attribute="changeFilter"
+ />
- <browser:page name="deleteLanguages.html" attribute="deleteLanguages" />
- <browser:page name="deleteDomains.html" attribute="deleteDomains" />
+ <browser:page name="deleteLanguages.html" attribute="deleteLanguages" />
+ <browser:page name="deleteDomains.html" attribute="deleteDomains" />
- </browser:view>
+ </browser:view>
- <zmi:tabs for="zope.i18n.interfaces.ITranslationService">
- <zmi:tab label="Translate" action="@@index.html"/>
- </zmi:tabs>
+ <zmi:tabs for="zope.i18n.interfaces.ITranslationService">
+ <zmi:tab label="Translate" action="@@index.html"/>
+ </zmi:tabs>
</configure>
- Example three reformatted again. Note how putting the attributes of
- 'browser:page' declarations on a separate line visually separates
- them, so we don't need so much vertical whitespace::
-
+Example three reformatted again. Note how putting the attributes of
+``browser:page`` declarations on a separate line visually separates them,
+so we don't need so much vertical whitespace::
+
<configure
xmlns='http://namespaces.zope.org/zope'
xmlns:zmi='http://namespaces.zope.org/zmi'
xmlns:browser='http://namespaces.zope.org/browser'
>
- <browser:defaultView
- for="zope.i18n.interfaces.ITranslationService" name="index.html" />
+ <browser:defaultView
+ for="zope.i18n.interfaces.ITranslationService" name="index.html" />
- <browser:view
- permission="zope.ManageServices"
- for="zope.i18n.interfaces.ITranslationService"
- factory="Zope.I18n.Views.Browser.Translate."
- >
-
- <browser:page
- name="index.html"
- attribute="index"
- />
- <browser:page
- name="editMessages.html"
- attribute="editMessages"
- />
- <browser:page
- name="deleteMessages.html"
- attribute="deleteMessages"
- />
- <browser:page
- name="addLanguage.html"
- attribute="addLanguage"
- />
- <browser:page
- name="addDomain.html"
- attribute="addDomain"
- />
- <browser:page
- name="changeEditLanguages.html"
- attribute="changeEditLanguages"
- />
- <browser:page
- name="changeEditDomains.html"
- attribute="changeEditDomains"
- />
- <browser:page
- name="changeFilter.html"
- attribute="changeFilter"
- />
- <browser:page
- name="deleteLanguages.html"
- attribute="deleteLanguages"
- />
- <browser:page
- name="deleteDomains.html"
- attribute="deleteDomains"
- />
-
- </browser:view>
+ <browser:view
+ permission="zope.ManageServices"
+ for="zope.i18n.interfaces.ITranslationService"
+ factory="Zope.I18n.Views.Browser.Translate."
+ >
- <zmi:tabs for="zope.i18n.interfaces.ITranslationService">
- <zmi:tab label="Translate" action="@@index.html"/>
- </zmi:tabs>
+ <browser:page
+ name="index.html"
+ attribute="index"
+ />
+ <browser:page
+ name="editMessages.html"
+ attribute="editMessages"
+ />
+ <browser:page
+ name="deleteMessages.html"
+ attribute="deleteMessages"
+ />
+ <browser:page
+ name="addLanguage.html"
+ attribute="addLanguage"
+ />
+ <browser:page
+ name="addDomain.html"
+ attribute="addDomain"
+ />
+ <browser:page
+ name="changeEditLanguages.html"
+ attribute="changeEditLanguages"
+ />
+ <browser:page
+ name="changeEditDomains.html"
+ attribute="changeEditDomains"
+ />
+ <browser:page
+ name="changeFilter.html"
+ attribute="changeFilter"
+ />
+ <browser:page
+ name="deleteLanguages.html"
+ attribute="deleteLanguages"
+ />
+ <browser:page
+ name="deleteDomains.html"
+ attribute="deleteDomains"
+ />
+ </browser:view>
+
+ <zmi:tabs for="zope.i18n.interfaces.ITranslationService">
+ <zmi:tab label="Translate" action="@@index.html"/>
+ </zmi:tabs>
+
</configure>
-
More information about the Checkins
mailing list