[Tutor] Documentation concerns.

[Michael Janssen]

On Tue, 20 May 2003, Bob Gailer wrote:

> I've been noticing deficiencies in the official Python documentation.
> What's the procedure to request and/or contribute fixes and improvements?

a bugreport with category Documentation:
http://sourceforge.net/bugs/?group_id=3D5470

Best is to suggest new text.

Your examples was also the hard bits for me. I make some more comments:

>
> Examples: at http://www.python.org/dev/doc/devel/lib/string-methods.html
> 1-decode and encode have an encoding parameter. It is not explained.

Possibly add something that explains where to find valid encodings.
string-methods is possibly not the right place to explain what an encoding
is, but I feel like that the Library Reference should mentioned/explain
it.

> 2-expandtabs "tab characters are expanded" expanded is not defined. It
> takes an experiment to find out what this means.

It is already explained:
"Return a copy of the string where all tab characters are expanded using
spaces". "Expand" means "replace one with many". I believe this is clear.

> 3-translate "mapped through the given translation table" Huh?

a translation table is pretty wired. Best to explain with: "As returned by
string.maketrans()":

>>> print string.maketrans("ACEGIK","______")



??!"#$%&'()*+,-./0123456789:;<=3D>?@_B_D_F_H_J_LMNOPQRSTUVWXYZ[\]^_`
abcdefghijklmnopqrstuvwxyz{|}~=A1=A2=A3=A4=A5=A6=A7=A8=A9=AA=AB=AC=AD=AE=AF=
=B0=B1=B2=B3=B4=B5=B6=B7=B8=B9=BA=BB=BC=BD=BE=BF=C0=C1=C2=C3=C4
=C5=C6=C7=C8=C9=CA=CB=CC=CD=CE=CF=D0=D1=D2=D3=D4=D5=D6=D7=D8=D9=DA=DB=DC=DD=
=DE=DF=E0=E1=E2=E3=E4=E5=E6=E7=E8=E9=EA=EB=EC=ED=EE=EF=F0=F1=F2=F3=F4=F5=F6=
=F7=F8=F9=FA=FB=FC=FD=FE=FF

---> please note the "_B_D_F_H_J_L" part. Target of the whole activity is
to replace more than one char in one step:

'123456789'.replace('1','2').replace('2','3').replace('3','4') #and so on

is ugly, inefficient and possibly results not as wanted ;-). Better:

tr_tbl =3D string.maketrans('123456789','234567890')
'123456789'.translate(tr_tbl)

Back to your point: "translation table, which must be a string of length
256" isn't enough for an explanation. But what else?

Should those topics better covered in the/ in a Tutorial?

Michael

>
> Bob Gailer
> bgailer@alum.rpi.edu
> 303 442 2625
>
>
> _______________________________________________
> Tutor maillist  -  Tutor@python.org
> http://mail.python.org/mailman/listinfo/tutor
>