{"action":"created","issue":{"url":"https://api.github.com/repos/QubesOS/qubes-issues/issues/4179","repository_url":"https://api.github.com/repos/QubesOS/qubes-issues","labels_url":"https://api.github.com/repos/QubesOS/qubes-issues/issues/4179/labels{/name}","comments_url":"https://api.github.com/repos/QubesOS/qubes-issues/issues/4179/comments","events_url":"https://api.github.com/repos/QubesOS/qubes-issues/issues/4179/events","html_url":"https://github.com/QubesOS/qubes-issues/issues/4179","id":347471496,"node_id":"MDU6SXNzdWUzNDc0NzE0OTY=","number":4179,"title":"Markdown convention about code snippets, shell commands and their terminal outputs","user":{"login":"tokideveloper","id":28876601,"node_id":"MDQ6VXNlcjI4ODc2NjAx","avatar_url":"https://avatars2.githubusercontent.com/u/28876601?v=4","gravatar_id":"","url":"https://api.github.com/users/tokideveloper","html_url":"https://github.com/tokideveloper","followers_url":"https://api.github.com/users/tokideveloper/followers","following_url":"https://api.github.com/users/tokideveloper/following{/other_user}","gists_url":"https://api.github.com/users/tokideveloper/gists{/gist_id}","starred_url":"https://api.github.com/users/tokideveloper/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tokideveloper/subscriptions","organizations_url":"https://api.github.com/users/tokideveloper/orgs","repos_url":"https://api.github.com/users/tokideveloper/repos","events_url":"https://api.github.com/users/tokideveloper/events{/privacy}","received_events_url":"https://api.github.com/users/tokideveloper/received_events","type":"User","site_admin":false},"labels":[{"id":184545381,"node_id":"MDU6TGFiZWwxODQ1NDUzODE=","url":"https://api.github.com/repos/QubesOS/qubes-issues/labels/C:%20doc","name":"C: doc","color":"cccccc","default":false},{"id":255451969,"node_id":"MDU6TGFiZWwyNTU0NTE5Njk=","url":"https://api.github.com/repos/QubesOS/qubes-issues/labels/task","name":"task","color":"207de5","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":{"url":"https://api.github.com/repos/QubesOS/qubes-issues/milestones/22","html_url":"https://github.com/QubesOS/qubes-issues/milestone/22","labels_url":"https://api.github.com/repos/QubesOS/qubes-issues/milestones/22/labels","id":1390120,"node_id":"MDk6TWlsZXN0b25lMTM5MDEyMA==","number":22,"title":"Ongoing","description":"Milestone for tasks independent of the Qubes OS release cycle. Includes website, documentation, and project management issues.","creator":{"login":"marmarek","id":726704,"node_id":"MDQ6VXNlcjcyNjcwNA==","avatar_url":"https://avatars1.githubusercontent.com/u/726704?v=4","gravatar_id":"","url":"https://api.github.com/users/marmarek","html_url":"https://github.com/marmarek","followers_url":"https://api.github.com/users/marmarek/followers","following_url":"https://api.github.com/users/marmarek/following{/other_user}","gists_url":"https://api.github.com/users/marmarek/gists{/gist_id}","starred_url":"https://api.github.com/users/marmarek/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/marmarek/subscriptions","organizations_url":"https://api.github.com/users/marmarek/orgs","repos_url":"https://api.github.com/users/marmarek/repos","events_url":"https://api.github.com/users/marmarek/events{/privacy}","received_events_url":"https://api.github.com/users/marmarek/received_events","type":"User","site_admin":false},"open_issues":121,"closed_issues":174,"state":"open","created_at":"2015-11-02T23:04:05Z","updated_at":"2018-10-27T23:18:25Z","due_on":null,"closed_at":null},"comments":12,"created_at":"2018-08-03T17:07:38Z","updated_at":"2018-10-29T20:17:16Z","closed_at":null,"author_association":"NONE","body":"I'd like to propose to add a [Markdown convention] item on how to format commands on the command line and their terminal outputs:\r\n\r\n- If a shell command follows that has to be entered into a terminal then\r\n    - state clearly in the text in front of it\r\n        - that a command will follow which shall be entered into a terminal,\r\n        - in which VM (or other machine) the terminal has to be started,\r\n        - as which user the command shall be executed and\r\n        - what the command should do.\r\n    - Write the command always as a code block using either\r\n        - a [fenced code block] by three backticks or tildes (*without* an [info string]) or\r\n        - an [indented code block] by four leading spaces on each line.\r\n      Don't use [inlines] (i.e. code snippets within the normal text) for that.\r\n    - In front of the command, write the shell prompt (e.g. `[user@dom0 ~]$`) the user should expect.\r\n    - *Always* describe in the following text what the output of the command will look like. This could include:\r\n        - *The output should be empty.*\r\n        - *The output will probably be very large. That's why we omit it here.*\r\n        - *The output should not contain any error messages like `ERROR: Lorem ipsum ...`.*\r\n        - *The output will look like this:* plus a separate code block containing the expected output.\r\n\r\nMaybe we should add some examples and counterexamples for clarification.\r\n\r\nThe **reasons for this item** include:\r\n- Making it easier for the users and translators to distinguish between prompts, commands, command outputs and file excerpts. See #4038.\r\n- Making it easier for the users to compare their terminal outputs with the expected outputs.\r\n- Unifying the formatting, of course.\r\n\r\nAny ideas, opinions or comments so far?\r\n\r\n[markdown convention]: https://www.qubes-os.org/doc/doc-guidelines/#markdown-conventions\r\n[fenced code block]: https://github.github.com/gfm/#fenced-code-blocks\r\n[indented code block]: https://github.github.com/gfm/#indented-code-blocks\r\n[info string]: https://github.github.com/gfm/#info-string\r\n[inlines]: https://github.github.com/gfm/#inlines"},"comment":{"url":"https://api.github.com/repos/QubesOS/qubes-issues/issues/comments/434062950","html_url":"https://github.com/QubesOS/qubes-issues/issues/4179#issuecomment-434062950","issue_url":"https://api.github.com/repos/QubesOS/qubes-issues/issues/4179","id":434062950,"node_id":"MDEyOklzc3VlQ29tbWVudDQzNDA2Mjk1MA==","user":{"login":"tokideveloper","id":28876601,"node_id":"MDQ6VXNlcjI4ODc2NjAx","avatar_url":"https://avatars2.githubusercontent.com/u/28876601?v=4","gravatar_id":"","url":"https://api.github.com/users/tokideveloper","html_url":"https://github.com/tokideveloper","followers_url":"https://api.github.com/users/tokideveloper/followers","following_url":"https://api.github.com/users/tokideveloper/following{/other_user}","gists_url":"https://api.github.com/users/tokideveloper/gists{/gist_id}","starred_url":"https://api.github.com/users/tokideveloper/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tokideveloper/subscriptions","organizations_url":"https://api.github.com/users/tokideveloper/orgs","repos_url":"https://api.github.com/users/tokideveloper/repos","events_url":"https://api.github.com/users/tokideveloper/events{/privacy}","received_events_url":"https://api.github.com/users/tokideveloper/received_events","type":"User","site_admin":false},"created_at":"2018-10-29T20:17:16Z","updated_at":"2018-10-29T20:17:16Z","author_association":"NONE","body":"> > On our FAQ page, there are several inlines (and sometimes it's not clear that they are to be typed or copied into a terminal), so, there is definitely a need IMHO.\r\n> \r\n> That can or should be clarified in the text. Code blocks are not the only way to do it.\r\n\r\nOkay. It's like inline formulas within math text.\r\n\r\n> > The second part shall say that e.g. if there are a lot output lines between some input lines then some of the input lines could get lost in the shuffle. So, within a code block, a single (and maybe lengthy) command together with its lengthy output might be enough. The next command should be moved into a separate code block and so on.\r\n> \r\n> Depends on the situation. Again, just use common sense and try to be as clear and unambiguous as possible. You're trying to make overly-specific syntactical rules that will probably backfire or be ignored when unanticipated situations arise.\r\n\r\nOkay, sounds persuasive.\r\n\r\n> > The problem with common sense is that everybody has a slightly different opinion of what common sense is. In a certain way, all of our convention rules could also be interpreted as just common sense. So, why do we need them anyway? Simply because common sense is not clear enough on its own IMHO.\r\n> \r\n> No. Many of our conventions are not things that people would arrive at purely through common sense, and they're important enough to mention. Some of the things you're fixated on are simply not important enough to spend time, space, and effort on, and in some cases they _would_ be taken care of by common sense, given the existence of the other guidelines.\r\n\r\nThe cause seems to be that sometimes I don't trust in other people enough. But that's my burden. I should learn to just relax ... Good things will happen. No intervention required. :-)\r\n"}}
{"actor":{"display_login":"tokideveloper"}}