{"action":"created","issue":{"url":"https://api.github.com/repos/Microsoft/vscode-docs/issues/230","repository_url":"https://api.github.com/repos/Microsoft/vscode-docs","labels_url":"https://api.github.com/repos/Microsoft/vscode-docs/issues/230/labels{/name}","comments_url":"https://api.github.com/repos/Microsoft/vscode-docs/issues/230/comments","events_url":"https://api.github.com/repos/Microsoft/vscode-docs/issues/230/events","html_url":"https://github.com/Microsoft/vscode-docs/issues/230","id":140783772,"number":230,"title":"Please document json file format","user":{"login":"JanKok","id":7545571,"avatar_url":"https://avatars.githubusercontent.com/u/7545571?v=3","gravatar_id":"","url":"https://api.github.com/users/JanKok","html_url":"https://github.com/JanKok","followers_url":"https://api.github.com/users/JanKok/followers","following_url":"https://api.github.com/users/JanKok/following{/other_user}","gists_url":"https://api.github.com/users/JanKok/gists{/gist_id}","starred_url":"https://api.github.com/users/JanKok/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JanKok/subscriptions","organizations_url":"https://api.github.com/users/JanKok/orgs","repos_url":"https://api.github.com/users/JanKok/repos","events_url":"https://api.github.com/users/JanKok/events{/privacy}","received_events_url":"https://api.github.com/users/JanKok/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2016-03-14T20:07:19Z","updated_at":"2016-03-16T05:55:25Z","closed_at":null,"body":"I have had several difficulties due to lack of documentation about the launch.json and tasks.json files. In the latest case, I had trouble passing a file path to my target program. See https://github.com/Microsoft/vscode/issues/4057\r\nI think what is needed is:\r\n1. Some documentation for each json file. This documentation should be referenced wherever launch.json and tasks.json are mentioned in the user docs. Also, where these json docs mention the \"args\": parameter, they should reference item #2 below. This json documentation doesn't necessarily have to be new web pages. I think it might be adequate to document the format in the files themselves, similar to what is done with Default Settings and settings.json.\r\n2. A detailed explanation of how the \"args\": parameter is parsed and the args passed to the target. I would suggest several parts to this:\r\n2.1 Several examples to help get the user on his way. Show the user how to pass:\r\n* File paths that include backslashes, slashes, blanks, wildcards (*, ?,...), environment variables (%WINDOWS%, $PATH, ${file}) and other special characters.\r\n* Zero-length strings, for example sometimes you want to start a program that can talk to X windows but tell it not to talk to X windows, using the call `xprogram -d ''`\r\n* Literal strings, for example, how to pass `${file}` to the target program as the string dollar-sign, open-brace, f, i, ...? This may actually be useful, for example when passing args to the gdb start command, because the start command interprets its args like a shell, so you might want to pass something like `$PATH` or `$MY_ENV_VAR` literally to some program.\r\n* Other special characters, such as newline chars (maybe not so useful) or non-ASCII character strings.\r\n\r\n2.2 An explanation of the process whereby args get from the json file to the target program, so that the user can understand and figure out how to handle difficult cases not covered by the examples. My understanding is: VSCode parses the json file using certain rules about backslash, double quote, etc., then passes the array of strings to the appropriate extension, which typically passes the args unchanged (or concatenated with spaces) to the target program, which in some cases (such as gdb) may do additional processing on the args.\r\n2.3 Give a simple program in several languages for checking out how args are passed. For example, in PowerShell, this one-line program seems to print the args, one per line:\r\n`Write-Output \"args:\", $args`\r\nHowever, I'm not a PowerShell expert, so that may not be exactly right. PowerShell has a habit of evaluating arguments in unexpected ways. That's why it would be good to have some examples from reliable, expert sources.\r\n3. Extension writers should be advised to reference these documents and also to provide any additional details that may be needed in their own documentation. For example, gdb extensions should mention the additional evaluation step that gdb does with the start args."},"comment":{"url":"https://api.github.com/repos/Microsoft/vscode-docs/issues/comments/197164820","html_url":"https://github.com/Microsoft/vscode-docs/issues/230#issuecomment-197164820","issue_url":"https://api.github.com/repos/Microsoft/vscode-docs/issues/230","id":197164820,"user":{"login":"raregrass","id":3363650,"avatar_url":"https://avatars.githubusercontent.com/u/3363650?v=3","gravatar_id":"","url":"https://api.github.com/users/raregrass","html_url":"https://github.com/raregrass","followers_url":"https://api.github.com/users/raregrass/followers","following_url":"https://api.github.com/users/raregrass/following{/other_user}","gists_url":"https://api.github.com/users/raregrass/gists{/gist_id}","starred_url":"https://api.github.com/users/raregrass/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/raregrass/subscriptions","organizations_url":"https://api.github.com/users/raregrass/orgs","repos_url":"https://api.github.com/users/raregrass/repos","events_url":"https://api.github.com/users/raregrass/events{/privacy}","received_events_url":"https://api.github.com/users/raregrass/received_events","type":"User","site_admin":false},"created_at":"2016-03-16T05:55:25Z","updated_at":"2016-03-16T05:55:25Z","body":"That's very helpful. I think documents for lanch.json and tasks.json will give new coming people like me a big picture about what could be use in vscode and how it does. \r\n\r\nFor vscode, IMO, those config files maybe the barriers to entry. Thanks for your job if you could put some docs."}}