[issue15439] Include Misc/ACKS names into the documentation
New submission from Chris Jerdonek <chris.jerdonek@gmail.com>: This issue is to include the names in Misc/ACKS into the documentation -- in place of the names from Doc/ACKS.txt. This was mentioned in the discussion for issue 15437, which is to add the names from Doc/ACKS.txt into Misc/ACKS. This issue should be done shortly after issue 15437. The current issue can include (1) converting Misc/ACKS into rst format, (2) deleting DOC/ACKS.txt (after confirming that any changes since issue 15437 are reflected in Misc/ACKS), and (3) resolving the intros in the two files with about.rst's surrounding text so that the text makes sense when included into the main documentation. Should Guido's note of acknowledgment in Misc/ACKS be included as is? And should a new "Python Acknowledgments" section be added to the docs, or is it okay for this more general acknowledgment to be included in the section called "About these documents"? If the former, the "About these documents" section could link to the more general "Python Acknowledgments" section to reference documentation contributors. ---------- assignee: docs@python components: Documentation keywords: easy messages: 166279 nosy: cjerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, jcea, pitrou priority: normal severity: normal stage: needs patch status: open title: Include Misc/ACKS names into the documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: ---------- dependencies: +Merge Doc/ACKS and Misc/ACKS _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Martin v. Löwis <martin@v.loewis.de> added the comment: -1. Misc/ACKS is fine where it is. No need to include it into the docs. ---------- nosy: +loewis _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Chris Jerdonek <chris.jerdonek@gmail.com> added the comment: Martin, just to be sure, this is to be done after issue 15437 (a dependency), and the location of Misc/ACKS will not change. Have you already read the discussion there? Éric said that he recalled it was Georg's preference to do this if Doc/ACKS.txt is removed. (I personally have no opinion.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Martin v. Löwis <martin@v.loewis.de> added the comment: Ok, please rephrase: what do you mean by "inlude ... into ..."? If the place of Misc/ACKS doesn't change, in what way is it being included into something? And which "documentation" is it being included into, if it doesn't change its location? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Serhiy Storchaka <storchaka@gmail.com> added the comment:
Ok, please rephrase: what do you mean by "inlude ... into ..."?
http://docs.python.org/about.html#contributors-to-the-python-documentation ---------- nosy: +storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Martin v. Löwis <martin@v.loewis.de> added the comment: I see; I'm changing my vote to -0 then. I don't think this list of names should have been included in the documentation in the first place. Since it is, providing the full list of contributors is just as fine. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Chris Jerdonek <chris.jerdonek@gmail.com> added the comment: The second sense of the word "include" is in the possible implementation. Éric pointed out in the other issue's thread that this can be achieved by modifying the existing include directive, for example-- --- a/Doc/about.rst +++ b/Doc/about.rst @@ -30,7 +30,7 @@ documentation, or Python itself. .. including the ACKS file here so that it can be maintained separately -.. include:: ACKS.txt +.. include:: ../Misc/ACKS The details of the surrounding text still need to be worked out though so that it reads right. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Martin v. Löwis <martin@v.loewis.de> added the comment: I think Guido's wording should be included literally in the online version. It very much explains what this list really is and how to interpret it. The post scriptum should be converted into a ReST comment, since it is primarily a note to maintainers. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I agree with Martin and don't think the ACKS list should be exposed further than it already is. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Chris Jerdonek <chris.jerdonek@gmail.com> added the comment: Is that a -0 then, Raymond? I think either the combined Misc/ACKS list should be included in the docs, or it should be removed entirely. If what Meador said is true (that people already in Misc/ACKS who contribute documentation should not be added)--
Doc/ACKS.txt is *only* for acknowledging documentation contributions. Serhiy is already in Misc/ACKS. No need to add him to Doc/ACKS.txt.
http://mail.python.org/pipermail/python-dev/2012-July/121093.html Then it's not clear to me why the current docs list is meaningful and what exactly it represents. At the least, the description of the list on the page doesn't match the stated practice. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Meador Inge <meadori@gmail.com> added the comment: What I meant by that was that Serhiy contributed a code change and was already in Misc/ACKS, therefore no ACKS file should have been updated. I didn't mean to imply that someone can't be in both files. My impression is that Misc/ACKS is for code contributions and Docs/ACKS.txt is for documentation contributions. ---------- nosy: +meador.inge _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Chris Jerdonek <chris.jerdonek@gmail.com> added the comment: Okay, thanks for clarifying. Then I have no strong opinion. However, if Doc/ACKS.txt is retained, then I think the Dev Guide should mention Doc/ACKS.txt just as it mentions Misc/ACKS: http://docs.python.org/devguide/patch.html#preparation And it should include instructions for when to update which files, and the patchcheck script should be suitably modified. With only ~230 names versus Misc/ACKS's ~1160 , I'm surprised that Doc/ACKS.txt does not have more names -- especially given that it's not uncommon for documentation changes to accompany code changes (or so one might think). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Martin v. Löwis <martin@v.loewis.de> added the comment: I don't know how Doc ACKS is maintained, but I think the devguide is fine as it stands, whether or not Doc ACKS is preserved or not. People should put themselves into Misc/ACKS if they made a contribution, period. If people need to be acknowledged separately for contributing to the documentation, I think only major contributions (such as writing the documentation for a yet-undocumented module) should be explicitly acknowledged. I think this all started from the documentation having initially Guido van Rossum given as its sole author, and then later Fred Drake. So Doc/ACKS.txt may have been an attempt to correct the impression that these two are the authors, but I think it went into the wrong direction (eventually leading to the creation of issues such as this one) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: FWIW including Misc/ACKS in the doc will probably break the generation of the pdf version of the doc, since it contains non-latin1 characters (see msg166408). I don't think it's necessary to include the names in the doc.
I don't know how Doc ACKS is maintained, but I think the devguide is fine as it stands, whether or not Doc ACKS is preserved or not. People should put themselves into Misc/ACKS if they made a contribution, period.
In my experience Doc/ACKS.txt is mostly ignored/unmaintained. I did a lot of work on the docs and my name is not in there, and I don't think I ever added anyone there.
If people need to be acknowledged separately for contributing to the documentation, I think only major contributions (such as writing the documentation for a yet-undocumented module) should be explicitly acknowledged.
It's already possible to give credit directly in the docs using directives like "sectionauthor". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Martin v. Löwis <martin@v.loewis.de> added the comment: OK, I propose to completely drop the Doc/ACKS.txt from the documentation, and replace it with the words "Many people have contributed to the Python language, the Python standard library, and the Python documentation. See Misc/ACKS in the Python source distribution for a partial list of contributors" ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment:
OK, I propose to completely drop the Doc/ACKS.txt from the documentation, and replace it with the words
Sounds good to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I agree with Martin also. A short paragraph and link to the (combined) online file is quite sufficient. There is no need for the file to be in offline copies. And I would make the change in all current versions. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Roundup Robot added the comment: New changeset 48185b0f7b8a by Ezio Melotti in branch '3.2': #15437, #15439: merge Doc/ACKS.txt with Misc/ACKS and modify Doc/about.rst accordingly. http://hg.python.org/cpython/rev/48185b0f7b8a New changeset 2b4a89f82485 by Ezio Melotti in branch 'default': #15437, #15439: merge with 3.2. http://hg.python.org/cpython/rev/2b4a89f82485 New changeset 76dd082d332e by Ezio Melotti in branch '2.7': #15437, #15439: merge Doc/ACKS.txt with Misc/ACKS and modify Doc/about.rst accordingly. http://hg.python.org/cpython/rev/76dd082d332e ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed type: -> enhancement versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________
participants (10)
-
Antoine Pitrou -
Chris Jerdonek
-
Ezio Melotti
-
Martin v. Löwis
-
Meador Inge
-
Raymond Hettinger
-
Roundup Robot
-
Serhiy Storchaka
-
Terry J. Reedy
-
Tshepang Lekhonkhobe