# manpage name conflict 10 messages from 2005-05-19 to 2005-05-20. Participants: Sebastian Kuzminsky, Petr Baudis, Linus Torvalds, Jonas Fonseca, Raja R Harinath. Thread: https://gitlist.dev/t/664 ## Sebastian Kuzminsky, 2005-05-19 15:29 Subject: manpage name conflict Message-ID: URL: https://gitlist.dev/e/E1DYmy8-0003YB-JW%40highlab.com ``` Hi folks, I maintain a Debian package for Cogito (it just went into "Sid" aka "unstable"), and I just got a bug report from a user that I'd like your input on. The problem is that Cogito wants to install a git(1) manpage, and so does the GNU Interactive Tools. The GNU Interactive Tools actually have a program called "git", so it seems only fair that they get to call their manpage by the same name. The GIT-as-in-Cogito git(1) manpage gives an overview of the GIT-as-in-Cogito core, so maybe we could install it as git-core(1)? What do you think? -- Sebastian Kuzminsky "Marie will know I'm headed south, so's to meet me by and by" -Townes Van Zandt ``` ## Petr Baudis, 2005-05-19 15:58 Subject: Re: manpage name conflict Message-ID: <20050519155804.GB4513@pasky.ji.cz> URL: https://gitlist.dev/e/20050519155804.GB4513%40pasky.ji.cz In-Reply-To: ``` Dear diary, on Thu, May 19, 2005 at 05:29:52PM CEST, I got a letter where Sebastian Kuzminsky told me that... > Hi folks, I maintain a Debian package for Cogito (it just went into "Sid" > aka "unstable"), and I just got a bug report from a user that I'd like > your input on. > > > The problem is that Cogito wants to install a git(1) manpage, and so does > the GNU Interactive Tools. The GNU Interactive Tools actually have a > program called "git", so it seems only fair that they get to call their > manpage by the same name. The GIT-as-in-Cogito git(1) manpage gives > an overview of the GIT-as-in-Cogito core, so maybe we could install it > as git-core(1)? Does this manpage actually belong to man1? What about git(7) or something? It's not an actual command. Not directly related to this problem, but just FYI - git isn't staying as part of Cogito forever, actually I think its time in Cogito distribution is running over soon (now that I've pushed all the interesting local changes to git-pb, consequently to git-linus). So you will have to either bundle it manually in the distribution packages, or provide a separate git package for cogito to depend on (when the unbundling really happens). Either way, this is git issue, not cogito. :-) -- Petr "Pasky" Baudis Stuff: http://pasky.or.cz/ C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor ``` ## Sebastian Kuzminsky, 2005-05-19 16:24 Subject: Re: manpage name conflict Message-ID: URL: https://gitlist.dev/e/E1DYnpO-0003cF-I6%40highlab.com In-Reply-To: <20050519155804.GB4513@pasky.ji.cz> ``` Petr Baudis wrote: > Does this manpage actually belong to man1? What about git(7) or > something? It's not an actual command. Good point. Ok, I've appended a patch (against the top of git-pb) that moves the git manpage to man7. It also does two other things: * Sort of works around the asciidoc 6.0.3 bug where the manpages all get called "git.1". It just renames them to what they should have been called. * Fixes a cut-n-paste bug in git-diff-helper.txt that was making asciidoc choke. > Not directly related to this problem, but just FYI - git isn't staying > as part of Cogito forever, actually I think its time in Cogito > distribution is running over soon (now that I've pushed all the interesting > local changes to git-pb, consequently to git-linus). > > So you will have to either bundle it manually in the distribution > packages, or provide a separate git package for cogito to depend on > (when the unbundling really happens). Either way, this is git issue, > not cogito. :-) Right. Hm. It's no problem to have git be it's own separate package with all the appropriate relationships (cogito Requires git, and git suggests cogito). But what is going to be the name of the git package? Let's please not make it "git", because that's taken by the GNU Interactive Tools. How about "git-core" or "git-plumbing" or "linus-is-a-git"? ;) Anyway, here's the documentation patch: Index: Documentation/Makefile =================================================================== --- 75b95bec390d6728b9b1b4572056af8cee34ea7d/Documentation/Makefile (mode:100644) +++ uncommitted/Documentation/Makefile (mode:100644) @@ -1,6 +1,6 @@ DOC_SRC=$(wildcard git*.txt) DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC)) -DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC)) +DOC_MAN=$(patsubst %.txt,%.1,$(wildcard git-*.txt)) git.7 all: $(DOC_HTML) $(DOC_MAN) @@ -13,13 +13,15 @@ touch $@ clean: - rm -f *.xml *.html *.1 + rm -f *.xml *.html *.1 *.7 %.html : %.txt asciidoc -b css-embedded -d manpage $< -%.1 : %.xml +%.1 %.7 : %.xml xmlto man $< + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 + [ "$@" = "git.7" ] || mv git.1 $@ %.xml : %.txt asciidoc -b docbook -d manpage $< Index: Documentation/git-diff-helper.txt =================================================================== --- 75b95bec390d6728b9b1b4572056af8cee34ea7d/Documentation/git-diff-helper.txt (mode:100644) +++ uncommitted/Documentation/git-diff-helper.txt (mode:100644) @@ -1,5 +1,5 @@ git-diff-helper(1) -======================= +================== v0.1, May 2005 NAME Index: Documentation/git.txt =================================================================== --- 75b95bec390d6728b9b1b4572056af8cee34ea7d/Documentation/git.txt (mode:100644) +++ uncommitted/Documentation/git.txt (mode:100644) @@ -1,4 +1,4 @@ -git(1) +git(7) ====== v0.1, May 2005 -- Sebastian Kuzminsky "Marie will know I'm headed south, so's to meet me by and by" -Townes Van Zandt ``` ## Linus Torvalds, 2005-05-19 16:47 Subject: Re: manpage name conflict Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.58.0505190945440.2322%40ppc970.osdl.org In-Reply-To: ``` On Thu, 19 May 2005, Sebastian Kuzminsky wrote: > > But what is going to be the name of the git package? Let's please > not make it "git", because that's taken by the GNU Interactive Tools. > How about "git-core" or "git-plumbing" or "linus-is-a-git"? "git-core" sounds good to me. I don't mind "linus-is-a-git" either, but I suspect it would end up confusing people if the git packages are installed with something that starts with "linus-" Linus ``` ## Linus Torvalds, 2005-05-19 16:57 Subject: Re: manpage name conflict Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.58.0505190956330.2322%40ppc970.osdl.org In-Reply-To: ``` On Thu, 19 May 2005, Sebastian Kuzminsky wrote: > > Anyway, here's the documentation patch: It's whitespace-corrupted, with tabs turned into spaces.. Linus ``` ## Sebastian Kuzminsky, 2005-05-19 18:18 Subject: Re: manpage name conflict Message-ID: URL: https://gitlist.dev/e/E1DYpbT-0003jv-JY%40highlab.com In-Reply-To: ``` Linus Torvalds wrote: > On Thu, 19 May 2005, Sebastian Kuzminsky wrote: > > Anyway, here's the documentation patch: > > It's whitespace-corrupted, with tabs turned into spaces.. Index: Documentation/Makefile =================================================================== --- 75b95bec390d6728b9b1b4572056af8cee34ea7d/Documentation/Makefile (mode:100644) +++ uncommitted/Documentation/Makefile (mode:100644) @@ -1,6 +1,6 @@ DOC_SRC=$(wildcard git*.txt) DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC)) -DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC)) +DOC_MAN=$(patsubst %.txt,%.1,$(wildcard git-*.txt)) git.7 all: $(DOC_HTML) $(DOC_MAN) @@ -13,13 +13,15 @@ touch $@ clean: - rm -f *.xml *.html *.1 + rm -f *.xml *.html *.1 *.7 %.html : %.txt asciidoc -b css-embedded -d manpage $< -%.1 : %.xml +%.1 %.7 : %.xml xmlto man $< + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 + [ "$@" = "git.7" ] || mv git.1 $@ %.xml : %.txt asciidoc -b docbook -d manpage $< Index: Documentation/git-diff-helper.txt =================================================================== --- 75b95bec390d6728b9b1b4572056af8cee34ea7d/Documentation/git-diff-helper.txt (mode:100644) +++ uncommitted/Documentation/git-diff-helper.txt (mode:100644) @@ -1,5 +1,5 @@ git-diff-helper(1) -======================= +================== v0.1, May 2005 NAME Index: Documentation/git.txt =================================================================== --- 75b95bec390d6728b9b1b4572056af8cee34ea7d/Documentation/git.txt (mode:100644) +++ uncommitted/Documentation/git.txt (mode:100644) @@ -1,4 +1,4 @@ -git(1) +git(7) ====== v0.1, May 2005 -- Sebastian Kuzminsky "Marie will know I'm headed south, so's to meet me by and by" -Townes Van Zandt ``` ## Jonas Fonseca, 2005-05-20 13:35 Subject: [PATCH] Fix and clean up man page building Message-ID: <20050520133533.GA27395@diku.dk> URL: https://gitlist.dev/e/20050520133533.GA27395%40diku.dk In-Reply-To: ``` Sebastian Kuzminsky wrote Thu, May 19, 2005: > -%.1 : %.xml > +%.1 %.7 : %.xml > xmlto man $< > + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > + [ "$@" = "git.7" ] || mv git.1 $@ > > %.xml : %.txt > asciidoc -b docbook -d manpage $< This doesn't work for me since make stops when the test fails. Besides it is a bit verbose. Following is a patch which will only check for moving when building .7 files. It also cleans up the Makefile so it will be easier to add the manpages for cogito. Signed-off-by: Jonas Fonseca --- f435f47dab3465a47fbd2114cf006e0e869f31a9/Documentation/Makefile (mode:100644) +++ uncommitted/Documentation/Makefile (mode:100644) @@ -1,6 +1,7 @@ -DOC_SRC=$(wildcard git*.txt) -DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC)) -DOC_MAN=$(patsubst %.txt,%.1,$(wildcard git-*.txt)) git.7 +MAN1_TXT=$(wildcard git-*.txt) +MAN7_TXT=git.txt +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) +DOC_MAN=$(patsubst %.txt,%.1,$(MAN1_TXT)) $(patsubst %.txt,%.7,$(MAN7_TXT)) all: $(DOC_HTML) $(DOC_MAN) @@ -18,10 +19,12 @@ %.html : %.txt asciidoc -b css-embedded -d manpage $< +%.7 : %.1 + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 + if [ -f "$<" ]; then mv $< $@; fi + %.1 %.7 : %.xml xmlto man $< - # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 - [ "$@" = "git.7" ] || mv git.1 $@ %.xml : %.txt asciidoc -b docbook -d manpage $< -- Jonas Fonseca ``` ## Raja R Harinath, 2005-05-20 14:08 Subject: Re: [PATCH] Fix and clean up man page building Message-ID: URL: https://gitlist.dev/e/m37jhu56ta.fsf%40harinath.blr.novell.com In-Reply-To: <20050520133533.GA27395@diku.dk> ``` Hi, Jonas Fonseca writes: > +%.7 : %.1 > + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > + if [ -f "$<" ]; then mv $< $@; fi > + > %.1 %.7 : %.xml > xmlto man $< > - # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > - [ "$@" = "git.7" ] || mv git.1 $@ > > %.xml : %.txt > asciidoc -b docbook -d manpage $< That doesn't look right. I think you want %.7: %.xml xmlto man %< %.1: %.xml xmlto man $< [ test -f $@ ] || mv git.1 $@ - Hari ``` ## Jonas Fonseca, 2005-05-20 14:52 Subject: Re: [PATCH] Fix and clean up man page building Message-ID: <20050520145211.GB27395@diku.dk> URL: https://gitlist.dev/e/20050520145211.GB27395%40diku.dk In-Reply-To: ``` Raja R Harinath wrote Fri, May 20, 2005: > Hi, > > Jonas Fonseca writes: > > > +%.7 : %.1 > > + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > > + if [ -f "$<" ]; then mv $< $@; fi > > + > > %.1 %.7 : %.xml > > xmlto man $< > > - # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > > - [ "$@" = "git.7" ] || mv git.1 $@ > > > > %.xml : %.txt > > asciidoc -b docbook -d manpage $< > > That doesn't look right. I think you want > > %.7: %.xml > xmlto man %< > > %.1: %.xml > xmlto man $< > [ test -f $@ ] || mv git.1 $@ [ Looks like you mixed up %.1 and %.7 ] Yes, separating the rule for %.1 and %.7 might be clearer. But it would be great if it would work for any man page in section 7 not just git.7. Since I hope to add cogito.7 soon. -- Jonas Fonseca ``` ## Sebastian Kuzminsky, 2005-05-20 17:09 Subject: Re: [PATCH] Fix and clean up man page building Message-ID: URL: https://gitlist.dev/e/E1DZB0X-0004qW-QX%40highlab.com In-Reply-To: <20050520145211.GB27395@diku.dk> ``` Jonas Fonseca wrote: > Raja R Harinath wrote Fri, May 20, 2005: > > Jonas Fonseca writes: > > > +%.7 : %.1 > > > + # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > > > + if [ -f "$<" ]; then mv $< $@; fi > > > + > > > %.1 %.7 : %.xml > > > xmlto man $< > > > - # FIXME: this next line works around an output filename bug in asciidoc 6.0.3 > > > - [ "$@" = "git.7" ] || mv git.1 $@ > > > > > > %.xml : %.txt > > > asciidoc -b docbook -d manpage $< > > > > That doesn't look right. I think you want > > > > %.7: %.xml > > xmlto man %< > > > > %.1: %.xml > > xmlto man $< > > [ test -f $@ ] || mv git.1 $@ > > [ Looks like you mixed up %.1 and %.7 ] > > Yes, separating the rule for %.1 and %.7 might be clearer. But it would > be great if it would work for any man page in section 7 not just git.7. > Since I hope to add cogito.7 soon. That's still not right. Jonas' %.7 target works (as long as none of the %.7 source files have dashes in the name), but the %.1 target fails to rebuild the manpages if they already exist. The underlying problem, just so we're all clear, is that asciidoc 6.0.3 has a bug that causes it to output buggy xml files when the command-name has a dash in it. When there's a dash in the command-name, asciidoc produces xml that says everything _before_ the first dash is the command name, and everything _after_ the first dash is the quick description ("purpose") of that command. The git.txt -> git.xml transition is fine since there is no dash in "git", but (for example) the git-cat-file.txt -> git-cat-file.xml transition tickles the bug. git-cat-file.xml thinks it's documenting a program called "git", with the quick description beginning with "cat-file". Here's the relevant snippet from git-cat-file.xml: git cat-file - Provide content or type information for repository objects So far it's not too bad (it's still getting the filename right, even though the contents are less than perfect). But when we feed that xml to 'xmlto man', xmlto sensibly uses the buggy command name "git" for the output file name, producing "git.1". _That_ is what we have to move. (xmlto has no --output-filename option, or we'd just use that.) Here's another attempt at the Makefile patch. It's got the broken-out man1 vs man7 layout that Jonas sensibly suggested. Note that the asciidoc bug workaround is incredibly fragile. If we have any man1 pages that don't begin with "git-", it'll do the wrong thing (because they won't be named git.1). And if we have any man7 pages that have "-" in the name, it'll do the wrong thing (by not renaming the incorrectly named manpage). Please please Stuart Rackham, Mr Asciidoc man, use David Greaves' patch to fix this bug. Index: Documentation/Makefile =================================================================== --- a81ef956b9b2946bea2104cd11a4529c965976ad/Documentation/Makefile (mode:100644) +++ uncommitted/Documentation/Makefile (mode:100644) @@ -1,25 +1,40 @@ -DOC_SRC=$(wildcard git*.txt) -DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC)) -DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC)) +MAN1_TXT=$(wildcard git-*.txt) +MAN7_TXT=git.txt -all: $(DOC_HTML) $(DOC_MAN) +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) + +DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) +DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) + + +all: html man html: $(DOC_HTML) -man: $(DOC_MAN) +man: man1 man7 + +man1: $(DOC_MAN1) + +man7: $(DOC_MAN7) + # 'include' dependencies git-diff-%.txt: diff-format.txt touch $@ clean: - rm -f *.xml *.html *.1 + rm -f *.xml *.html *.1 *.7 %.html : %.txt asciidoc -b css-embedded -d manpage $< %.1 : %.xml xmlto man $< + @# FIXME: this next line works around an output filename bug in asciidoc 6.0.3 + mv git.1 $@ + +%.7 : %.xml + xmlto man $< %.xml : %.txt asciidoc -b docbook -d manpage $< -- Sebastian Kuzminsky "Marie will know I'm headed south, so's to meet me by and by" -Townes Van Zandt ```