| msg166279 - (view) |
Author: Chris Jerdonek (chris.jerdonek) *  |
Date: 2012-07-24 11:51 |
| 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. |
|
|
| msg166280 - (view) |
Author: Martin v. Löwis (loewis) * |
Date: 2012-07-24 11:58 |
| -1. Misc/ACKS is fine where it is. No need to include it into the docs. |
|
|
| msg166282 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-07-24 12:10 |
| 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.) |
|
|
| msg166320 - (view) |
Author: Martin v. Löwis (loewis) * |
Date: 2012-07-24 19:03 |
| 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? |
|
|
| msg166322 - (view) |
Author: Serhiy Storchaka (serhiy.storchaka) * |
Date: 2012-07-24 19:21 |
| > Ok, please rephrase: what do you mean by "inlude ... into ..."? http://docs.python.org/about.html#contributors-to-the-python-documentation |
|
|
| msg166325 - (view) |
Author: Martin v. Löwis (loewis) * |
Date: 2012-07-24 19:29 |
| 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. |
|
|
| msg166327 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-07-24 19:37 |
| 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. |
|
|
| msg166329 - (view) |
Author: Martin v. Löwis (loewis) * |
Date: 2012-07-24 19:57 |
| 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. |
|
|
| msg166341 - (view) |
Author: Raymond Hettinger (rhettinger) * |
Date: 2012-07-24 23:34 |
| I agree with Martin and don't think the ACKS list should be exposed further than it already is. |
|
|
| msg166344 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-07-25 00:18 |
| 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. |
|
|
| msg166347 - (view) |
Author: Meador Inge (meador.inge) * |
Date: 2012-07-25 01:56 |
| 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. |
|
|
| msg166355 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-07-25 05:58 |
| 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). |
|
|
| msg166358 - (view) |
Author: Martin v. Löwis (loewis) * |
Date: 2012-07-25 06:39 |
| 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) |
|
|
| msg166409 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2012-07-25 16:29 |
| 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 ). 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". |
|
|
| msg166410 - (view) |
Author: Martin v. Löwis (loewis) * |
Date: 2012-07-25 16:37 |
| 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" |
|
|
| msg166597 - (view) |
Author: Antoine Pitrou (pitrou) * |
Date: 2012-07-27 18:51 |
| > OK, I propose to completely drop the Doc/ACKS.txt from the documentation, and replace it with the words Sounds good to me. |
|
|
| msg166606 - (view) |
Author: Terry J. Reedy (terry.reedy) * |
Date: 2012-07-27 21:07 |
| 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. |
|
|
| msg170463 - (view) |
Author: Roundup Robot (python-dev)  |
Date: 2012-09-13 22:59 |
| 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 |
|
|