threads / patch / 10902

patchDocumentation: fix git-clone manpage not to refer to itself

Subject: [PATCH] Documentation: fix git-clone manpage not to refer to itself

## tl;dr

6 messages between Nov 16, 2007 and Nov 20, 2007. Diffs are folded; open one to read it.

replies: 5people: 4as markdown or json

Sergei Organov· Nov 16, 2007, 18:43 UTC · lore
Signed-off-by: Sergei Organov <osv@javad.com>
---
 Documentation/git-clone.txt |    1 +
 Documentation/urls.txt      |    6 ++++++
 2 files changed, 7 insertions(+), 0 deletions(-)
Show changes to 2 files +7 −0

Documentation/git-clone.txt, Documentation/urls.txt

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 14e58f3..c90bcec 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -130,6 +130,7 @@ OPTIONS
 	for "host.xz:foo/.git").  Cloning into an existing directory
 	is not allowed.
 
+:git-clone: 1
 include::urls.txt[]
 
 Examples
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index e67f914..4f66738 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -36,5 +36,11 @@ To sync with a local directory, you can use:
 - file:///path/to/repo.git/
 ===============================================================
 
+ifndef::git-clone[]
 They are mostly equivalent, except when cloning.  See
 gitlink:git-clone[1] for details.
+endif::git-clone[]
+
+ifdef::git-clone[]
+They are equivalent, except the former implies --local option.
+endif::git-clone[]

-- 
1.5.3.4
Johannes Schindelin· Nov 19, 2007, 13:35 UTC · re: Sergei Organov · lore

Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself

Hi,
On Fri, 16 Nov 2007, Sergei Organov wrote:
> +ifndef::git-clone[]

It is laudable that you want to fix the _generated_ documentation, but there are two things to keep in mind:

- it does _nothing_ to help readers of the sources, and asciidoc was 
  chosen purposely because the source is human-readable, and
- it makes writing the perl script to do a very tiny subset of asciidoc 
  formatting much harder.  We encounter enough problems with the different 
  versions of asciidoc/docbook combinations that I think this perl script 
  would be actually useful.

I know that the user manual uses some advanced features, too, but it did not use ifdef in the main text, for example, let alone nested ifdefs, which your patch would encourage much more than the source before.

Ciao, Dscho

Jakub Narebski· Nov 19, 2007, 14:03 UTC · re: Johannes Schindelin · lore

Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself

Johannes Schindelin wrote:
Show 9 quoted lines
> On Fri, 16 Nov 2007, Sergei Organov wrote:
> 
>> +ifndef::git-clone[]
> 
> It is laudable that you want to fix the _generated_ documentation, but 
> there are two things to keep in mind:
> 
> - it does _nothing_ to help readers of the sources, and asciidoc was 
>   chosen purposely because the source is human-readable, and
IMHO it doesn't make source of documentation less readable.

It has the advantage of not duplicating contents, and being a bit mre readable than writing "for <cmd>" in documentation contents.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Sergei Organov· Nov 19, 2007, 19:18 UTC · re: Johannes Schindelin · lore

Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
Show 11 quoted lines
> Hi,
>
> On Fri, 16 Nov 2007, Sergei Organov wrote:
>
>> +ifndef::git-clone[]
>
> It is laudable that you want to fix the _generated_ documentation, but 
> there are two things to keep in mind:
>
> - it does _nothing_ to help readers of the sources, and asciidoc was 
>   chosen purposely because the source is human-readable, and
I wonder if C sources are human-readable? No #ifdefs whatsoever? ;)

And please notice that asciidoc is much worse than C preprocessor in this regard :(

Show 9 quoted lines
>
> - it makes writing the perl script to do a very tiny subset of asciidoc 
>   formatting much harder.  We encounter enough problems with the different 
>   versions of asciidoc/docbook combinations that I think this perl script 
>   would be actually useful.
>
> I know that the user manual uses some advanced features, too, but it did 
> not use ifdef in the main text, for example, let alone nested ifdefs, 
> which your patch would encourage much more than the source before.

Unfortunately I don't see better solution than using ifdef in this particular case, though I'm open for suggestions.

What I really do care about is the quality of the documentation that user reads. For example, when the first option of git-format-*patch* described in the manual is "-p Generate *patch*...", well..., what does it generate without -p???

-- 
Sergei.
Wincent Colaiuta· Nov 20, 2007, 09:41 UTC · re: Johannes Schindelin · lore

Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself

El 19/11/2007, a las 14:35, Johannes Schindelin escribió:
Show 12 quoted lines
> - it makes writing the perl script to do a very tiny subset of  
> asciidoc
>  formatting much harder.  We encounter enough problems with the  
> different
>  versions of asciidoc/docbook combinations that I think this perl  
> script
>  would be actually useful.
>
> I know that the user manual uses some advanced features, too, but it  
> did
> not use ifdef in the main text, for example, let alone nested ifdefs,
> which your patch would encourage much more than the source before.

Out of curiosity, have you done any more work on that WIP AsciiDoc replacement since you last wrote to the list about it back in October?

I'm on a new OS install now, so just yesterday and today I had to set up the AsciiDoc/DocBook/xmlto toolchain again, and was reminded of how painful it was. At least on Mac OS X, it requires installing a bunch of dependencies (and specific versions of them otherwise it won't work), hacking Makefiles, installing a bunch of XSL and DTDs, and setting up XML catalogs. Doable but annoying.

Cheers, Wincent

Johannes Schindelin· Nov 20, 2007, 11:28 UTC · re: Wincent Colaiuta · lore

Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself

Hi,
On Tue, 20 Nov 2007, Wincent Colaiuta wrote:
Show 14 quoted lines
> El 19/11/2007, a las 14:35, Johannes Schindelin escribi?:
> 
> > - it makes writing the perl script to do a very tiny subset of 
> > asciidoc formatting much harder.  We encounter enough problems with 
> > the different versions of asciidoc/docbook combinations that I think 
> > this perl script would be actually useful.
> > 
> > I know that the user manual uses some advanced features, too, but it 
> > did not use ifdef in the main text, for example, let alone nested 
> > ifdefs, which your patch would encourage much more than the source 
> > before.
> 
> Out of curiosity, have you done any more work on that WIP AsciiDoc 
> replacement since you last wrote to the list about it back in October?

Yes. I rewrote it three times, and the third time is not finished, but slowed down to a glacial pace. You can see the continental shift at my repository on repo.or.cz (it's the "dscho" fork of git.git).

Ciao, Dscho

← back to recent threads