{"action":"created","issue":{"url":"https://api.github.com/repos/openssl/openssl/issues/403","labels_url":"https://api.github.com/repos/openssl/openssl/issues/403/labels{/name}","comments_url":"https://api.github.com/repos/openssl/openssl/issues/403/comments","events_url":"https://api.github.com/repos/openssl/openssl/issues/403/events","html_url":"https://github.com/openssl/openssl/pull/403","id":106949024,"number":403,"title":"man pages: adjust & regularize formatting","user":{"login":"apjanke","id":2618447,"avatar_url":"https://avatars.githubusercontent.com/u/2618447?v=3","gravatar_id":"","url":"https://api.github.com/users/apjanke","html_url":"https://github.com/apjanke","followers_url":"https://api.github.com/users/apjanke/followers","following_url":"https://api.github.com/users/apjanke/following{/other_user}","gists_url":"https://api.github.com/users/apjanke/gists{/gist_id}","starred_url":"https://api.github.com/users/apjanke/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apjanke/subscriptions","organizations_url":"https://api.github.com/users/apjanke/orgs","repos_url":"https://api.github.com/users/apjanke/repos","events_url":"https://api.github.com/users/apjanke/events{/privacy}","received_events_url":"https://api.github.com/users/apjanke/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":17,"created_at":"2015-09-17T09:52:20Z","updated_at":"2015-09-18T06:20:39Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/openssl/openssl/pulls/403","html_url":"https://github.com/openssl/openssl/pull/403","diff_url":"https://github.com/openssl/openssl/pull/403.diff","patch_url":"https://github.com/openssl/openssl/pull/403.patch"},"body":"STATUS: Don't merge yet; still under discussion, with more commits to come.\r\n\r\nThis PR modifies and regularizes formatting for the man pages.\r\n\r\nThis is only done for the `dgst`, `openssl`, `passwd`, and `rsa` commands so far. If you're interested, I'll make the same formatting changes on the rest of the pages and roll those in to this PR.\r\n\r\nApplies formatting:\r\n - Bold for literal text, underline for placeholders\r\n - Capitalize list item text\r\n - Two spaces between sentences\r\n - '...' for \"more items\" is a separate token\r\n - Oxford commas\r\n - Remove blank lines at top of page (for easy side-by-side comparison in editors)\r\n\r\nThis also corrects a couple typos, and adds a couple missing elements to the synopsis of `dgst`.\r\n\r\n##  Example  ##\r\n\r\nBefore:\r\n\r\n<img width=\"699\" alt=\"screen shot 2015-09-17 at 5 49 23 am\" src=\"https://cloud.githubusercontent.com/assets/2618447/9930169/eb69068e-5cff-11e5-8424-d02b1a380afe.png\">\r\n\r\n\r\nAfter:\r\n\r\n<img width=\"613\" alt=\"screen shot 2015-09-17 at 5 49 26 am\" src=\"https://cloud.githubusercontent.com/assets/2618447/9930173/ef61500c-5cff-11e5-903c-0e29111734e7.png\">\r\n\r\n\r\n\r\n\r\n##  Formatting choices  ##\r\n\r\n###  Grammar Markup   ###\r\n\r\nExisting man pages use bold markup for most command text. This change modifies it to use:\r\n* Bold (`B<...>`) for literal text to be entered as is\r\n* Underline/italic (`I<...>`) for placeholders (\"metasyntactic variables\") that the user is supposed to replace with other text\r\n* Plain for structural grammar elements (like the `[...]` that indicate optional things or `|` for alternation)\r\n\r\nI think this makes it a bit more readable, particularly in distinguishing literal text from placeholders.\r\n\r\nThese markup choices are consistent with those I've seen in other major man pages, particularly the BSD commands in OS X and the GNU coreutils commands that choose to use markup.\r\n\r\n###  Two spaces  ###\r\n\r\nExisting man pages put sometimes one and sometimes two spaces following the period between sentences. In HTML this doesn't matter, but in pod/man, these are significant. We should be consistent. I've adopted two spaces, since that seems to be slightly more common in the existing man pages, and that's what left-justified man pages from BSD and GNU seem to use.\r\n\r\n##   References   ##\r\n\r\n* [Linux `man-pages` man page](http://man7.org/linux/man-pages/man7/man-pages.7.html)\r\n* [Old \"is there a man page style guide\"? discussion](https://lists.gnu.org/archive/html/groff/2001-10/msg00052.html)\r\n* [`perlpodstyle` - Perl POD style guide](http://perldoc.perl.org/perlpodstyle.html)\r\n* [`man mdoc` from mandoc project](http://mdocml.bsd.lv/man/mdoc.7.html) (more authoritative)\r\n* [`man groff_mdoc` from FreeBSD](https://www.freebsd.org/cgi/man.cgi?query=mdoc) (less authoritative)\r\n\r\n##   Commands/Topics  ##\r\n\r\nList of the man page files in openssl. Check mark means I've reformatted that one.\r\n\r\n####   apps/    ####\r\n\r\n- [x] CA.pl\r\n- [X] asn1parse\r\n- [ ] ca\r\n- [ ] ciphers\r\n- [ ] cms\r\n- [ ] config\r\n- [ ] crl\r\n- [ ] crl2pkcs7\r\n- [X] dgst\r\n- [ ] dhparam\r\n- [X] dsa\r\n- [ ] dsaparam\r\n- [ ] ec\r\n- [ ] ecparam\r\n- [ ] enc\r\n- [ ] errstr\r\n- [ ] gendsa\r\n- [ ] genpkey\r\n- [ ] genrsa\r\n- [ ] nseq\r\n- [ ] ocsp\r\n- [X] openssl\r\n- [X] passwd\r\n- [ ] pkcs12\r\n- [ ] pkcs7\r\n- [ ] pkcs8\r\n- [ ] pkey\r\n- [ ] pkeyparam\r\n- [ ] pkeyutl\r\n- [ ] rand\r\n- [ ] rehash\r\n- [ ] req\r\n- [X] rsa\r\n- [ ] rsautl\r\n- [ ] s_client\r\n- [ ] s_server\r\n- [ ] s_time\r\n- [ ] sess_id\r\n- [ ] smime\r\n- [ ] speed\r\n- [ ] spkac\r\n- [ ] ts\r\n- [x] tsget\r\n- [ ] verify\r\n- [x] version\r\n- [ ] x509\r\n- [ ] x509v3_config\r\n\r\n\r\n####     crypto/    ####\r\n\r\n_(Long list omitted because I'm just going to do apps/ for now)_"},"comment":{"url":"https://api.github.com/repos/openssl/openssl/issues/comments/141355650","html_url":"https://github.com/openssl/openssl/pull/403#issuecomment-141355650","issue_url":"https://api.github.com/repos/openssl/openssl/issues/403","id":141355650,"user":{"login":"apjanke","id":2618447,"avatar_url":"https://avatars.githubusercontent.com/u/2618447?v=3","gravatar_id":"","url":"https://api.github.com/users/apjanke","html_url":"https://github.com/apjanke","followers_url":"https://api.github.com/users/apjanke/followers","following_url":"https://api.github.com/users/apjanke/following{/other_user}","gists_url":"https://api.github.com/users/apjanke/gists{/gist_id}","starred_url":"https://api.github.com/users/apjanke/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apjanke/subscriptions","organizations_url":"https://api.github.com/users/apjanke/orgs","repos_url":"https://api.github.com/users/apjanke/repos","events_url":"https://api.github.com/users/apjanke/events{/privacy}","received_events_url":"https://api.github.com/users/apjanke/received_events","type":"User","site_admin":false},"created_at":"2015-09-18T06:20:39Z","updated_at":"2015-09-18T06:20:39Z","body":"@levitte I love this nerdy attention to detail. :)\r\n\r\nThis might be system or configuration dependent: on my OS X 10.9.5 box with `Perldoc v3.17, under perl v5.016002`, that `perldoc` command results in two spaces after LF-terminated sentences. E.g.:\r\n\r\n```\r\nThen an B<SSL_CTX> object is created as a framework to establish\r\nTLS/SSL enabled connections (see L<SSL_CTX_new(3)>).\r\nVarious options regarding certificates, algorithms etc. can be set\r\nin this object.\r\n```\r\n<img width=\"500\" alt=\"screen shot 2015-09-18 at 2 13 54 am\" src=\"https://cloud.githubusercontent.com/assets/2618447/9953041/0ac95988-5dab-11e5-9a9b-f09eeb02bc76.png\">\r\n\r\nIf that is the case, it's a nice result, b/c it means that the formatting could respect user's local configuration and/or their system conventions. (And work well in other output formats, like proportional-width HTML or PDF targets, where \"real\" typographical sentence spacing could be used.)\r\n\r\nI still need to read that `mdoc` stuff, but as of now I'm rather leaning toward \"LF-terminated sentences\", and even \"each sentence on exactly one line\". That would give us maximum flexibility by deferring all sentence spacing to the downstream typesetting system (which sounds like the Right Thing) and turns out to be the least work for me (and future editors, I suspect) while doing reformatting, because I don't have to manually reflow any text for readability. Could also end up producing nicer `diff` output because in-sentence changes could be highlighted instead of spreading across multiple reflowed lines.\r\n"}}