Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Fri, Feb 01, 2013 at 02:33:52AM -0500, Jeff King wrote: I am starting to think it has grown in an unnecessarily complex direction, and we would be much happier just calling all of the concept documentation git-. The steps I see are: I am still undecided on whether it is a good idea (in some ways, I like that gitrevisions signals to the user that it is not a command; but I also recognize that it is more complex for users, and gitremote-helpers looks silly to me). But here is what the patch looks like, for reference. The first one is a cleanup we might want to take anyway, and the second one is the meat. [1/2]: Documentation/Makefile: clean up MAN*_TXT lists [2/2]: docs: convert concept manpages to git-* -Peff -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Jeff King p...@peff.net writes: Right. So we have some that must be gitfoo, and others that do not care. If we turned githooks into git-hooks and removed the is it a command? magic from git help, then git help hooks would still find hooks. And likewise, git help gitignore would still find gitignore. But you could no longer say git help ignore to find gitignore. Which I think is a good thing ;-) Which personally I am OK with. It is not a sensible thing to ask for; the concept is not ignore, but rather the gitignore file. Yes, exactly. 4. Replace the rename gitfoo above with a see git-foo... pointer. Users of git help foo would not ever see this, but people who have trained their fingers to type man gitfoo would, along with anybody following an outdated HTML link. 5. Update internal references to linkgit:gitfoo to point to git-foo. Hmm. That really does not seem so bad. The biggest downside is the people who have to see the redirect made in step 4. Yeah, I see that a show-stopper in the whole sequence. This is one of the if we had perfect knowledge we would have designed it this way, and we could still migrate our current system to that ideal, but it is dubious the difference between the current system and the ideal will outweigh the cost of migration moment, isn't it? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Fri, Feb 01, 2013 at 10:52:52AM -0800, Junio C Hamano wrote: 4. Replace the rename gitfoo above with a see git-foo... pointer. Users of git help foo would not ever see this, but people who have trained their fingers to type man gitfoo would, along with anybody following an outdated HTML link. 5. Update internal references to linkgit:gitfoo to point to git-foo. Hmm. That really does not seem so bad. The biggest downside is the people who have to see the redirect made in step 4. Yeah, I see that a show-stopper in the whole sequence. This is one of the if we had perfect knowledge we would have designed it this way, and we could still migrate our current system to that ideal, but it is dubious the difference between the current system and the ideal will outweigh the cost of migration moment, isn't it? Yeah, perhaps. I did the patch series just to see what the effort would be like. But at this point I am fine if we drop it (it sounded like Jonathan was in favor of this direction, so maybe he wants to make a final argument). -Peff -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Jeff King p...@peff.net writes: On Fri, Feb 01, 2013 at 10:52:52AM -0800, Junio C Hamano wrote: 4. Replace the rename gitfoo above with a see git-foo... pointer. Users of git help foo would not ever see this, but people who have trained their fingers to type man gitfoo would, along with anybody following an outdated HTML link. 5. Update internal references to linkgit:gitfoo to point to git-foo. Hmm. That really does not seem so bad. The biggest downside is the people who have to see the redirect made in step 4. Yeah, I see that a show-stopper in the whole sequence. This is one of the if we had perfect knowledge we would have designed it this way, and we could still migrate our current system to that ideal, but it is dubious the difference between the current system and the ideal will outweigh the cost of migration moment, isn't it? Yeah, perhaps. I did the patch series just to see what the effort would be like. But at this point I am fine if we drop it (it sounded like Jonathan was in favor of this direction, so maybe he wants to make a final argument). OK. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
John Keeping j...@keeping.me.uk writes:
When looking up a topic via git help topic, git-help prepends git-
to topics that are the names of commands (either builtin or found on the
path) and git (no hyphen) to any other topic name.
git-remote-helpers is not the name of a command, so git help
remote-helpers looks for gitremote-helpers and does not find it.
Fix this by renaming git-remote-helpers.txt to
gitremote-helpers.txt.
Signed-off-by: John Keeping j...@keeping.me.uk
---
Changes since v1:
- add gitremote-helpers.txt to the Makefile since it is no longer caught
by git-*.txt.
- add a simple git-remote-helpers.html to help people following links to
the old name.
Doesn't make clean remove the placeholder file?
Documentation/.gitignore | 1 +
Documentation/Makefile | 4 +-
Documentation/git-remote-helpers.html | 55
++
Documentation/git-remote-testgit.txt | 2 +-
...it-remote-helpers.txt = gitremote-helpers.txt} | 6 +--
Documentation/urls.txt | 2 +-
6 files changed, 63 insertions(+), 7 deletions(-)
create mode 100644 Documentation/git-remote-helpers.html
rename Documentation/{git-remote-helpers.txt = gitremote-helpers.txt} (99%)
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 2c8b2d6..5f479b8 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -1,5 +1,6 @@
*.xml
*.html
+!git-remote-helpers.html
*.[1-8]
*.made
*.texi
diff --git a/Documentation/Makefile b/Documentation/Makefile
index fe6709c..4ccb828 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,7 +1,7 @@
MAN1_TXT= \
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
$(wildcard git-*.txt)) \
- gitk.txt gitweb.txt git.txt
+ gitk.txt gitweb.txt git.txt gitremote-helpers.txt
MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
gitrepository-layout.txt gitweb.conf.txt
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
@@ -13,7 +13,7 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
-DOC_HTML=$(MAN_HTML)
+DOC_HTML=$(MAN_HTML) git-remote-helpers.html
ARTICLES = howto-index
ARTICLES += everyday
diff --git a/Documentation/git-remote-helpers.html
b/Documentation/git-remote-helpers.html
new file mode 100644
index 000..0c5ec27
--- /dev/null
+++ b/Documentation/git-remote-helpers.html
@@ -0,0 +1,55 @@
+!DOCTYPE html PUBLIC -//W3C//DTD XHTML 1.1//EN
+http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd;
+html xmlns=http://www.w3.org/1999/xhtml; xml:lang=en
+head
+meta http-equiv=Content-Type content=application/xhtml+xml;
charset=UTF-8 /
+titlegit-remote-helpers(1) - Document Moved/title
+style type=text/css
+/* Cut-down styles from asciidoc.css. */
+
+/* Default font. */
+body {
+ font-family: Georgia,serif;
+}
+
+/* Title font. */
+h1 {
+ font-family: Arial,Helvetica,sans-serif;
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: fuchsia;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+/style
+/head
+body class=manpage
+div id=header
+h1
+Document Moved
+/h1
+/div
+
+pThis document is now called a
+href=gitremote-helpers.htmlgitremote-helpers/a./p
+
+pPlease let the owners of the referring site know so that they can update
the
+link you clicked to get here./p
+
+/body
+/html
diff --git a/Documentation/git-remote-testgit.txt
b/Documentation/git-remote-testgit.txt
index 612a625..f791d73 100644
--- a/Documentation/git-remote-testgit.txt
+++ b/Documentation/git-remote-testgit.txt
@@ -23,7 +23,7 @@ The best way to learn more is to read the comments and
source code in
SEE ALSO
-linkgit:git-remote-helpers[1]
+linkgit:gitremote-helpers[1]
GIT
---
diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/gitremote-helpers.txt
similarity index 99%
rename from Documentation/git-remote-helpers.txt
rename to Documentation/gitremote-helpers.txt
index e36fdcb..0c91aba 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -1,9 +1,9 @@
-git-remote-helpers(1)
-=
+gitremote-helpers(1)
+
NAME
-git-remote-helpers - Helper programs to interact with remote repositories
+gitremote-helpers - Helper programs to interact with remote repositories
SYNOPSIS
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 539c0a0..3ca122f 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -55,7 +55,7 @@ may be used:
where address may be a path, a server and
Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Thu, Jan 31, 2013 at 02:13:10PM -0800, Junio C Hamano wrote: John Keeping j...@keeping.me.uk writes: When looking up a topic via git help topic, git-help prepends git- to topics that are the names of commands (either builtin or found on the path) and git (no hyphen) to any other topic name. git-remote-helpers is not the name of a command, so git help remote-helpers looks for gitremote-helpers and does not find it. Fix this by renaming git-remote-helpers.txt to gitremote-helpers.txt. Signed-off-by: John Keeping j...@keeping.me.uk --- Changes since v1: - add gitremote-helpers.txt to the Makefile since it is no longer caught by git-*.txt. - add a simple git-remote-helpers.html to help people following links to the old name. Doesn't make clean remove the placeholder file? Yes. Should I change it to git-remote-helpers.html.in and then copy it into place? That seems like the simplest answer and means that *.html will continue to refer only to generated files. John -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Thu, Jan 31, 2013 at 09:59:50PM +, John Keeping wrote: When looking up a topic via git help topic, git-help prepends git- to topics that are the names of commands (either builtin or found on the path) and git (no hyphen) to any other topic name. git-remote-helpers is not the name of a command, so git help remote-helpers looks for gitremote-helpers and does not find it. Fix this by renaming git-remote-helpers.txt to gitremote-helpers.txt. Maybe it is just me, but the fact that accessing the manpage is now: man gitremote-helpers feels weird to me. I know it technically follows our syntactic rules, but having the lack of dash be significant between git and remote, but then having a dash later makes it hard on the eyes. Would it make more sense to just call it gitremotehelpers, and then access it as: git help remotehelpers or man gitremotehelpers ? That has it its own ugliness (two words run together), but at least my version of man will accept arbitrary capitalization, allowing: git help remoteHelpers and man gitremoteHelpers I dunno. -Peff -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
John Keeping j...@keeping.me.uk writes:
Yes. Should I change it to git-remote-helpers.html.in and then copy
it into place? That seems like the simplest answer and means that
*.html will continue to refer only to generated files.
I'd like to see if we can have a way to keep its look as the default
css gets updated without maintainance burden.
How about using AsciiDoc instead of cp, perhaps like this on top
of your patch?
Documentation/.gitignore | 1 -
Documentation/Makefile| 9 +-
Documentation/git-remote-helpers.txto | 26 +
Documentation/git-remote-helpers.html | 55 ---
4 files changed, 34 insertions(+), 57 deletions(-)
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 4685378..d62aebd 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -1,6 +1,5 @@
*.xml
*.html
-!git-remote-helpers.html
*.[1-8]
*.made
*.texi
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 13e0098..fa2f9f9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -13,7 +13,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
-DOC_HTML=$(MAN_HTML) git-remote-helpers.html
+OBSOLETE_HTML = git-remote-helpers.html
+DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)
ARTICLES = howto-index
ARTICLES += everyday
@@ -261,6 +262,12 @@ $(MAN_HTML): %.html : %.txt asciidoc.conf
$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $ \
mv $@+ $@
+$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf
+ $(QUIET_ASCIIDOC)$(RM) $@+ $@ \
+ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
+ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $ \
+ mv $@+ $@
+
manpage-base-url.xsl: manpage-base-url.xsl.in
sed s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)| $ $@
diff --git a/Documentation/git-remote-helpers.txto
b/Documentation/git-remote-helpers.txto
new file mode 100644
index 000..a966013
--- /dev/null
+++ b/Documentation/git-remote-helpers.txto
@@ -0,0 +1,25 @@
+git-remote-helpers(1)
+=
+
+NAME
+
+git-remote-helpers - obsoleted page
+
+SYNOPSIS
+
+See linkgit:gitremote-helpers[1].
+
+DESCRIPTION
+---
+This document has been moved to linkgit:gitremote-helpers[1].
+
+Please let the owners of the referring site know so that they can update the
+link you clicked to get here.
+
+SEE ALSO
+
+linkgit:gitremote-helpers[1]
+
+GIT
+---
+No longer a part of the linkgit:git[1] suite
diff --git a/Documentation/git-remote-helpers.html
b/Documentation/git-remote-helpers.html
deleted file mode 100644
index 0c5ec27..000
--- a/Documentation/git-remote-helpers.html
+++ /dev/null
@@ -1,55 +0,0 @@
-!DOCTYPE html PUBLIC -//W3C//DTD XHTML 1.1//EN
-http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd;
-html xmlns=http://www.w3.org/1999/xhtml; xml:lang=en
-head
-meta http-equiv=Content-Type content=application/xhtml+xml; charset=UTF-8
/
-titlegit-remote-helpers(1) - Document Moved/title
-style type=text/css
-/* Cut-down styles from asciidoc.css. */
-
-/* Default font. */
-body {
- font-family: Georgia,serif;
-}
-
-/* Title font. */
-h1 {
- font-family: Arial,Helvetica,sans-serif;
-}
-
-body {
- margin: 1em 5% 1em 5%;
-}
-
-a {
- color: blue;
- text-decoration: underline;
-}
-a:visited {
- color: fuchsia;
-}
-
-h1, h2, h3, h4, h5, h6 {
- color: #527bbd;
- margin-top: 1.2em;
- margin-bottom: 0.5em;
- line-height: 1.3;
-}
-
-/style
-/head
-body class=manpage
-div id=header
-h1
-Document Moved
-/h1
-/div
-
-pThis document is now called a
-href=gitremote-helpers.htmlgitremote-helpers/a./p
-
-pPlease let the owners of the referring site know so that they can update the
-link you clicked to get here./p
-
-/body
-/html
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Jeff King p...@peff.net writes: Maybe it is just me, but the fact that accessing the manpage is now: man gitremote-helpers feels weird to me. It feels equally weird to say man gitremotehelpers (or in general man git-thing or man gitconcept), to me. I gave up and switched to git help remote-helpers some time ago. git help remotehelpers feels like a small regression. I dunno. Me neither. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Thu, Jan 31, 2013 at 02:43:20PM -0800, Junio C Hamano wrote: John Keeping j...@keeping.me.uk writes: Yes. Should I change it to git-remote-helpers.html.in and then copy it into place? That seems like the simplest answer and means that *.html will continue to refer only to generated files. I'd like to see if we can have a way to keep its look as the default css gets updated without maintainance burden. How about using AsciiDoc instead of cp, perhaps like this on top of your patch? I tried AsciiDoc first but didn't like the output. I think putting See gitremote-helpers in the synopsis is the magic I was missing. This looks good to me. John -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Jeff King wrote: Maybe it is just me, but the fact that accessing the manpage is now: man gitremote-helpers feels weird to me. I know it technically follows our syntactic rules, but having the lack of dash be significant between git and remote, but then having a dash later makes it hard on the eyes. Yes. I have thought for years that it should be git-remote-helpers, that git help should be tweaked to look for that, and that the existing gitrepository-layout and friends should be replaced with redirects. I didn't say anything (except a random comment once on #git) because I can't promise to have time soon to work on it. Might try anyway. Thanks, Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Jonathan Nieder jrnie...@gmail.com writes: Jeff King wrote: Maybe it is just me, but the fact that accessing the manpage is now: man gitremote-helpers feels weird to me. I know it technically follows our syntactic rules, but having the lack of dash be significant between git and remote, but then having a dash later makes it hard on the eyes. Yes. I have thought for years that it should be git-remote-helpers, that git help should be tweaked to look for that, and that the existing gitrepository-layout and friends should be replaced with redirects. Because of the git help look up rules, we cannot have two pages that only differ at the dash (or absense of it) immediately after 'git'; e.g. one about the concept of 'frotz' in the context of Git, i.e. man gitfrotz, and the other about the subcommand to perform 'frotz', i.e. man git-frotz. The way to refer to these two pages are both git help frotz. The simplest way forward may be to teach git help to try both paths? But some people configure git help -w to refer to remote site, so it won't be access(path, F_OK). Sigh... -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Junio C Hamano wrote: Jonathan Nieder jrnie...@gmail.com writes: Yes. I have thought for years that it should be git-remote-helpers, that git help should be tweaked to look for that, and that the existing gitrepository-layout and friends should be replaced with redirects. Because of the git help look up rules, we cannot have two pages that only differ at the dash (or absense of it) immediately after 'git'; e.g. one about the concept of 'frotz' in the context of Git, i.e. man gitfrotz, and the other about the subcommand to perform 'frotz', i.e. man git-frotz. The way to refer to these two pages are both git help frotz. Exactly. Hence the disambiguating dash-versus-nondash convention buys us nothing. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
John Keeping j...@keeping.me.uk writes: On Thu, Jan 31, 2013 at 02:43:20PM -0800, Junio C Hamano wrote: John Keeping j...@keeping.me.uk writes: Yes. Should I change it to git-remote-helpers.html.in and then copy it into place? That seems like the simplest answer and means that *.html will continue to refer only to generated files. I'd like to see if we can have a way to keep its look as the default css gets updated without maintainance burden. How about using AsciiDoc instead of cp, perhaps like this on top of your patch? I tried AsciiDoc first but didn't like the output. I think putting See gitremote-helpers in the synopsis is the magic I was missing. This looks good to me. Actually I didn't mean take this patch, it works. I've queued a slightly different version and will push it out as part of 'pu' later. Thanks. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Thu, Jan 31, 2013 at 03:04:55PM -0800, Jonathan Nieder wrote: Jeff King wrote: Maybe it is just me, but the fact that accessing the manpage is now: man gitremote-helpers feels weird to me. I know it technically follows our syntactic rules, but having the lack of dash be significant between git and remote, but then having a dash later makes it hard on the eyes. Yes. I have thought for years that it should be git-remote-helpers, that git help should be tweaked to look for that, and that the existing gitrepository-layout and friends should be replaced with redirects. What was the original rationale for the gitfoo form? Was it just to visually distinguish command manpages from non-command manpages? I can't remember the origins now. It does seem like it is causing more hassle than it is worth, but maybe there is something I am forgetting. -Peff -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
Jeff King p...@peff.net writes:
What was the original rationale for the gitfoo form? Was it just to
visually distinguish command manpages from non-command manpages? I can't
remember the origins now.
b27a23e (Documentation: convert tutorials to man pages, 2008-05-24)
turns tutorial.txt into gittutorial.txt. Before that, there
were git{attributes,cli,ignore,hooks,modules}.txt. They were added
in this order, which reveals the true reason:
hooks.txt
gitignore.txt
gitmodules.txt
gitcli.txt
hooks.txt = githooks.txt
gitatributes.txt
Originally, we did not intend to name them as git$concept.txt;
instead, we just said $concept.txt. Hooks are hooks, and we
know we are discussing hooks in the context of Git, there was no
reason to say githooks. gitignore was about the file format,
and it would have been insane to call it ignore.txt. The same
applies to gitmodules.txt.
Things start to go in a strange direction when cli was added. We
know that is about the command line interface in the context of Git,
and it should have been cli.txt. To make things worse, later
hooks.txt took an example of gitcli.txt in the wrong way at
a5af0e2 (Documentation: rename hooks.txt to githooks.txt and
make it a man page, 2008-05-02).
In other way, I think this wasn't designed, but organically grown.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Rename {git- = git}remote-helpers.txt
On Thu, Jan 31, 2013 at 09:37:51PM -0800, Junio C Hamano wrote:
Jeff King p...@peff.net writes:
What was the original rationale for the gitfoo form? Was it just to
visually distinguish command manpages from non-command manpages? I can't
remember the origins now.
b27a23e (Documentation: convert tutorials to man pages, 2008-05-24)
turns tutorial.txt into gittutorial.txt. Before that, there
were git{attributes,cli,ignore,hooks,modules}.txt. They were added
in this order, which reveals the true reason:
hooks.txt
gitignore.txt
gitmodules.txt
gitcli.txt
hooks.txt = githooks.txt
gitatributes.txt
Originally, we did not intend to name them as git$concept.txt;
instead, we just said $concept.txt. Hooks are hooks, and we
know we are discussing hooks in the context of Git, there was no
reason to say githooks.
Yes, but if we are going to install a manpage, we must include git
somewhere in the name since that context is lost in the global manpage
database. So we need githooks.txt or git-hooks.txt.
gitignore was about the file format,
and it would have been insane to call it ignore.txt. The same
applies to gitmodules.txt.
Right. So we have some that must be gitfoo, and others that do not
care. If we turned githooks into git-hooks and removed the is it a
command? magic from git help, then git help hooks would still find
hooks. And likewise, git help gitignore would still find gitignore.
But you could no longer say git help ignore to find gitignore.
Which personally I am OK with. It is not a sensible thing to ask for;
the concept is not ignore, but rather the gitignore file.
In other way, I think this wasn't designed, but organically grown.
Like many parts of git. :) I am starting to think it has grown in an
unnecessarily complex direction, and we would be much happier just
calling all of the concept documentation git-.
The steps I see are:
1. Modify builtin/help.c, like:
diff --git a/builtin/help.c b/builtin/help.c
index 6067a61..1eca4ea 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -308,10 +308,8 @@ static const char *cmd_to_page(const char *git_cmd)
return git;
else if (!prefixcmp(git_cmd, git))
return git_cmd;
- else if (is_git_command(git_cmd))
- return prepend(git-, git_cmd);
else
- return prepend(git, git_cmd);
+ return prepend(git-, git_cmd);
}
static void setup_man_path(void)
2. Rename the concept files like:
Documentation/{gitcli.txt = git-cli.txt} | 0
Documentation/{gitcore-tutorial.txt = git-core-tutorial.txt} | 0
Documentation/{gitcredentials.txt = git-credentials.txt} | 0
Documentation/{gitcvs-migration.txt = git-cvs-migration.txt} | 0
Documentation/{gitdiffcore.txt = git-diffcore.txt} | 0
Documentation/{gitglossary.txt = git-glossary.txt} | 0
Documentation/{githooks.txt = git-hooks.txt} | 0
Documentation/{gitnamespaces.txt = git-namespaces.txt} | 0
Documentation/{gitrepository-layout.txt = git-repository-layout.txt} | 0
Documentation/{gitrevisions.txt = git-revisions.txt} | 0
Documentation/{gittutorial-2.txt = git-tutorial-2.txt} | 0
Documentation/{gittutorial.txt = git-tutorial.txt} | 0
Documentation/{gitworkflows.txt = git-workflows.txt} | 0
3. Teach Documentation/Makefile about the new filenames. MAN1_TXT
includes git-*.txt, which is no longer right. I think we'd need to
just filter out what is in MAN5_TXT and MAN7_TXT.
4. Replace the rename gitfoo above with a see git-foo... pointer.
Users of git help foo would not ever see this, but people who
have trained their fingers to type man gitfoo would, along with
anybody following an outdated HTML link.
5. Update internal references to linkgit:gitfoo to point to
git-foo.
Hmm. That really does not seem so bad. The biggest downside is the
people who have to see the redirect made in step 4.
But I have not thought about it too hard, so maybe there is something
else I'm not seeing.
-Peff
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
