classification
Title: Reference TOC: expand 'Atoms' and 'Primaries'
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, terry.reedy
Priority: normal Keywords:

Created on 2017-04-04 18:31 by terry.reedy, last changed 2017-04-04 18:45 by terry.reedy.

Messages (2)
msg291131 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-04-04 18:31
Today there is a fairly long python-list thread about the difficult of finding info on 'dict comprehensions' in the doc.  Point 1 is missing index entries.  I opened #29981 for this.  Point 2 is something I have also noticed: the obscurity of 'Atoms' and 'Primaries' as titles of sections in the Expressions chapter.  These are fairly esoteric Computer Science language theory terms.  Compare these to beginner-friendly 'Binary arithmetic operators' and 'Comparisons'.

My specific suggestions, subject to change:

Atoms, including identifiers, literals, displays, and comprehensions
Primaries: attributes, subscripts, slices, and calls
msg291133 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-04-04 18:45
'displays' is partly redundant with 'comprehensions'.  Since many think of other 'displays' as a type of literal, leave 'displays' out.  They are well indexed.  I think the most likely term people have trouble finding in the TOC is 'comprehension'.  It was not immediately obvious to most that should be 'atoms'.
History
Date User Action Args
2017-04-04 18:45:31terry.reedysetmessages: + msg291133
2017-04-04 18:31:12terry.reedycreate