{"thread":{"id":"10902","subject":"[PATCH] Documentation: fix git-clone manpage not to refer to itself","startedAt":"2007-11-16T18:43:16Z","lastAt":"2007-11-20T11:28:11Z","messageCount":6,"participants":["Sergei Organov","Johannes Schindelin","Jakub Narebski","Wincent Colaiuta"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"60103","messageId":"87ejeq1131.fsf@osv.gnss.ru","threadId":"10902","inReplyTo":null,"subject":"[PATCH] Documentation: fix git-clone manpage not to refer to itself","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-11-16T18:43:16Z","receivedAt":"2007-11-16T18:43:16Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"\nSigned-off-by: Sergei Organov \n---\n Documentation/git-clone.txt | 1 +\n Documentation/urls.txt | 6 ++++++\n 2 files changed, 7 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 14e58f3..c90bcec 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -130,6 +130,7 @@ OPTIONS\n \tfor \"host.xz:foo/.git\"). Cloning into an existing directory\n \tis not allowed.\n \n+:git-clone: 1\n include::urls.txt[]\n \n Examples\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex e67f914..4f66738 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -36,5 +36,11 @@ To sync with a local directory, you can use:\n - file:///path/to/repo.git/\n ===============================================================\n \n+ifndef::git-clone[]\n They are mostly equivalent, except when cloning. See\n gitlink:git-clone[1] for details.\n+endif::git-clone[]\n+\n+ifdef::git-clone[]\n+They are equivalent, except the former implies --local option.\n+endif::git-clone[]\n-- \n1.5.3.4\n"},{"id":"60305","messageId":"Pine.LNX.4.64.0711191430460.16728@wbgn129.biozentrum.uni-wuerzburg.de","threadId":"10902","inReplyTo":"87ejeq1131.fsf@osv.gnss.ru","subject":"Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-19T13:35:43Z","receivedAt":"2007-11-19T13:35:43Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Fri, 16 Nov 2007, Sergei Organov wrote:\n\n> +ifndef::git-clone[]\n\nIt is laudable that you want to fix the _generated_ documentation, but \nthere are two things to keep in mind:\n\n- it does _nothing_ to help readers of the sources, and asciidoc was \n chosen purposely because the source is human-readable, and\n\n- it makes writing the perl script to do a very tiny subset of asciidoc \n formatting much harder. We encounter enough problems with the different \n versions of asciidoc/docbook combinations that I think this perl script \n would be actually useful.\n\nI know that the user manual uses some advanced features, too, but it did \nnot use ifdef in the main text, for example, let alone nested ifdefs, \nwhich your patch would encourage much more than the source before.\n\nCiao,\nDscho\n"},{"id":"60309","messageId":"fhs52j$npp$1@ger.gmane.org","threadId":"10902","inReplyTo":"Pine.LNX.4.64.0711191430460.16728@wbgn129.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-19T14:03:00Z","receivedAt":"2007-11-19T14:03:00Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Johannes Schindelin wrote:\n\n> On Fri, 16 Nov 2007, Sergei Organov wrote:\n> \n>> +ifndef::git-clone[]\n> \n> It is laudable that you want to fix the _generated_ documentation, but \n> there are two things to keep in mind:\n> \n> - it does _nothing_ to help readers of the sources, and asciidoc was \n>   chosen purposely because the source is human-readable, and\n\nIMHO it doesn't make source of documentation less readable.\n\nIt has the advantage of not duplicating contents, and being a bit mre\nreadable than writing \"for \" in documentation contents.\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"60352","messageId":"87mytayrgu.fsf@osv.gnss.ru","threadId":"10902","inReplyTo":"Pine.LNX.4.64.0711191430460.16728@wbgn129.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-11-19T19:18:09Z","receivedAt":"2007-11-19T19:18:09Z","isPatch":true,"sender":{"key":"osv@javad.com","avatar":null},"body":"Johannes Schindelin writes:\n> Hi,\n>\n> On Fri, 16 Nov 2007, Sergei Organov wrote:\n>\n>> +ifndef::git-clone[]\n>\n> It is laudable that you want to fix the _generated_ documentation, but \n> there are two things to keep in mind:\n>\n> - it does _nothing_ to help readers of the sources, and asciidoc was \n> chosen purposely because the source is human-readable, and\n\nI wonder if C sources are human-readable? No #ifdefs whatsoever? ;)\n\nAnd please notice that asciidoc is much worse than C preprocessor in\nthis regard :(\n\n>\n> - it makes writing the perl script to do a very tiny subset of asciidoc \n> formatting much harder. We encounter enough problems with the different \n> versions of asciidoc/docbook combinations that I think this perl script \n> would be actually useful.\n>\n> I know that the user manual uses some advanced features, too, but it did \n> not use ifdef in the main text, for example, let alone nested ifdefs, \n> which your patch would encourage much more than the source before.\n\nUnfortunately I don't see better solution than using ifdef in this\nparticular case, though I'm open for suggestions.\n\nWhat I really do care about is the quality of the documentation that\nuser reads. For example, when the first option of git-format-*patch*\ndescribed in the manual is \"-p Generate *patch*...\", well..., what does\nit generate without -p???\n\n-- \nSergei.\n"},{"id":"60399","messageId":"3FC9A391-AED0-4988-B1F7-EE5C06AD1137@wincent.com","threadId":"10902","inReplyTo":"Pine.LNX.4.64.0711191430460.16728@wbgn129.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-20T09:41:04Z","receivedAt":"2007-11-20T09:41:04Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 19/11/2007, a las 14:35, Johannes Schindelin escribió:\n\n> - it makes writing the perl script to do a very tiny subset of \n> asciidoc\n> formatting much harder. We encounter enough problems with the \n> different\n> versions of asciidoc/docbook combinations that I think this perl \n> script\n> would be actually useful.\n>\n> I know that the user manual uses some advanced features, too, but it \n> did\n> not use ifdef in the main text, for example, let alone nested ifdefs,\n> which your patch would encourage much more than the source before.\n\nOut of curiosity, have you done any more work on that WIP AsciiDoc \nreplacement since you last wrote to the list about it back in October?\n\nI'm on a new OS install now, so just yesterday and today I had to set \nup the AsciiDoc/DocBook/xmlto toolchain again, and was reminded of how \npainful it was. At least on Mac OS X, it requires installing a bunch \nof dependencies (and specific versions of them otherwise it won't \nwork), hacking Makefiles, installing a bunch of XSL and DTDs, and \nsetting up XML catalogs. Doable but annoying.\n\nCheers,\nWincent\n\n\n"},{"id":"60404","messageId":"Pine.LNX.4.64.0711201126430.27959@racer.site","threadId":"10902","inReplyTo":"3FC9A391-AED0-4988-B1F7-EE5C06AD1137@wincent.com","subject":"Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-20T11:28:11Z","receivedAt":"2007-11-20T11:28:11Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 20 Nov 2007, Wincent Colaiuta wrote:\n\n> El 19/11/2007, a las 14:35, Johannes Schindelin escribi?:\n> \n> > - it makes writing the perl script to do a very tiny subset of \n> > asciidoc formatting much harder. We encounter enough problems with \n> > the different versions of asciidoc/docbook combinations that I think \n> > this perl script would be actually useful.\n> > \n> > I know that the user manual uses some advanced features, too, but it \n> > did not use ifdef in the main text, for example, let alone nested \n> > ifdefs, which your patch would encourage much more than the source \n> > before.\n> \n> Out of curiosity, have you done any more work on that WIP AsciiDoc \n> replacement since you last wrote to the list about it back in October?\n\nYes. I rewrote it three times, and the third time is not finished, but \nslowed down to a glacial pace. You can see the continental shift at my \nrepository on repo.or.cz (it's the \"dscho\" fork of git.git).\n\nCiao,\nDscho\n"}]}