| msg120937 - (view) |
Author: Alexander Belopolsky (belopolsky) *  |
Date: 2010-11-11 02:52 |
| I was going to commit this patch, but decided to ask for a second opinion. I think module names in section titles should be marked up with :mod:. |
|
|
| msg120956 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2010-11-11 15:19 |
| Marking up each and every instance of a module name is not mandatory IMO. What’s important is that each document title starts with the :mod: construct, so that the HTML titles and index (at /library) be consistently useful. See for example ast (which also suffers from non-standard markup in its docstring, but that’s another issue). In addition, there are hierarchy problems in the index. |
|
|
| msg121057 - (view) |
Author: Terry J. Reedy (terry.reedy) * |
Date: 2010-11-12 19:09 |
| 1. Does the markup make any visual difference? 2. Does the markup affect the index? 3. What do other module docs do? I notice that 'Tkinter' appears in several section headings. Is it marked? (Is the upper case a holdover that should be lowercased?) 'Turtle' also appears in several section headers. That could be interpreted as a reference to the class rather than the module. |
|
|
| msg121061 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-12 19:27 |
| On Fri, Nov 12, 2010 at 2:09 PM, Terry J. Reedy <report@bugs.python.org> wrote: .. > 1. Does the markup make any visual difference? It does on my browser. (I wouldn't have noticed it otherwise.) See http://docs.python.org/dev/contents.html > 2. Does the markup affect the index? I don't think so because module names are already in the index. This is either holdover or title-case. In either case it should be fixed. Note that in some section titles it is lower case and marked up properly. > 'Turtle' also appears in several section headers. That could be interpreted > as a reference to the class rather than the module. In "Turtle graphics" it is neither -- just part of the name of the graphics framework. When it is a name of the class, as in " Overview of available Turtle and Screen methods," is should be marked up with :class: IMO. In "Tell Turtle’s state", I think "turtle" should be lower-cased. |
|
|
| msg121066 - (view) |
Author: Georg Brandl (georg.brandl) * |
Date: 2010-11-12 19:48 |
| Eric: any :mod: role never affects the index. Only the module directive does. Otherwise, I concur that it's not mandatory to mark up every occurrence of the module name, but it's nice in section headings. |
|
|
| msg121069 - (view) |
Author: Terry J. Reedy (terry.reedy) * |
Date: 2010-11-12 20:22 |
| >http://docs.python.org/dev/contents.html The only thing I see there is the bold-facing of *PEP 3101*. Is that what you are referring to? In any case, with Georg's concurrence go ahead with this and any other modules you care about. |
|
|
| msg121093 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2010-11-12 23:50 |
| I think that using e.g. :mod:`subprocess` in the subprocess page is redundant because there's no need to add a link to the page you are already reading. I'm also not sure that it looks too nice in the headers (iirc the font is different), but I haven't tried to apply the patch and see how it looks. |
|
|
| msg175140 - (view) |
Author: Roundup Robot (python-dev)  |
Date: 2012-11-08 08:12 |
| New changeset 58564aeec8e4 by Ezio Melotti in branch '2.7': #10385: use the mod role in subprocess docs. http://hg.python.org/cpython/rev/58564aeec8e4 New changeset 8e8d391eb3eb by Ezio Melotti in branch '3.2': #10385: use the mod role in subprocess docs. http://hg.python.org/cpython/rev/8e8d391eb3eb New changeset f45d1afb952b by Ezio Melotti in branch '3.3': #10385: merge with 3.2. http://hg.python.org/cpython/rev/f45d1afb952b New changeset 5d7e7e7e2e82 by Ezio Melotti in branch 'default': #10385: merge with 3.3. http://hg.python.org/cpython/rev/5d7e7e7e2e82 |
|
|
| msg175141 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2012-11-08 08:18 |
| It looked OK and the :mod: role was already used throughout the page, so I applied the patch. |
|
|