Issue 32523: inconsistent spacing in changelog.html (original) (raw)
Created on 2018-01-09 16:21 by ned.deily, last changed 2022-04-11 14:58 by admin.
| Pull Requests | |||
|---|---|---|---|
| URL | Status | Linked | Edit |
| PR 8154 | merged | mdk,2018-07-07 13:56 |
| Messages (12) | ||
|---|---|---|
| msg309711 - (view) | Author: Ned Deily (ned.deily) *  |
Date: 2018-01-09 16:21 |
| The rendered changelog.html files produced "make html" have inconsistent spacing between items. Usually, the first changelog topic section (e.g. Security) starts with no blank lines between items but occasionally some subsequent sections will render with a blank link between items; this seems to be often true for the Library section, but not always. This is visible across the recent 3.x branches; here's an example with the stable 3.5 docs: Library section has blank line separator: https://docs.python.org/3.5/whatsnew/changelog.html#id5 Library section has no blank separators: https://docs.python.org/3.5/whatsnew/changelog.html#id11 | ||
| msg309713 - (view) | Author: Ned Deily (ned.deily) * |
Date: 2018-01-09 16:22 |
| See also discussion at https://github.com/python/core-workflow/issues/209 | ||
| msg317911 - (view) | Author: Ned Deily (ned.deily) * |
Date: 2018-05-28 19:59 |
| @mdk, Would you have time to take a look at this? Thanks! | ||
| msg318709 - (view) | Author: Julien Palard (mdk) * |
Date: 2018-06-04 21:42 |
| It's from docutils (see details below), it can be fixed in pydoctheme.css by adding something like: li p { margin-bottom: 0; } Would look like: https://mdk.fr/list-before.png → https://mdk.fr/list-after.png is it better? (If it's better I still have to ensure this rule won't break something else in another place.) For more information I quote here the docstring of `class HTMLTranslator`: The html4css1 writer has been optimized to produce visually compact lists (less vertical whitespace). HTML's mixed content models allow list items to contain " body elements and body elements combinedtags in "simple" lists: list items contain either a single paragraph, a nested simple list, or a paragraph followed by a nested simple list. This means that this list can be compact: - Item 1. - Item 2. But this list cannot be compact: - Item 1. This second paragraph forces space between list items. - Item 2. - In non-list contexts, omit tags on a paragraph if that paragraph is the only child of its parent (footnotes & citations are allowed a label first). - Regardless of the above, in definitions, table cells, field bodies, option descriptions, and list items, mark the first child with 'class="first"' and the last child with 'class="last"'. The stylesheet sets the margins (top & bottom respectively) to 0 for these elements. |
||
| msg318711 - (view) | Author: Julien Palard (mdk) * |
Date: 2018-06-04 21:53 |
| An intermediate fix would be to remove only bottom of first paragraphs: li p.first { margin-bottom: 0; } It looks like: https://mdk.fr/list-intermediate.png | ||
| msg318713 - (view) | Author: Ned Deily (ned.deily) * |
Date: 2018-06-04 21:55 |
| Thank you for looking into it! In the example you chose, I think the first step would be to trim the two two-paragraph news items to be only one paragraph each; in general, news items should only be a few sentences at most. With that change, I think the choice is pretty clear (to me, at least:): I prefer without the blank lines. And the issue is that today the changelogs have a "random" mixture of both. So, if news items followed that rule, would the css change still be necessary? | ||
| msg318724 - (view) | Author: Julien Palard (mdk) * |
Date: 2018-06-05 05:09 |
| > So, if news items followed that rule, would the css change still be necessary? The CSS change would not be necessary, so yes the issue is "Don't mix paragraphs in changelogs". Maybe we can add an option to blurb merge to only keep the first paragraph, to fix every list in a single shot, then better document the "a single paragraph per news entry"? Would it be OK to edit old Misc/NEWS.d/ to fix it in the past? | ||
| msg321228 - (view) | Author: Terry J. Reedy (terry.reedy) * |
Date: 2018-07-07 18:10 |
| Since 'News entry is one paragraph without subject line' is a change from older policy, I suggest posting a reminder to committers list and rechecking devguide. | ||
| msg321229 - (view) | Author: Julien Palard (mdk) * |
Date: 2018-07-07 18:32 |
| terry: Make sense, I'll also try to add the reminder in blurb if I find an appropriate place and wording. | ||
| msg321351 - (view) | Author: Julien Palard (mdk) * |
Date: 2018-07-09 21:35 |
| Hi Ned, what do you think about https://github.com/python/cpython/pull/8154? I feel this is a bit a huge change in NEWS entry writing policy which make them less readable (in text files). Is it really worth it to change the policy to single-paragraph only just for an HTML rendering issue? Or should we silently join/trim those paragraphs only in blurb merge, maybe with an option like "--trim-paragraphs" while building the HTML documentations? | ||
| msg341996 - (view) | Author: Julien Palard (mdk) * |
Date: 2019-05-09 19:52 |
| New changeset 137be34180a20dba53948d126b961069f299f153 by Julien Palard in branch 'master': bpo-32523: Simplifying news entries with multiple paragraphs. (GH-8154) https://github.com/python/cpython/commit/137be34180a20dba53948d126b961069f299f153 | ||
| msg402963 - (view) | Author: Julien Palard (mdk) * |
Date: 2021-09-30 14:46 |
| This still happen, but it's hard to tell if it'll happen from blurb, as when it's two paragraphs consisting of a text and a list it does not happen, sphinx just put the list as a sublist and it's clean. I don't want to tell people stop using list, it's very readable. Also sometimes having a paragraph, a list, then one or two more paragraphs looks usefull, see examples in [1]. [1]: https://github.com/python/core-workflow/pull/274#issuecomment-931387938 So I'm no longer trying to fix it in blurb. |
| History | |||
|---|---|---|---|
| Date | User | Action | Args |
| 2022-04-11 14:58:56 | admin | set | github: 76704 |
| 2021-09-30 14:46:13 | mdk | set | messages: + |
| 2019-05-09 19:52:37 | mdk | set | messages: + |
| 2018-07-09 21:35:03 | mdk | set | messages: + |
| 2018-07-07 18:32:40 | mdk | set | messages: + stage: patch review -> |
| 2018-07-07 18:10:15 | terry.reedy | set | nosy: + terry.reedymessages: + |
| 2018-07-07 13:56:54 | mdk | set | keywords: + patchstage: patch reviewpull_requests: + <pull%5Frequest7720> |
| 2018-06-05 05:09:48 | mdk | set | messages: + |
| 2018-06-04 21:55:55 | ned.deily | set | messages: + |
| 2018-06-04 21:53:43 | mdk | set | messages: + |
| 2018-06-04 21:42:47 | mdk | set | messages: + |
| 2018-05-28 19:59:49 | ned.deily | set | nosy: + mdkmessages: + versions: + Python 3.8 |
| 2018-01-09 16:22:51 | ned.deily | set | messages: + |
| 2018-01-09 16:21:22 | ned.deily | create |