#15257: Suggestion: examples of double-underscore usage/meaning
-----------------------------------------+----------------------------------
Reporter: MixedContent | Owner: nobody
Status: new | Milestone:
Component: Documentation | Version: 1.2
Resolution: | Keywords: syntax examples
Triage Stage: Accepted | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 |
-----------------------------------------+----------------------------------
Changes (by gabrielhurley):
* needs_docs: 1 => 0
Old description:
> On this page:
>
> http://docs.djangoproject.com/en/1.2/intro/tutorial01
>
> this text appears:
>
> ====
>
> # The API automatically follows relationships as far as you need.
> # Use double underscores to separate relationships.
> # This works as many levels deep as you want; there's no limit.
> # Find all Choices for any poll whose pub_date is in 2007.
>
> ====
>
> The use of double-underscore as a syntactic element is not familiar to
> me. I accept without objection that it *is* used in this context, but it
> is unfamiliar. Since the audience for this tutorial *probably* includes
> at least *some* people as ignorant as I am, maybe a separate page for
> some examples of how the double-underscore syntax relates to particular
> object references would be helpful. (E.g., "See examples _here_",
> linking to a page with examples, "this__that__the-other" ==> "this.that
> .the-other" etc.)
>
> Since I explicitly lack experience here, my recommendation could be
> completely wrong; I leave that to you.
New description:
On this page:
http://docs.djangoproject.com/en/1.2/intro/tutorial01
this text appears:
{{{
# The API automatically follows relationships as far as you need.
# Use double underscores to separate relationships.
# This works as many levels deep as you want; there's no limit.
# Find all Choices for any poll whose pub_date is in 2007.
}}}
The use of double-underscore as a syntactic element is not familiar to me.
I accept without objection that it *is* used in this context, but it is
unfamiliar. Since the audience for this tutorial *probably* includes at
least *some* people as ignorant as I am, maybe a separate page for some
examples of how the double-underscore syntax relates to particular object
references would be helpful. (E.g., "See examples _here_", linking to a
page with examples, `"this__that__the-other" ==> "this.that.the-other"`
etc.)
Since I explicitly lack experience here, my recommendation could be
completely wrong; I leave that to you.
--
Comment:
I suppose Paul's suggestion is as good a solution as any. That snippet he
links to at least gives a general introduction to "this is the way it is",
which is better than nothing. The reality, though, is that the double
underscore is a relatively arbitrary delimiter, and is used by convention
(not just in Django). I am not aware of any good links on '''why''' it's
used as such.
I'll accept a patch as per Paul's comment, though.
--
Ticket URL: <http://code.djangoproject.com/ticket/15257#comment:2>
Django <http://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
