Jakub Narębski [off-list ref] writes:
But I think it is not the best place to keep this documentation.
All true. In case it was not obvious, I didn't mean to say "Here
you find the information, shut up." It was "here is a pointer if
you didn't find it, so that you can use it as a starting point to
make a better documentation."
An analogous entity in the world model of Git that appears
everywhere and is not limited to a single command is the revision
set calculus. Where do we describe it and how do we make it
discoverable? Can the new way to describe pathspec and pathspec
magic mimic the way it is done for the revisions?
W dniu 2016-06-29 o 23:28, Junio C Hamano pisze:
Jakub Narębski [off-list ref] writes:
quoted
But I think it is not the best place to keep this documentation.
All true. In case it was not obvious, I didn't mean to say "Here
you find the information, shut up." It was "here is a pointer if
you didn't find it, so that you can use it as a starting point to
make a better documentation."
An analogous entity in the world model of Git that appears
everywhere and is not limited to a single command is the revision
set calculus. Where do we describe it and how do we make it
discoverable? Can the new way to describe pathspec and pathspec
magic mimic the way it is done for the revisions?
Is that a trick question? :-P
The revision set calculus is described as a standalone documentation
in the gitrevisions(7) manpage (titled "specifying revisions and
[revision] ranges for Git"... well, the "[revision]" isn't there).
This documentation is also accessible via `git help revisions`,
which is cool. It is referenced in the "Symbolic Identifiers"
section of the git(1) manual page.
Long time ago the description of revision set calculus was hidden
in the manpage for the plumbing command git-rev-parse, and is still
included in it (the common part is, via "include::revisions.txt[]").
As I wrote:
quoted
quoted
quoted
Nowadays we have gitcli(7) manual page, but perhaps
it would be better to create a separate manpage for issues related
to pathspec handling (of which ":/" is only one part)... but then
what should it be named?
So we could describe how Git handles pathspecs and pathspec magic
in the new manual page named gitpathspec(7), or gitpaths(7). The
former has the advantage of the name being identical to the entry
in gitglossary(7). The latter has the probable advantage of being
easier for the Git novice to find, and that it could be used to
gather various ways to generate list of files in Git (files in
the working area, files in the staging area aka the index, files
in the revision / tree object, changed files, etc.); the pathspec
in strict sense is about the input. Well, we could have 'manpage
alias' of gitpaths to gitpathspec, or vice versa.
Sidenote: I wonder if people (especially novices) have problem
finding relevant documentation, and if adding something like
"git apropos <topic>" command ("apropos", or "man -k"), or
add the '--apropos' option to "git help" would be useful...
and if it would be easy to create.
The description from gitglossary would be a good start, as would
parts of gitcli and relevant RelNotes. It would need to be linked
from git(1) manpage, and probably also from gitcli.
Now only to start it...
--
Jakub Narębski
Hi Jakub,
Where have you been all these years? :D
On Thu, Jun 30, 2016 at 11:42 AM, Jakub Narębski [off-list ref] wrote:
quoted
quoted
quoted
quoted
Nowadays we have gitcli(7) manual page, but perhaps
it would be better to create a separate manpage for issues related
to pathspec handling (of which ":/" is only one part)... but then
what should it be named?
So we could describe how Git handles pathspecs and pathspec magic
in the new manual page named gitpathspec(7), or gitpaths(7). The
former has the advantage of the name being identical to the entry
in gitglossary(7). The latter has the probable advantage of being
easier for the Git novice to find,
git-pathspec(7) is a great idea. It bugs me that all the pathspec
details are hidden in that glossary file (though I didn't know it was
also available via "git help glossary", which probably just reinforces
its invisibility). The closet place I could think of was git(1) but
that page is already very long.
and that it could be used to
gather various ways to generate list of files in Git (files in
the working area, files in the staging area aka the index, files
in the revision / tree object, changed files, etc.);
You mean the list of commands in this man page? OK. Another thing we
could do is the reverse direction, add gitpathspec(7) as a reference
to all commands that may need it.
the pathspec
in strict sense is about the input. Well, we could have 'manpage
alias' of gitpaths to gitpathspec, or vice versa.
Sidenote: I wonder if people (especially novices) have problem
finding relevant documentation, and if adding something like
"git apropos <topic>" command ("apropos", or "man -k"), or
add the '--apropos' option to "git help" would be useful...
and if it would be easy to create.
I have that problem sometimes and I don't think I can call myself a
noob anymore. I usually need to do some grepping. So yeah "git
apropos" would be great.
--
Duy
On Thu, Jun 30, 2016 at 05:14:15PM +0200, Duy Nguyen wrote:
quoted
So we could describe how Git handles pathspecs and pathspec magic
in the new manual page named gitpathspec(7), or gitpaths(7). The
former has the advantage of the name being identical to the entry
in gitglossary(7). The latter has the probable advantage of being
easier for the Git novice to find,
git-pathspec(7) is a great idea. It bugs me that all the pathspec
details are hidden in that glossary file (though I didn't know it was
also available via "git help glossary", which probably just reinforces
its invisibility). The closet place I could think of was git(1) but
that page is already very long.
quoted
and that it could be used to
gather various ways to generate list of files in Git (files in
the working area, files in the staging area aka the index, files
in the revision / tree object, changed files, etc.);
You mean the list of commands in this man page? OK. Another thing we
could do is the reverse direction, add gitpathspec(7) as a reference
to all commands that may need it.
I'll second (third?) this. Some of our manpages are quite unwieldy, and
I don't think we are doing any favors to users when we auto-include the
same content in multiple places. I think we should instead be splitting
concepts into their own pages and referring to them. That helps users
build the mental model ("aha, pathspecs; I read that concept page and
know how those work!" instead of "here's 3 pages of description on how
git-diff handles paths. Is it identical to the 3 pages in git-log?").
I suspect some things like diff options could benefit from a similar
split.
quoted
Sidenote: I wonder if people (especially novices) have problem
finding relevant documentation, and if adding something like
"git apropos <topic>" command ("apropos", or "man -k"), or
add the '--apropos' option to "git help" would be useful...
and if it would be easy to create.
I have that problem sometimes and I don't think I can call myself a
noob anymore. I usually need to do some grepping. So yeah "git
apropos" would be great.
I think better searching would help a lot if we split things into more
pages (right now, a legitimate technique is "man git-foo", using search
in the pager, and wading through all of the false positives. That sucks,
but at least you can find what you want _eventually_).
I'm not sure if "man -k" is all that great, though, for two reasons:
1. AFAIK there isn't an easy way to restrict it only to git manpages
(try "man -k git"; oh, hello "isxdigit(3posix)").
2. It only searches the title lines. So it's great for finding the
pathspec page, but you could probably already do that by guessing
it's called "git help pathspecs". But if you're looking for
discussion of a particular diff option, say, it would be nice to be
able to search for all mentions of "--word-diff-regex", or
something.
There is "man -K", but it kind of sucks (it seems to just dump you
in any manpage that matches, in a list).
I don't think those are problems that _git_ should necessarily be
solving, though. It's a general problem for manpages. And there may be
better "man" implementations than I'm used to (or even options or
configuration I don't know about).
-Peff
W dniu 2016-07-01 o 08:42, Jeff King pisze:
On Thu, Jun 30, 2016 at 05:14:15PM +0200, Duy Nguyen wrote:
quoted
quoted
So we could describe how Git handles pathspecs and pathspec magic
in the new manual page named gitpathspec(7), or gitpaths(7). The
former has the advantage of the name being identical to the entry
in gitglossary(7). The latter has the probable advantage of being
easier for the Git novice to find,
git-pathspec(7) is a great idea. It bugs me that all the pathspec
details are hidden in that glossary file (though I didn't know it was
also available via "git help glossary", which probably just reinforces
its invisibility). The closet place I could think of was git(1) but
that page is already very long.
quoted
and that it could be used to
gather various ways to generate list of files in Git (files in
the working area, files in the staging area aka the index, files
in the revision / tree object, changed files, etc.);
You mean the list of commands in this man page? OK. Another thing we
could do is the reverse direction, add gitpathspec(7) as a reference
to all commands that may need it.
I'll second (third?) this. Some of our manpages are quite unwieldy, and
I don't think we are doing any favors to users when we auto-include the
same content in multiple places. I think we should instead be splitting
concepts into their own pages and referring to them. That helps users
build the mental model ("aha, pathspecs; I read that concept page and
know how those work!" instead of "here's 3 pages of description on how
git-diff handles paths. Is it identical to the 3 pages in git-log?").
I suspect some things like diff options could benefit from a similar
split.
I'd rather we keep manpages self-contained; one reason is as you said
below easier searching. I also prefer not to have to follow from one
page to another.
On the contrary, I think it would be good idea to include full list
of a configuration variables affecting specific command in its manpage.
Currently almost all configuration variables are in git-config(1)
manpage, but some are in individual manpages, and only linked there.
Redundancy in reference documentation is not bad, provided that it
doesn't require duplication in documentation sources, and that the
documentation itself is not too long, and not too unwieldy.
quoted
quoted
Sidenote: I wonder if people (especially novices) have problem
finding relevant documentation, and if adding something like
"git apropos <topic>" command ("apropos", or "man -k"), or
add the '--apropos' option to "git help" would be useful...
and if it would be easy to create.
I have that problem sometimes and I don't think I can call myself a
noob anymore. I usually need to do some grepping. So yeah "git
apropos" would be great.
I think better searching would help a lot if we split things into more
pages (right now, a legitimate technique is "man git-foo", using search
in the pager, and wading through all of the false positives. That sucks,
but at least you can find what you want _eventually_).
I'm not sure if "man -k" is all that great, though, for two reasons:
1. AFAIK there isn't an easy way to restrict it only to git manpages
(try "man -k git"; oh, hello "isxdigit(3posix)").
One solution would be to use "apropos" / "man -k" and then filter it
(e.g. with /^git/) to filter out non-git manpages.
Another would be to search whatis database ourselves. Yet another
to create whatis-like database, and put it in /usr/share/doc/*.
In both of those cases Git would search the 'database' itself.
2. It only searches the title lines. So it's great for finding the
pathspec page, but you could probably already do that by guessing
it's called "git help pathspecs". But if you're looking for
discussion of a particular diff option, say, it would be nice to be
able to search for all mentions of "--word-diff-regex", or
something.
Well, for apropos-like command to work well we would need better
description of manpages, isn't it?. It is getting better, but we still
have a bit to go...
If Git was to create a whatis-like database (for future "--apropos" and
"--whatis" options to "git help"), it could add extra information, for
example keywords (which would have to be added to manpages sources,
and embedded in whatis-like database when creating man, html, etc.
documentaion formats, i.e. when building documentation).
There is "man -K", but it kind of sucks (it seems to just dump you
in any manpage that matches, in a list).
By default Git installs into /usr/share/doc/git-x.y.z the *.txt and *.html
documentation formats. We could follow "man -K" / "man --global-apropos"
example and search sources... but then we would need to follow inclusions
at least for it to be useful. We could search HTML version of manpages...
but then we would have to strip formatting codes before performing a search.
I don't think those are problems that _git_ should necessarily be
solving, though. It's a general problem for manpages. And there may be
better "man" implementations than I'm used to (or even options or
configuration I don't know about).
I wonder what other version control systems do, like Mercurial, or
Subversion, or Veracity with providing access to their reference docs...
--
Jakub Narębski