Tidy dexterity-xml.md

Author: stevepiercy

plone.app.dexterity/reference/dexterity-xml.md

@@ -1,28 +1,29 @@
 ---
 myst:
   html_meta:
-    "description": ""
-    "property=og:description": ""
-    "property=og:title": ""
-    "keywords": ""
+    "description": "Reference for Dexterity's XML name spaces for content types in Plone"
+    "property=og:description": "Reference for Dexterity's XML name spaces for content types in Plone"
+    "property=og:title": "Reference for Dexterity's XML name spaces for content types in Plone"
+    "keywords": "Plone, reference, content types, Dexterity, XML, name spaces"
 ---
 
 # Dexterity XML
 
-**A reference for Dexterity's XML name spaces**
+This chapter serves as a reference for Dexterity's XML name spaces.
+
 
 ## Introduction
 
-The schema (structure) of a Dexterity content type may be detailed in two very different ways:
+The schema of a Dexterity content type may be detailed in two very different ways.
 
-> - In Python as a Zope schema; or,
-> - In XML
+-   In Python as a Zope schema
+-   In XML
 
-When you are using Dexterity's through-the-web schema editor, all your work is being saved in the content type's Factory Type Information (FTI) as XML.
-`plone.supermodel` dynamically translates that XML into Python objects which are used to display and edit your content objects.
+When you use Dexterity's through-the-web (TTW) schema editor, all your work is being saved in the content type's Factory Type Information (FTI) as XML.
+`plone.supermodel` dynamically translates that XML into Python objects, which are used to display and edit your content objects.
 
 The XML model of your content object may be exported from Dexterity and incorporated into a Python package.
-That's typically done with code like:
+That's typically done with code such as the following.
 
 ```python
 class IExampleType(form.Schema):
@@ -32,7 +33,7 @@ class IExampleType(form.Schema):
 
 or:
 
-```
+```python
 from plone.supermodel import xmlSchema
 
 IExampleType = xmlSchema("models/example_type.xml")
@@ -43,10 +44,11 @@ XML models in a package may be directly edited.
 This document is a reference to the tags and attributes you may use in model XML files.
 This includes several form-control and security-control attributes that are not available through the TTW schema editor.
 
-## XML Document Structure
+
+## XML document structure
 
 Dexterity requires that its model XML be well-formed XML, including name space declarations.
-The typical structure of a Dexterity XML document is:
+The typical structure of a Dexterity XML document is the following.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -63,12 +65,13 @@ The typical structure of a Dexterity XML document is:
 </model>
 ```
 
-Only the default name space (.../supermodel/schema) is required for basic schema.
+Only the default name space `supermodel/schema` is required for basic schema.
 The `supermodel/form` and `supermodel/schema` provide additional attributes to control form presentation and security.
 
-## supermodel/schema fields
 
-Most of the supermodel/schema field tag and its attributes map directly to what's available via the TTW schema editor:
+## `supermodel/schema` fields
+
+Most of the `supermodel/schema` field tag and its attributes map directly to what's available via the TTW schema editor:
 
 ```xml
 <field name="dummy" type="zope.schema.TextLine">
@@ -83,11 +86,12 @@ Most of the supermodel/schema field tag and its attributes map directly to what'
 </field>
 ```
 
-The field `type` needs to be the full dotted name (as if it was being imported in Python) of the field type.
+The field `type` needs to be the full dotted name of the field type, as if it were imported in Python.
+
 
 ### Fieldsets
 
-It's easy to add fieldsets by surrounding embedding fields tags in a `fieldset` block:
+To add fieldsets, surround embedded `field` tags in a `fieldset` block.
 
 ```xml
 <schema>
@@ -108,9 +112,10 @@ It's easy to add fieldsets by surrounding embedding fields tags in a `fieldset`
 </schema>
 ```
 
+
 ### Vocabularies
 
-Vocabularies may be specified via dotted names using the `source` tag:
+Vocabularies may be specified via dotted names using the `source` tag.
 
 ```xml
 <field name="dummy" type="zope.schema.Choice">
@@ -124,15 +129,15 @@ Vocabularies may be specified via dotted names using the `source` tag:
 </field>
 ```
 
-Where the full Python dotted-name of a Zope vocabulary in a package:
+Where the full Python dotted-name of a Zope vocabulary in a package.
 
-```
+```python
 from zope.schema.vocabulary import SimpleVocabulary
 
-dummy_vocabulary_instance = SimpleVocabulary.fromItems([(1, 'a'), (2, 'c')])
+dummy_vocabulary_instance = SimpleVocabulary.fromItems([(1, "a"), (2, "c")])
 ```
 
-Or, a source binder:
+Or, a source binder.
 
 ```xml
 <field name="dummy" type="zope.schema.Choice">
@@ -141,7 +146,7 @@ Or, a source binder:
 </field>
 ```
 
-With Python like:
+Or in Python.
 
 ```python
 from zope.schema.interfaces import IContextSourceBinder
@@ -150,20 +155,20 @@ class Binder(object):
     implements(IContextSourceBinder)
 
     def __call__(self, context):
-        return SimpleVocabulary.fromValues(['a', 'd', 'f'])
+        return SimpleVocabulary.fromValues(["a", "d", "f"])
 
 dummy_binder = Binder()
 ```
 
 You may also use the `vocabulary` tag rather than `source` to refer to named vocabularies registered via the ZCA.
 
+
 ### Internationalization
 
-Translation domains and message ids can be specified for text
-that is interpreted as unicode. This will result in deserialization
-as a zope.i18nmessageid message id rather than a basic Unicode string.
+Translation domains and message IDs can be specified for text that is interpreted as Unicode.
+This will result in deserialization as a `zope.i18nmessageid` message ID rather than a basic Unicode string.
 
-Note that we need to add the i18n namespace and a domain specification:
+Note that we need to add the `i18n` namespace and a domain specification.
 
 ```xml
 <model xmlns="http://namespaces.plone.org/supermodel/schema"
@@ -179,21 +184,20 @@ Note that we need to add the i18n namespace and a domain specification:
 </model>
 ```
 
-## supermodel/form attributes
 
-supermodel/form provides attributes that govern presentation and editing.
+## `supermodel/form` attributes
 
-### after/before
+`supermodel/form` provides attributes that govern presentation and editing.
 
-To re-order fields, use `form:after` or `form:before`.
 
-The value should be either `'*'`, to put the field first/last in the form,
-or the name of a another field. Use `'.fieldname'` to refer to field in the
-current schema (or a base schema). Use a fully prefixed name (e.g.
-`'my.package.ISomeSchema'`) to refer to a field in another schema. Use an
-unprefixed name to refer to a field in the default schema for the form.
+### `after/before`
 
-Example:
+To reorder fields, use `form:after` or `form:before`.
+
+The value should be either `"*"`, to put the field first/last in the form, or the name of a another field.
+Use `".fieldname"` to refer to a field in the current schema or a base schema.
+Use a fully prefixed name (for example, `"my.package.ISomeSchema"`) to refer to a field in another schema.
+Use an unprefixed name to refer to a field in the default schema of the form.
 
 ```xml
 <field type="zope.schema.TextLine"
@@ -203,13 +207,11 @@ Example:
 </field>
 ```
 
-### mode
 
-To turn a field into a view mode or hidden field, use `form:mode`.  The
-mode may be set for only some forms by specifying a form interface in the
-same manner as for `form:omitted`.
+### `mode`
 
-Example:
+To turn a field into a view mode or hidden field, use `form:mode`.
+The mode may be set for only some forms by specifying a form interface in the same manner as for `form:omitted`.
 
 ```xml
 <field type="zope.schema.TextLine"
@@ -219,14 +221,12 @@ Example:
 </field>
 ```
 
-### omitted
 
-To omit a field from all forms, use `form:omitted="true"`.  To omit a field
-only from some forms, specify a form interface like
-`form:omitted="z3c.form.interfaces.IForm:true"`. Multiple interface:value
-settings may be specified, separated by spaces.
+### `omitted`
 
-Examples:
+To omit a field from all forms, use `form:omitted="true"`.
+To omit a field only from some forms, specify a form interface such as `form:omitted="z3c.form.interfaces.IForm:true"`.
+Multiple `interface:value` settings may be specified, separated by spaces.
 
 ```xml
 <field type="zope.schema.TextLine"
@@ -244,12 +244,10 @@ Examples:
 
 The latter example hides the field on everything except the edit form.
 
-### widget
 
-To set a custom widget for a field, use `form:widget` to give a fully
-qualified name to the field widget factory.
+### `widget`
 
-Example:
+To set a custom widget for a field, use `form:widget` to give a fully qualified name to the field widget factory.
 
 ```xml
 <field type="zope.schema.TextLine"
@@ -259,14 +257,11 @@ Example:
 </field>
 ```
 
-### Dynamic Defaults
 
-To set a dynamic default for a field, use a `defaultFactory` tag to
-give a fully qualified name for a callable. The defaultFactory callable must
-provide either plone.supermodel.interfaces.IDefaultFactory or
-zope.schema.interfaces.IContextAwareDefaultFactory.
+### Dynamic defaults
 
-Example:
+To set a dynamic default for a field, use a `defaultFactory` tag to give a fully qualified name for a callable.
+The defaultFactory callable must provide either `plone.supermodel.interfaces.IDefaultFactory` or `zope.schema.interfaces.IContextAwareDefaultFactory`.
 
 ```xml
 <field type="zope.schema.TextLine" name="three">
@@ -275,34 +270,31 @@ Example:
 </field>
 ```
 
-Sample Python for the validator factory:
+Sample Python for the validator factory.
 
 ```python
 @provider(IDefaultFactory)
 def dummy_defaultFactory():
-    return 'something'
+    return "something"
 ```
 
-For a callable using context:
+For a callable using context.
 
 ```python
 @provider(IContextAwareDefaultFactory)
 def dummy_defaultCAFactory(context):
     return context.something
 ```
 
-:::{note}
-The `defaultFactory` tag was added in plone.supermodel 1.2.3,
-shipping with Plone 4.3.2+.
-:::
+```{versionadded} 4.3.2
+The `defaultFactory` tag was added in `plone.supermodel` 1.2.3, shipping with Plone 4.3.2 and later.
+```
 
-### validator
 
-To set a custom validator for a field, use `form:validator` to give a fully
-qualified name to the field validator factory. The validator factory should be
-a class derived from one of the validators in z3c.form.validator.
+### `validator`
 
-Example:
+To set a custom validator for a field, use `form:validator` to give a fully qualified name to the field validator factory.
+The validator factory should be a class derived from one of the validators in `z3c.form.validator`.
 
 ```xml
 <field type="zope.schema.TextLine"
@@ -312,7 +304,7 @@ Example:
 </field>
 ```
 
-Sample Python for the validator factory:
+Sample Python for the validator factory.
 
 ```python
 class TestValidator(z3c.form.validator.SimpleFieldValidator):
@@ -322,17 +314,16 @@ class TestValidator(z3c.form.validator.SimpleFieldValidator):
         raise Invalid("Test")
 ```
 
+
 (dexterity-xml-security)=
 
-## supermodel/security attributes
+## `supermodel/security` attributes
 
-### read-permission/write-permission
 
-To set a read or write permission, use `security:read-permission` or
-`security:write-permission`. The value should be the name of an
-`IPermission` utility.
+### `read-permission` and `write-permission`
 
-Example:
+To set a read or write permission, use `security:read-permission` or `security:write-permission`.
+The value should be the name of an `IPermission` utility.
 
 ```xml
 <field type="zope.schema.TextLine"