[Doc-SIG] Reference guide, and images

A.M. Kuchling amk at amk.ca
Wed Apr 9 03:43:08 CEST 2008


1) The reference guide occasionally refers to past Python versions,
mentioning that a feature was introduced in such-and-such a version.  
For example, in lexical_analysis.rst:

. [#] In versions of Python prior to 2.4, octal and hexadecimal
   literals in the range just above the largest representable plain
   integer but below the largest unsigned 32-bit number (on a machine
   using 32-bit arithmetic), 4294967296, were taken as the negative
   plain integer obtained by subtracting 4294967296 from their
   unsigned value.

Should the reference guide include this past history, or just describe 
the version of Python it's shipped with?

2) With the shift to HTML and Sphinx, it's probably much easier to include 
images in the docs.  (I'm thinking of reviving the railroad syntax
diagrams.)  What image format would be best?  Bitmaps (PNG/JPG) or
vector (SVG)?

3) In the 'what's new', I have comments recording bug and patch
numbers, because it's useful information for me.  It strikes me
that this information might be interesting to include as part of
the published HTML.  Does that seem like a good idea?  I envision
something very brief; perhaps the text would read "Contributed by 
so-so; <patch #X>.  Can anyone suggest a better rendering?

--amk


More information about the Doc-SIG mailing list