[Python-checkins] Doc: Update references and examples of old, unsupported OSes and uarches (GH-92791) (GH-93639)

Thu Jun 9 10:16:00 EDT 2022

https://github.com/python/cpython/commit/2139583bf9350289cf137848c123f538ae03c691
commit: 2139583bf9350289cf137848c123f538ae03c691
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2022-06-09T16:15:49+02:00
summary:

Doc: Update references and examples of old, unsupported OSes and uarches (GH-92791) (GH-93639)

(cherry picked from commit a5ba0f4ebca5020f6c77718a20663e0ac6e194ac)

Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>

files:
M Doc/c-api/init_config.rst
M Doc/faq/library.rst
M Doc/howto/sockets.rst
M Doc/library/mmap.rst
M Doc/library/platform.rst
M Doc/library/posix.rst
M Doc/library/struct.rst

diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 657d8e9caf1ea..2b6da2a7810bc 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -689,9 +689,8 @@ PyConfig
 
       * ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
       * ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces
-        the ASCII encoding (or Roman8 encoding on HP-UX), whereas the
-        ``mbstowcs()`` function decodes from a different encoding (usually
-        Latin1).
+        the ASCII encoding, whereas the ``mbstowcs()`` function
+        decodes from a different encoding (usually Latin1).
       * ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string.
       * Otherwise, use the :term:`locale encoding`:
         ``nl_langinfo(CODESET)`` result.
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index b9e541c150dc4..85b04c963f590 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -483,8 +483,14 @@ including :func:`~shutil.copyfile`, :func:`~shutil.copytree`, and
 How do I copy a file?
 ---------------------
 
-The :mod:`shutil` module contains a :func:`~shutil.copyfile` function.  Note
-that on MacOS 9 it doesn't copy the resource fork and Finder info.
+The :mod:`shutil` module contains a :func:`~shutil.copyfile` function.
+Note that on Windows NTFS volumes, it does not copy
+`alternate data streams
+<https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)>`_
+nor `resource forks <https://en.wikipedia.org/wiki/Resource_fork>`__
+on macOS HFS+ volumes, though both are now rarely used.
+It also doesn't copy file permissions and metadata, though using
+:func:`shutil.copy2` instead will preserve most (though not all) of it.
 
 
 How do I read (or write) binary data?
diff --git a/Doc/howto/sockets.rst b/Doc/howto/sockets.rst
index e58f78a7cb024..0bbf97da39768 100644
--- a/Doc/howto/sockets.rst
+++ b/Doc/howto/sockets.rst
@@ -252,20 +252,25 @@ Binary Data
 -----------
 
 It is perfectly possible to send binary data over a socket. The major problem is
-that not all machines use the same formats for binary data. For example, a
-Motorola chip will represent a 16 bit integer with the value 1 as the two hex
-bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00.
+that not all machines use the same formats for binary data. For example,
+`network byte order <https://en.wikipedia.org/wiki/Endianness#Networking>`_
+is big-endian, with the most significant byte first,
+so a 16 bit integer with the value ``1`` would be the two hex bytes ``00 01``.
+However, most common processors (x86/AMD64, ARM, RISC-V), are little-endian,
+with the least significant byte first - that same ``1`` would be ``01 00``.
+
 Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl,
 htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means
 *short* and "l" means *long*. Where network order is host order, these do
 nothing, but where the machine is byte-reversed, these swap the bytes around
 appropriately.
 
-In these days of 32 bit machines, the ascii representation of binary data is
+In these days of 64-bit machines, the ASCII representation of binary data is
 frequently smaller than the binary representation. That's because a surprising
-amount of the time, all those longs have the value 0, or maybe 1. The string "0"
-would be two bytes, while binary is four. Of course, this doesn't fit well with
-fixed-length messages. Decisions, decisions.
+amount of the time, most integers have the value 0, or maybe 1.
+The string ``"0"`` would be two bytes, while a full 64-bit integer would be 8.
+Of course, this doesn't fit well with fixed-length messages.
+Decisions, decisions.
 
 
 Disconnecting
diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index da174753361b2..79733ed7d2d07 100644
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -102,7 +102,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
 
    To ensure validity of the created memory mapping the file specified
    by the descriptor *fileno* is internally automatically synchronized
-   with physical backing store on macOS and OpenVMS.
+   with the physical backing store on macOS.
 
    This example shows a simple way of using :class:`~mmap.mmap`::
 
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 346063d66afab..dc2d871b47d5e 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -53,7 +53,7 @@ Cross Platform
 
 .. function:: machine()
 
-   Returns the machine type, e.g. ``'i386'``. An empty string is returned if the
+   Returns the machine type, e.g. ``'AMD64'``. An empty string is returned if the
    value cannot be determined.
 
 
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
index ad417a17879c1..90be191aa2f8d 100644
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -37,7 +37,7 @@ Large File Support
 
 .. sectionauthor:: Steve Clift <clift at mail.anacapa.net>
 
-Several operating systems (including AIX, HP-UX and Solaris) provide
+Several operating systems (including AIX and Solaris) provide
 support for files that are larger than 2 GiB from a C programming model where
 :c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished
 by defining the relevant size and offset types as 64-bit values. Such files are
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index eccba20fb8fe7..978eeabe37b1a 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -146,9 +146,10 @@ If the first character is not one of these, ``'@'`` is assumed.
 
 Native byte order is big-endian or little-endian, depending on the host
 system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
-Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
-switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
-endianness of your system.
+IBM z and most legacy architectures are big-endian;
+and ARM, RISC-V and IBM Power feature switchable endianness
+(bi-endian, though the former two are nearly always little-endian in practice).
+Use ``sys.byteorder`` to check the endianness of your system.
 
 Native size and alignment are determined using the C compiler's
 ``sizeof`` expression.  This is always combined with native byte order.

