Author scoder
Recipients docs@python, eli.bendersky, jlaurens, ned.deily, rhettinger, scoder
Date 2015-04-30.07:04:39
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1430377480.79.0.373009887305.issue24079@psf.upfronthosting.co.za>
In-reply-to
Content
I agree that the wording in the documentation isn't great:

"""
text

    The text attribute can be used to hold additional data associated with the element. As the name implies this attribute is usually a string but may be any application-specific object. If the element is created from an XML file the attribute will contain any text found between the element tags.

tail

    The tail attribute can be used to hold additional data associated with the element. This attribute is usually a string but may be any application-specific object. If the element is created from an XML file the attribute will contain any text found after the element’s end tag and before the next tag.
"""

Special cases that no-one uses (sticking non-string objects into text/tail) are given too much space and the difference isn't explained as needed.

Since the distinction between text and tail is a (great but) rather special feature of ElementTree, it needs to be given more room in the docs.

Proposal:

"""
text

    The text attribute holds the immediate text content of the element. It contains any text found up to either the closing tag if the element has no children, or the next opening child tag within the element. For text following an element, see the `tail` attribute. To collect the entire text content of a subtree, see `tostring`. Applications may store arbitrary objects in this attribute.

tail

    The tail attribute holds any text that directly follows the element. For example, in a document like ``<a>Text<b/>BTail<c/>CTail</a>``, the `text` attribute of the ``a`` element holds the string "Text", and the tail attributes of ``b`` and ``c`` hold the strings "BTail" and "CTail" respectively. Applications may store arbitrary objects in this attribute.
"""
History
Date User Action Args
2015-04-30 07:04:40scodersetrecipients: + scoder, rhettinger, ned.deily, eli.bendersky, docs@python, jlaurens
2015-04-30 07:04:40scodersetmessageid: <1430377480.79.0.373009887305.issue24079@psf.upfronthosting.co.za>
2015-04-30 07:04:40scoderlinkissue24079 messages
2015-04-30 07:04:39scodercreate