[New-bugs-announce] [issue14056] Misc doc changes for tarfile

[Éric Araujo]

New submission from Éric Araujo <merwok at netwok.org>:

A few things to improve in tarfile’s doc:

a) I found the heading “The following variables are available on module level” strange; does “variable” mean that users are able to edit tarfile.ENCODING to control the default encoding used?  The answer is no, as ENCODING is bound to a function default argument value and a class attribute at import time.  I suggest changing this heading for something like “Module-level constants”, and move it before the doc for the *_FORMATS constants (the attached diff makes it look like I moved these constants, but I actually moved ENCODING—same result).

b) The doc does not say that the availability of compression formats depends on the optional compilation of some modules.  Someone following the link to the module docs for gzip, bz2 or lzma can find the info, but I think a bit more explicitness wouldn’t hurt.  The attached patch for 3.2 tries to inline the info, but is a bit clumsy; alternatively, a table like this could be added near the top:

   Support depends on the availability of certain optional modules:

   ========= =========================================== =============
   Format    Description                                 Requires
   ========= =========================================== =============
   ``xz``    xz'ed tar file (:file:`.tar.xz`)            :mod:`lzma`
   ``bz2``   bzip2'ed tar file (:file:`.tar.bz2`)        :mod:`bz2`
   ``gz``    gzip'ed tar file (:file:`.tar.gz`)          :mod:`gzip`
   ========= =========================================== =============

c) The seealso section links to zipfile, just like the into text, but not to shutil.

Please let me know what suggestions you approve or reject and I’ll commit them.

----------
assignee: eric.araujo
components: Documentation
files: misc-tarfile-doc-changes-3.2.diff
keywords: patch
messages: 153733
nosy: eric.araujo, lars.gustaebel
priority: normal
severity: normal
stage: commit review
status: open
title: Misc doc changes for tarfile
versions: Python 2.7, Python 3.2, Python 3.3
Added file: http://bugs.python.org/file24571/misc-tarfile-doc-changes-3.2.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14056>
_______________________________________