Omission in the documentation

In section 3.1.2. ‘Text’ of the documentation there is the following example(3. An Informal Introduction to Python — Python 3.12.7 documentation):

print("""\
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to
""")

it will give the following result:

Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

I think this example is incorrect because the ‘\’ character is missing at the end of the line on line 4.

print("""\
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to\
""")

The only difference would be an additional newline at the end of what’s printed out (since print() adds a newline). In the context it’s being used in, this wouldn’t make a difference.

Even if you use a newline, you will still have one empty line.

print("""\
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to
""", end='')

there will be the following conclusion:

Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

The example doesn’t say anything about the final newline, it explicitly notes that only the initial newline is not included in the output.

So the correct fix might be to just add a newline at the end of the output.

I don’t think it’s possible to add a trailing newline to a code block:

.. code-block:: text

   Usage: thingy [OPTIONS]
        -h                        Display this usage message
        -H hostname               Hostname to connect to

I don’t expect the docs to be exactly precise with regard to final newlines or blank lines. They will not stand out visually and most readers wouldn’t notice them if they were there or not. The doc page in question is fine as it is.

2 Likes

While this is true most of the time, this code is supposed to show of newline handling, and should therefore IMO be exact. If this is not possible, it should be removed entirely to prevent confusion.

3 Likes

One option is to put the example in the context of the REPL, like the example after it.

This shows exactly what a user would see in the REPL, which is hopefully clearer.

2 Likes

That’s what I mean. An empty line could be included in the example to show the reader exactly how a multiline quote works.

A pull request: Docs: make a tutorial example more precise by nedbat · Pull Request #125066 · python/cpython · GitHub

3 Likes