classification
Title: Fix incomplete line on optparse documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.10
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eamanu, lukasz.langa, miss-islington, taleinat, terry.reedy
Priority: normal Keywords: patch

Created on 2020-09-25 02:16 by eamanu, last changed 2020-10-05 16:10 by lukasz.langa. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 22407 merged eamanu, 2020-09-25 02:17
PR 22425 merged miss-islington, 2020-09-27 03:43
PR 22426 merged miss-islington, 2020-09-27 03:44
Messages (10)
msg377474 - (view) Author: Emmanuel Arias (eamanu) * Date: 2020-09-25 02:16
This line seems to be incomplete. This fix come from the translation
to spanish of @fjsevilla-dev on https://github.com/python/python-docs-es/pull/758/file.
reading the proposal for the translate has sense add `the next lines`.
msg377512 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-09-25 23:43
I can see how the current phrasing gives one pause, and might seem incomplete, but it is not incorrect.  The sense of

Additionally, users can run one of  ::
   <yourscript> -h
   <yourscript> --help
and optparse will ...

is "Additionally, users can run one of ``<yourscript> -h`` or ``<yourscript> --help`` and optparse will ...".  I personally prefer this running text form with in-line code markup to the block form.  What do you think?

If we keep the block form, I slightly prefer 'one of the following' to 'one of the next lines' but cannot say why.
msg377525 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2020-09-26 12:08
I agree with Terry that the current form is not incorrect, as well as with his suggestion to inline the commands for printing the usage info.
msg377550 - (view) Author: Emmanuel Arias (eamanu) * Date: 2020-09-27 00:12
Hi Terry and Tal Einat,

I can't say too much because I am not English native, and my English is very basic.

When I read the docs and the translation from python-docs-es, that sentence make me feel how if something is missing, but I understand the intention with the Terry explanation.

I will change the patch for 

``Additionally, users can run one of the following ::``

What about now?
msg377553 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-09-27 03:43
New changeset 00eb063b6600fdb4ba5cfb99da83cc1660ec69bf by Emmanuel Arias in branch 'master':
bpo-41858: Clarify line in optparse doc (GH-22407)
https://github.com/python/cpython/commit/00eb063b6600fdb4ba5cfb99da83cc1660ec69bf
msg377554 - (view) Author: miss-islington (miss-islington) Date: 2020-09-27 03:52
New changeset e0e614ca99c39e107b97c7be779efea08f22ace3 by Miss Islington (bot) in branch '3.8':
bpo-41858: Clarify line in optparse doc (GH-22407)
https://github.com/python/cpython/commit/e0e614ca99c39e107b97c7be779efea08f22ace3
msg377556 - (view) Author: miss-islington (miss-islington) Date: 2020-09-27 04:04
New changeset 8b2595f68af059afdd61b2bb3d32a2bf4f1662c8 by Miss Islington (bot) in branch '3.9':
bpo-41858: Clarify line in optparse doc (GH-22407)
https://github.com/python/cpython/commit/8b2595f68af059afdd61b2bb3d32a2bf4f1662c8
msg377558 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2020-09-27 07:30
Thanks for the report and the PR, Emmanuel!
msg377564 - (view) Author: Emmanuel Arias (eamanu) * Date: 2020-09-27 13:17
Thanks for the help and review!
msg378045 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2020-10-05 16:10
New changeset a5750cf43466f5913cdeef774f7c2dcb5943d408 by Łukasz Langa (Miss Islington (bot)) in branch '3.9':
bpo-41858: Clarify line in optparse doc (GH-22407)
https://github.com/python/cpython/commit/a5750cf43466f5913cdeef774f7c2dcb5943d408
History
Date User Action Args
2020-10-05 16:10:19lukasz.langasetnosy: + lukasz.langa
messages: + msg378045
2020-09-27 13:17:23eamanusetmessages: + msg377564
2020-09-27 07:30:44taleinatsetstatus: open -> closed
resolution: fixed
messages: + msg377558

stage: patch review -> resolved
2020-09-27 04:04:00miss-islingtonsetmessages: + msg377556
2020-09-27 03:52:05miss-islingtonsetmessages: + msg377554
2020-09-27 03:44:01miss-islingtonsetpull_requests: + pull_request21460
2020-09-27 03:43:52miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request21459
2020-09-27 03:43:22terry.reedysetmessages: + msg377553
2020-09-27 00:12:10eamanusetmessages: + msg377550
2020-09-26 12:08:21taleinatsetnosy: + taleinat
messages: + msg377525
2020-09-25 23:43:20terry.reedysetnosy: + terry.reedy
messages: + msg377512
2020-09-25 02:17:47eamanusetkeywords: + patch
stage: patch review
pull_requests: + pull_request21447
2020-09-25 02:16:48eamanucreate