{"thread":{"id":"47384","subject":"Documentation Breakage at 2.5.6","startedAt":"2017-12-06T04:12:50Z","lastAt":"2017-12-08T22:47:36Z","messageCount":6,"participants":["Randall S. Becker","Ævar Arnfjörð Bjarmason","Jeff King","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"334241","messageId":"008d01d36e48$747cc130$5d764390$@nexbridge.com","threadId":"47384","inReplyTo":null,"subject":"Documentation Breakage at 2.5.6","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2017-12-06T04:12:33Z","receivedAt":"2017-12-06T04:12:50Z","isPatch":false,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"Hi All,\n\nI'm trying to upgrade the NonStop port from 2.3.7 upward eventually to\n2.15.1 and hit a snag on documentation. The xmlto component is a bit new to\nme and I hit the following error:\n\n XMLTO git-remote-testgit.1\nxmlto: /home/git/git/Documentation/git-remote-testgit.xml does not validate\n(status 3)\nxmlto: Fix document syntax or use --skip-validation option\nI/O error : Attempt to load network entity\nhttp://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n/home/git/git/Documentation/git-remote-testgit.xml:2: warning: failed to\nload external entity\n\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\nD DocBook XML V4.5//EN\"\n\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n \n^\nI/O error : Attempt to load network entity\nhttp://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\nwarning: failed to load external entity\n\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\nvalidity error : Could not load the external subset\nhttp://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n\nThe -skip-validation option just takes me to a different problem validating\nvia sourceforge URL that appears not to exist anymore, although I had to\nmodify ./git/Documention/Makefile, which is vexing.\n\n XMLTO git-remote-testgit.1\nI/O error : Attempt to load network entity\nhttp://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\nwarning: failed to load external entity\n\"http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\"\ncompilation error: file /tmp/xmlto-xsl.ie6J8p line 4 element import\nxsl:import : unable to load\nhttp://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\nMakefile:328: recipe for target 'git-remote-testgit.1' failed\n\nAny advice on getting past this? It would be nice to get git help to working\nagain. An answer of \"you need to get past 2.5.6\" is ok too as long as I know\nwhere I'm going.\n\nThanks,\nRandall\n\n-- Brief whoami: NonStop&UNIX developer since approximately\nUNIX(421664400)/NonStop(211288444200000000) \n-- In my real life, I talk too much.\n\n\n\n"},{"id":"334242","messageId":"877eu0uvb2.fsf@evledraar.gmail.com","threadId":"47384","inReplyTo":"008d01d36e48$747cc130$5d764390$@nexbridge.com","subject":"Re: Documentation Breakage at 2.5.6","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2017-12-06T08:14:57Z","receivedAt":"2017-12-06T08:15:06Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Dec 06 2017, Randall S. Becker jotted:\n\n> Hi All,\n>\n> I'm trying to upgrade the NonStop port from 2.3.7 upward eventually to\n> 2.15.1 and hit a snag on documentation. The xmlto component is a bit new to\n> me and I hit the following error:\n>\n> XMLTO git-remote-testgit.1\n> xmlto: /home/git/git/Documentation/git-remote-testgit.xml does not validate\n> (status 3)\n> xmlto: Fix document syntax or use --skip-validation option\n> I/O error : Attempt to load network entity\n> http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n> /home/git/git/Documentation/git-remote-testgit.xml:2: warning: failed to\n> load external entity\n> \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n> D DocBook XML V4.5//EN\"\n> \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n>\n> ^\n> I/O error : Attempt to load network entity\n> http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n> warning: failed to load external entity\n> \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n> validity error : Could not load the external subset\n> http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n>\n> The -skip-validation option just takes me to a different problem validating\n> via sourceforge URL that appears not to exist anymore, although I had to\n> modify ./git/Documention/Makefile, which is vexing.\n>\n> XMLTO git-remote-testgit.1\n> I/O error : Attempt to load network entity\n> http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\n> warning: failed to load external entity\n> \"http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\"\n> compilation error: file /tmp/xmlto-xsl.ie6J8p line 4 element import\n> xsl:import : unable to load\n> http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\n> Makefile:328: recipe for target 'git-remote-testgit.1' failed\n>\n> Any advice on getting past this? It would be nice to get git help to working\n> again. An answer of \"you need to get past 2.5.6\" is ok too as long as I know\n> where I'm going.\n\nI don't know if this helps, but here with xmlto 0.0.28 on Debian if I\napply this the docs still build:\n\n diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl\n index 0f8ff07eca..332a65558d 100644\n --- a/Documentation/texi.xsl\n +++ b/Documentation/texi.xsl\n @@ -7,7 +7,7 @@\n \n + doctype-system=\"http://example.org/docbook/xml/4.5/docbookx.dtd\" />\n\nSo whatever's needing to remote fetch those resources doesn't seem to\ncause the same error for me.\n\n\n> -- Brief whoami: NonStop&UNIX developer since approximately\n> UNIX(421664400)/NonStop(211288444200000000)\n> -- In my real life, I talk too much.\n"},{"id":"334243","messageId":"20171206084833.GA9501@sigill.intra.peff.net","threadId":"47384","inReplyTo":"877eu0uvb2.fsf@evledraar.gmail.com","subject":"Re: Documentation Breakage at 2.5.6","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-12-06T08:48:33Z","receivedAt":"2017-12-06T08:48:41Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Dec 06, 2017 at 09:14:57AM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> > I'm trying to upgrade the NonStop port from 2.3.7 upward eventually to\n> > 2.15.1 and hit a snag on documentation. The xmlto component is a bit new to\n> > me and I hit the following error:\n\nDid it work before in v2.3.7? If so, can you bisect to the breakage?\n\n> > XMLTO git-remote-testgit.1\n> > xmlto: /home/git/git/Documentation/git-remote-testgit.xml does not validate\n> > (status 3)\n> > xmlto: Fix document syntax or use --skip-validation option\n> > I/O error : Attempt to load network entity\n> > http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n> > /home/git/git/Documentation/git-remote-testgit.xml:2: warning: failed to\n> > load external entity\n> > \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n> > D DocBook XML V4.5//EN\"\n> > \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n> >\n> > ^\n> > I/O error : Attempt to load network entity\n> > http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n> > warning: failed to load external entity\n> > \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"\n> > validity error : Could not load the external subset\n> > http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\n\nThose URLs are the \"official\" names of the docbook DTDs. But normally\nyou'd have a local copy, along with a mapping from the official name to\nyour local copy. The XML term for that mapping is a \"catalog\", and it\nlooks something like this:\n\n $ grep oasis-open /etc/xml/catalog\n \n\nThat just points to another local catalog, which has:\n\n $ grep 4.5/docbookx.dtd /etc/xml/docbook-xml.xml\n \n \n\nSo my guess is that your problem is one of:\n\n 1. You don't have docbook 4.5 installed on your system.\n\nor\n\n 2. You don't have a correctly built catalog file, or xmlto isn't\n pointing to it for some reason (on Debian, this is normally built\n by the post-install script of packages that contain xml).\n\nAnd xmlto (actually, probably xsltproc that it's calling) is unwilling\nor unable to hit the network to pull down those entities.\n\nThose are all somewhat vague guesses based on past troubles I've had\nwith broken xml setups. I'm far from an expert on xml processing (and\nI'd just as soon keep it that way).\n\n> I don't know if this helps, but here with xmlto 0.0.28 on Debian if I\n> apply this the docs still build:\n> \n> diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl\n> index 0f8ff07eca..332a65558d 100644\n> --- a/Documentation/texi.xsl\n> +++ b/Documentation/texi.xsl\n> @@ -7,7 +7,7 @@\n> encoding=\"UTF-8\"\n> doctype-public=\"-//OASIS//DTD DocBook XML V4.5//EN\"\n> - doctype-system=\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\" />\n> + doctype-system=\"http://example.org/docbook/xml/4.5/docbookx.dtd\" />\n> \n> So whatever's needing to remote fetch those resources doesn't seem to\n> cause the same error for me.\n\nI think that would come into play only if you try to build\n\"gitman.info\", which isn't one of the default targets.\n\nThe string that Randall is seeing is in git-remote-testgit.xml, so it's\nprobably be generated by the \"docbook\" backend of asciidoc.\n\nOne alternative is to try to avoid docbook entirely. The only way to get\nmanpages with asciidoc is to generate docbook and then process it, but:\n\n - you can generate HTML directly (and \"make -C Documentation html\" does\n this). Perhaps not as nice, but you still at least have some\n documentation.\n\n - asciidoctor can generate manpages directly. I don't think our\n Makefile supports that now, but it might not be too hard to hack in\n (we already have some basic asciidoctor support). I'm not sure how\n hard it would be to get Ruby running on NonStop\n\nAnd of course one final option is to generate the manpages elsewhere and\ncopy them in, since they're platform-independent. In fact, that's what\nquick-install-man should do (you just have to clone Junio's git-manpages\nrepository -- see the INSTALL file).\n\n-Peff\n"},{"id":"334250","messageId":"002601d36ea8$ea80b160$bf821420$@nexbridge.com","threadId":"47384","inReplyTo":"20171206084833.GA9501@sigill.intra.peff.net","subject":"RE: Documentation Breakage at 2.5.6","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2017-12-06T15:43:03Z","receivedAt":"2017-12-06T15:43:20Z","isPatch":false,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"-----Original Message-----\nOn December 6, 2017 3:49 AM, Jeff King wrote:\n>On Wed, Dec 06, 2017 at 09:14:57AM +0100, Ævar Arnfjörð Bjarmason wrote:\n>> > I'm trying to upgrade the NonStop port from 2.3.7 upward eventually \n>> > to\n>> > 2.15.1 and hit a snag on documentation. The xmlto component is a bit \n>> > new to me and I hit the following error:\n>Did it work before in v2.3.7? If so, can you bisect to the breakage?\nIt worked fine at 2.3.7. No seeming dependency on docbook at that point - it was never on my system.\n\n>One alternative is to try to avoid docbook entirely. The only way to get manpages with asciidoc is to generate docbook and then process it, but:\nI have asciidoc installed, but using it via Make?\n\n> - you can generate HTML directly (and \"make -C Documentation html\" does\n> this). Perhaps not as nice, but you still at least have some\n> documentation.\nNot an option. I need git help to work.\n\n> - asciidoctor can generate manpages directly. I don't think our\n> Makefile supports that now, but it might not be too hard to hack in\n> (we already have some basic asciidoctor support). I'm not sure how\n > hard it would be to get Ruby running on NonStop\nRuby runs fine. I'm a bit out of my configuration depth here.\n\n>And of course one final option is to generate the manpages elsewhere and copy them in, since they're platform-independent.\n>In fact, that's what quick-install-man should do (you just have to clone Junio's >git-manpages repository -- see the INSTALL file).\n\nI've gone down this path and it works. Much cleaner in fact. Dependencies of docbook (jade) are too reliant on GCC C++ forms to port to the platform - not to mention being SVN, which is culturally uncomfortable 😉\n\nOne request to Junio: Would it be possible to tag the commits to align with the tags in the main repo? That way, I can build a nice little Jenkins job to automatically fetch the correct commit for man pages when packaging up a release.\n\n-Peff\n\n"},{"id":"334510","messageId":"xmqq4lp07t1k.fsf@gitster.mtv.corp.google.com","threadId":"47384","inReplyTo":"002601d36ea8$ea80b160$bf821420$@nexbridge.com","subject":"Re: Documentation Breakage at 2.5.6","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-12-08T22:29:11Z","receivedAt":"2017-12-08T22:29:19Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Randall S. Becker\" writes:\n\n> One request to Junio: Would it be possible to tag the commits to\n> align with the tags in the main repo? That way, I can build a nice\n> little Jenkins job to automatically fetch the correct commit for\n> man pages when packaging up a release.\n\nSorry, I missed this due to an overlong line in the message.\n\nI am not interested in doing anything more than absolute minimum in\nthe history that records generated cruft. We already describe the\nmainline commit object names in the messages; perhaps that is\nsufficient?\n\n commit daa88a54a985ed1ef258800c742223c2a8f0caaa\n Author: Junio C Hamano \n Date: Wed Dec 6 10:04:03 2017 -0800\n\n Autogenerated manpages for v2.15.1-354-g95ec6\n\n commit 466a3070abecf4081a12d8e07c770689506440b9\n Author: Junio C Hamano \n Date: Wed Nov 29 10:12:49 2017 +0900\n\n Autogenerated manpages for v2.15.1-271-g1a4e4\n\n commit be681f4100647ab93fd19cb5066fcaa2cb79204b\n Author: Junio C Hamano \n Date: Mon Nov 27 12:33:30 2017 +0900\n\n Autogenerated manpages for v2.15.0-374-g5f995\n\nThe primary reason why I do not want to tag them is because the tree\nthe documentation sources were taken from is *not* the only thing\nthat affects these autogenerated cruft. The AsciiDoc toolchain that\nhappen to be installed on the box the day I ran the documentation\ntools is an obvious difference, and I do not want to make them\nappear any more definitive and official. \"This is *the* manpage for\nrelease v2.15.1\" is the message I do not want to give.\n"},{"id":"334517","messageId":"003301d37076$846d3e00$8d47ba00$@nexbridge.com","threadId":"47384","inReplyTo":"xmqq4lp07t1k.fsf@gitster.mtv.corp.google.com","subject":"RE: Documentation Breakage at 2.5.6","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2017-12-08T22:47:19Z","receivedAt":"2017-12-08T22:47:36Z","isPatch":false,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"-----Original Message-----\nOn December 8, 2017 5:29 PM Junio C Hamano wrote:\n>\"Randall S. Becker\" writes:\n>> One request to Junio: Would it be possible to tag the commits to align \n>> with the tags in the main repo? That way, I can build a nice little \n>> Jenkins job to automatically fetch the correct commit for man pages \n>> when packaging up a release.\n>I am not interested in doing anything more than absolute minimum in the history that records generated cruft. We already describe the mainline commit object names in the messages; perhaps that is >sufficient?\n> commit daa88a54a985ed1ef258800c742223c2a8f0caaa\n> Author: Junio C Hamano \n> Date: Wed Dec 6 10:04:03 2017 -0800\n>\n> Autogenerated manpages for v2.15.1-354-g95ec6\n>The primary reason why I do not want to tag them is because the tree the documentation sources were taken from is *not* the only thing that affects these autogenerated cruft. The AsciiDoc toolchain that >happen to be installed on the box the day I ran the documentation tools is an obvious difference, and I do not want to make them appear any more definitive and official. \"This is *the* manpage for release >v2.15.1\" is the message I do not want to give.\n\nNo worries. I will push on with trying to get asciidoc to build so that I can generate the man pages. That probably won't happen soon, so I'll keep MacGyvering. I do get generating is the better solution, but I would rather focus my own efforts on keeping up with git (that ports fairly easily and is essential to work life) than burning off $DAYJOB hours on asciidoc and/or xmlto.\n\nCheers,\nRandall\n\n\n"}]}