{"action":"created","issue":{"url":"https://api.github.com/repos/cplusplus/draft/issues/781","repository_url":"https://api.github.com/repos/cplusplus/draft","labels_url":"https://api.github.com/repos/cplusplus/draft/issues/781/labels{/name}","comments_url":"https://api.github.com/repos/cplusplus/draft/issues/781/comments","events_url":"https://api.github.com/repos/cplusplus/draft/issues/781/events","html_url":"https://github.com/cplusplus/draft/issues/781","id":163297161,"number":781,"title":"\\pnums in examples/notes/effects/etc. are ugly and confusing","user":{"login":"burblebee","id":6687528,"avatar_url":"https://avatars.githubusercontent.com/u/6687528?v=3","gravatar_id":"","url":"https://api.github.com/users/burblebee","html_url":"https://github.com/burblebee","followers_url":"https://api.github.com/users/burblebee/followers","following_url":"https://api.github.com/users/burblebee/following{/other_user}","gists_url":"https://api.github.com/users/burblebee/gists{/gist_id}","starred_url":"https://api.github.com/users/burblebee/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/burblebee/subscriptions","organizations_url":"https://api.github.com/users/burblebee/orgs","repos_url":"https://api.github.com/users/burblebee/repos","events_url":"https://api.github.com/users/burblebee/events{/privacy}","received_events_url":"https://api.github.com/users/burblebee/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"burblebee","id":6687528,"avatar_url":"https://avatars.githubusercontent.com/u/6687528?v=3","gravatar_id":"","url":"https://api.github.com/users/burblebee","html_url":"https://github.com/burblebee","followers_url":"https://api.github.com/users/burblebee/followers","following_url":"https://api.github.com/users/burblebee/following{/other_user}","gists_url":"https://api.github.com/users/burblebee/gists{/gist_id}","starred_url":"https://api.github.com/users/burblebee/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/burblebee/subscriptions","organizations_url":"https://api.github.com/users/burblebee/orgs","repos_url":"https://api.github.com/users/burblebee/repos","events_url":"https://api.github.com/users/burblebee/events{/privacy}","received_events_url":"https://api.github.com/users/burblebee/received_events","type":"User","site_admin":false},"assignees":[{"login":"burblebee","id":6687528,"avatar_url":"https://avatars.githubusercontent.com/u/6687528?v=3","gravatar_id":"","url":"https://api.github.com/users/burblebee","html_url":"https://github.com/burblebee","followers_url":"https://api.github.com/users/burblebee/followers","following_url":"https://api.github.com/users/burblebee/following{/other_user}","gists_url":"https://api.github.com/users/burblebee/gists{/gist_id}","starred_url":"https://api.github.com/users/burblebee/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/burblebee/subscriptions","organizations_url":"https://api.github.com/users/burblebee/orgs","repos_url":"https://api.github.com/users/burblebee/repos","events_url":"https://api.github.com/users/burblebee/events{/privacy}","received_events_url":"https://api.github.com/users/burblebee/received_events","type":"User","site_admin":false}],"milestone":null,"comments":12,"created_at":"2016-07-01T00:41:59Z","updated_at":"2016-07-07T23:48:07Z","closed_at":null,"body":"Adding \\pnums added in the middle of examples and notes makes it hard to see where the example/note starts/ends, and \\pnums added in \\effects (or other) clauses causes the wording to spill over into a new paragraph making it look like it's no longer part of the Effects (or other).\r\n\r\nAs an example of \\pnums in an example, have a look at 27.10.8.6.2 [path.factory]/p4 - it has new paragraphs as they appeared in the original wording, but it is ugly!  See also the Note above in 27.10.8.6 [path.non-member]/p8.\r\n\r\nInserting a blank line in the Latex before the text in the examples/notes/effects/etc. seems to work - is there a better way?  In any case, I think we should fix these as we come across them.  Or in one big swoop if someone has the patience.\r\n\r\nHaving examples embedded in the paragraph is ugly also - see 1.9 [intro.execution]/p16.  It would be nice to address those while we're at it, perhaps also by inserting a blank line before/after the example?  \\linebreak doesn't work because it causes the previous line to get stretched, and \\linebreak after a blank line results in an error.\r\n\r\nHere's a few examples of embedded \\pnums that I think we may want to fix:\r\n* \\pnums in clauses:\r\n** [ios.members.static]/p3\r\n** [streambuf.virt.pback]/p3\r\n** [istream::sentry]/p3\r\n** [istream::extractors]/p7\r\n** [istream::extractors]/p14\r\n** [istream.unformatted]/p8\r\n** [istream.unformatted]/p14\r\n** [istream.unformatted]/p18\r\n** [ostream.inserters.arithmetic]/p1\r\n** [ostream.inserters]/p7 (this is as far as I got thru Clause 27)\r\n\r\n* \\pnums in Examples:\r\n** [path.factory]/p4\r\n** [fs.op.copy]/p6\r\n** [fs.op.system_complete]/p5\r\n** [fs.op.temp_dir_path]/p3\r\n\r\n* \\pnums in Notes:\r\n** [path.non-member]/p8\r\n\r\nHere's a few examples of embedded exampes/notes that I think we may want to fix:\r\n* examples embedded in the paragraphs:\r\n** [intro.execution]/p16\r\n\r\n* notes embedded in the paragraphs:\r\n**  [path.io]/p1"},"comment":{"url":"https://api.github.com/repos/cplusplus/draft/issues/comments/231240193","html_url":"https://github.com/cplusplus/draft/issues/781#issuecomment-231240193","issue_url":"https://api.github.com/repos/cplusplus/draft/issues/781","id":231240193,"user":{"login":"godbyk","id":195036,"avatar_url":"https://avatars.githubusercontent.com/u/195036?v=3","gravatar_id":"","url":"https://api.github.com/users/godbyk","html_url":"https://github.com/godbyk","followers_url":"https://api.github.com/users/godbyk/followers","following_url":"https://api.github.com/users/godbyk/following{/other_user}","gists_url":"https://api.github.com/users/godbyk/gists{/gist_id}","starred_url":"https://api.github.com/users/godbyk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/godbyk/subscriptions","organizations_url":"https://api.github.com/users/godbyk/orgs","repos_url":"https://api.github.com/users/godbyk/repos","events_url":"https://api.github.com/users/godbyk/events{/privacy}","received_events_url":"https://api.github.com/users/godbyk/received_events","type":"User","site_admin":false},"created_at":"2016-07-07T23:48:07Z","updated_at":"2016-07-07T23:48:07Z","body":"**On the general use of `\\pnum`.** I'm kind of getting the impression that the distinction between `\\pnum` and a regular paragraph (whether introduced through a blank line or `\\par` or equivalent) is getting lost.\r\n\r\nIs `\\pnum` being used explicitly to introduced a numbered paragraph or just as the de facto way of creating a new paragraph (and the numbered part may just be an unintentional side effect).\r\n\r\nIn LaTeX a paragraph ends and a new one begins when there is a blank line or when `\\par` (or very occasionally `\\endgraf`) appears. The `\\pnum` macro should only be used to introduce a _numbered_ paragraph.\r\n\r\nA better solution (as opposed to the quick-fix redefinition of `\\pnum` within the `note` and `example` environments above) would be to edit replace all uses of `\\pnum` with a blank line (which I usually prefer) or `\\par` (but please don't use `\\endgraf`).  To help in this endeavor, we could instruct LaTeX to emit a log file containing pointers to all the places where `\\pnum` has been used within a `note` or `example` environment.\r\n\r\n**An alternative proposal.** Instead of removing paragraph numbers within examples and notes, we could number them in the same way we do bulleted lists ((5.1), (5.2), (5.3), etc.). This would allow people to still reference an individual paragraph within an example/note but also make it clear that those paragraphs are still within the the example/note.  This could be accomplished with something like the following (untested):\r\n\r\n```latex\r\n\\newenvironment{note}[1][Note]{%\r\n  \\def\\pnum{\\parabullnum{Bullets1}{0pt}}%\r\n  \\noteintro{#1}}{\\noteoutro{note}\\xspace}\r\n\\newenvironment{example}[1][Example]{%\r\n  \\def\\pnum{\\parabullnum{Bullets1}{0pt}}%\r\n  \\noteintro{#1}}{\\noteoutro{example}\\xspace}\r\n```\r\n\r\n**Typesetting effects, returns, etc.**  To enable more flexibility in the formatting of these, it might be useful to either change the `\\effects` et al. macros to take the text as an argument or turn it into an environment similar to `note` and `example`. This would allow us to change the formatting of the text of each environment easily. Unfortunately, both of those options requires editing the source document extensively.\r\n\r\n**NB:** I don't have a strong opinion on this issue; I'm just offering some options. I'm happy to help implement a solution for whatever the desired formatting should look like."}}
{"actor":{"display_login":"godbyk"}}