Style Guide

To do:

• fix up remaining conversion issues (mainly in “prose” sections)
• reorganize the overview sections (syntax, data model, execution model, etc)
• merge syntax and semantics material, where appropriate.
• add more cross-references/see-also stuff:
  • link between built-in functions and corresponding hooks (e.g. int, __int__)
  • link between type objects and type descriptions
• add reference pages for core types
• break up function descriptions (using more than one paragraph is perfectly okay ;-)

Style Issues:

• make the reference a bit more inviting to non-language-lawyers
  • use “inverted pyramid” style a bit more often (brief summary followed by description followed by minutiae)
  • replace grammar sections with human-readable notation.
  • provide a few examples here and there.
  • use more paragraphs. whitespace isn’t a disease.
  • clean up the vocabulary; no need to use formal words when non-formal words would work
  • use descriptive text when describing what things do, not prescriptive (i.e. use “gets the value” rather than “get the value”)
  • avoid hyperbole (“the possibilities are endless”), odd or overly formal language, and bland examples (“foobar”?). also see the Style section on this page.
• etc