{"action":"created","issue":{"url":"https://api.github.com/repos/NixOS/nixpkgs/issues/26940","repository_url":"https://api.github.com/repos/NixOS/nixpkgs","labels_url":"https://api.github.com/repos/NixOS/nixpkgs/issues/26940/labels{/name}","comments_url":"https://api.github.com/repos/NixOS/nixpkgs/issues/26940/comments","events_url":"https://api.github.com/repos/NixOS/nixpkgs/issues/26940/events","html_url":"https://github.com/NixOS/nixpkgs/pull/26940","id":239296056,"number":26940,"title":"NixOS Manual: Make it easier to debug","user":{"login":"grahamc","id":76716,"avatar_url":"https://avatars0.githubusercontent.com/u/76716?v=3","gravatar_id":"","url":"https://api.github.com/users/grahamc","html_url":"https://github.com/grahamc","followers_url":"https://api.github.com/users/grahamc/followers","following_url":"https://api.github.com/users/grahamc/following{/other_user}","gists_url":"https://api.github.com/users/grahamc/gists{/gist_id}","starred_url":"https://api.github.com/users/grahamc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/grahamc/subscriptions","organizations_url":"https://api.github.com/users/grahamc/orgs","repos_url":"https://api.github.com/users/grahamc/repos","events_url":"https://api.github.com/users/grahamc/events{/privacy}","received_events_url":"https://api.github.com/users/grahamc/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":10,"created_at":"2017-06-28T21:02:25Z","updated_at":"2017-06-29T23:49:05Z","closed_at":"2017-06-29T23:45:17Z","pull_request":{"url":"https://api.github.com/repos/NixOS/nixpkgs/pulls/26940","html_url":"https://github.com/NixOS/nixpkgs/pull/26940","diff_url":"https://github.com/NixOS/nixpkgs/pull/26940.diff","patch_url":"https://github.com/NixOS/nixpkgs/pull/26940.patch"},"body":"###### Motivation for this change\r\n\r\nWhen hacking on the manual, if you make an markup error like an invalid tag you get bogus validation results:\r\n\r\n```\r\nmanual.xml:5: element chapter: Relax-NG validity error : Element part has extra content: chapter\r\n```\r\n\r\nexcept I added that to `installation/installing.xml`!\r\n\r\nDebugging this further, I found `jing` makes a much better error message. First I perform the `xincludes` and produce a single monolithic manual file, then run jing, and get:\r\n\r\n```\r\n/tmp/nix-build-nixos-manual-combined.drv-0/./manual-combined.xml:313:10: error: element \"chapter\" not allowed here; expected element \"address\", \"anchor\", ...\r\n```\r\n\r\nWith `--keep-failed`:\r\n\r\n```\r\n$ cat /tmp/nix-build-nixos-manual-combined.drv-0/./manual-combined.xml | head -n 318 | tail -n10\r\ntypical sequence of commands for installing NixOS on an empty hard\r\ndrive (here <filename>/dev/sda</filename>).  <xref linkend=\"ex-config\"/> shows a corresponding configuration Nix expression.</para>\r\n\r\n<example xml:id=\"ex-install-sequence\"><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>\r\n<chapter><screen>\r\n# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>\r\n# mkfs.ext4 -L nixos /dev/sda1\r\n# mkswap -L swap /dev/sda2\r\n# swapon /dev/sda2\r\n# mount /dev/disk/by-label/nixos /mnt\r\n```\r\n\r\nBingo! I added the chapter in the wrong place.\r\n\r\nBy performing xinclude in one place, this also means the error is only outputted once, and not many times (once per manual type.)\r\n\r\n###### Things done\r\n\r\n- [x] Tested using sandboxing\r\n  ([nix.useSandbox](http://nixos.org/nixos/manual/options.html#opt-nix.useSandbox) on NixOS,\r\n    or option `build-use-sandbox` in [`nix.conf`](http://nixos.org/nix/manual/#sec-conf-file)\r\n    on non-NixOS)\r\n- Built on platform(s)\r\n   - [x] NixOS\r\n   - [ ] macOS\r\n   - [ ] Linux\r\n- [x] Tested via one or more NixOS test(s) if existing and applicable for the change (look inside [nixos/tests](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests))\r\n- [x] Tested compilation of all pkgs that depend on this change using `nix-shell -p nox --run \"nox-review wip\"`\r\n- [x] Tested execution of all binary files (usually in `./result/bin/`)\r\n- [x] Fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md).\r\n\r\nAdditionally, I word-diffed the results of this to the current process, and received effectively identical output, for each of the following:\r\n\r\n`nix-build ./nixos/release.nix -A manual.x86_64-linux -A manualEpub.x86_64-linux -A manpages.x86_64-linux -A options`\r\n\r\n---\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/NixOS/nixpkgs/issues/comments/312137608","html_url":"https://github.com/NixOS/nixpkgs/pull/26940#issuecomment-312137608","issue_url":"https://api.github.com/repos/NixOS/nixpkgs/issues/26940","id":312137608,"user":{"login":"grahamc","id":76716,"avatar_url":"https://avatars0.githubusercontent.com/u/76716?v=3","gravatar_id":"","url":"https://api.github.com/users/grahamc","html_url":"https://github.com/grahamc","followers_url":"https://api.github.com/users/grahamc/followers","following_url":"https://api.github.com/users/grahamc/following{/other_user}","gists_url":"https://api.github.com/users/grahamc/gists{/gist_id}","starred_url":"https://api.github.com/users/grahamc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/grahamc/subscriptions","organizations_url":"https://api.github.com/users/grahamc/orgs","repos_url":"https://api.github.com/users/grahamc/repos","events_url":"https://api.github.com/users/grahamc/events{/privacy}","received_events_url":"https://api.github.com/users/grahamc/received_events","type":"User","site_admin":false},"created_at":"2017-06-29T23:49:05Z","updated_at":"2017-06-29T23:49:05Z","body":"(merged without the debug notice commit)"}}
{"actor":{"display_login":"grahamc"}}