It hasn't been substantially updated for 20 years
(see `git diff e31952da5c52a4c1:Documentation/tutorial-2.txt
0f8e75abebff0877:Documentation/gittutorial-2.adoc`)
and it's becoming out of date, for example:
- refs do not necessarily live in `.git/refs`
- we don't really call it "the index file" anymore, and we don't
encourage users to think about the individual files in `.git` as much
as we did 20 years ago
More importantly, this approach of introducing Git by learning about the
contents of `.git` does not work for most people learning Git for the
first time. It's interesting information for some people (maybe more
advanced users or folks with a strong computer science background, for
not appropriate for a general tutorial).
Right now `gittutorial-2` is meant to be a logical sequel to
`gittutorial` ("read gittutorial, then gittutorial-2").
Deleting `gittutorial-2` means that we can more easily rewrite the main
`gittutorial` (which is also not effective) in any way we want, without
having to make sure that `gittutorial-2` is the logical next step.
We have other documentation which can serve a similar purpose to
tutorial-2 and isn't framed as a general tutorial appropriate for
everyone.
Keep building the man page for now and leave behind a stub to
redirect folks to those other documents.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove the SYNOPSIS section from the section 7 man pages where
appropriate, to avoid having a section that contains no information.
It's not the norm in section 7 to always require a SYNOPSIS.
Update the perl script with a special case for section 7.
Tested by running `make lint-docs`, and looked at the renaming synopses
with this fish script snippet:
for i in *.7
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We presently use the ".txt" extension for our AsciiDoc files. While not
wrong, most editors do not associate this extension with AsciiDoc,
meaning that contributors don't get automatic editor functionality that
could be useful, such as syntax highlighting and prose linting.
It is much more common to use the ".adoc" extension for AsciiDoc files,
since this helps editors automatically detect files and also allows
various forges to provide rich (HTML-like) rendering. Let's do that
here, renaming all of the files and updating the includes where
relevant. Adjust the various build scripts and makefiles to use the new
extension as well.
Note that this should not result in any user-visible changes to the
documentation.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Julia Evans