Update "git help guides" documentation organization.

* pb/guide-docs:
  git.txt: add list of guides
  Documentation: don't hardcode command categories twice
  help: drop usage of 'common' and 'useful' for guides
  command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
This commit is contained in:
Junio C Hamano 2020-08-10 10:24:04 -07:00
Родитель abde3d39ec f442f28a81
Коммит 995c71986a
9 изменённых файлов: 34 добавлений и 22 удалений

Просмотреть файл

@ -17,6 +17,7 @@ MAN1_TXT += git.txt
MAN1_TXT += gitk.txt
MAN1_TXT += gitweb.txt
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
MAN5_TXT += gitattributes.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
@ -294,6 +295,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
cmds-plumbingmanipulators.txt \
cmds-synchingrepositories.txt \
cmds-synchelpers.txt \
cmds-guide.txt \
cmds-purehelpers.txt \
cmds-foreignscminterface.txt
@ -301,7 +303,7 @@ $(cmds_txt): cmd-list.made
cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
$(QUIET_GEN)$(RM) $@ && \
$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \
date >$@
mergetools_txt = mergetools-diff.txt mergetools-merge.txt

Просмотреть файл

@ -6,9 +6,14 @@ sub format_one {
my ($out, $nameattr) = @_;
my ($name, $attr) = @$nameattr;
my ($state, $description);
my $mansection;
$state = 0;
open I, '<', "$name.txt" or die "No such file $name.txt";
while (<I>) {
if (/^git[a-z0-9-]*\(([0-9])\)$/) {
$mansection = $1;
next;
}
if (/^NAME$/) {
$state = 1;
next;
@ -27,7 +32,7 @@ sub format_one {
die "No description found in $name.txt";
}
if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) {
print $out "linkgit:$name\[1\]::\n\t";
print $out "linkgit:$name\[$mansection\]::\n\t";
if ($attr =~ / deprecated /) {
print $out "(deprecated) ";
}
@ -38,12 +43,15 @@ sub format_one {
}
}
while (<>) {
my ($input, @categories) = @ARGV;
open IN, "<$input";
while (<IN>) {
last if /^### command list/;
}
my %cmds = ();
for (sort <>) {
for (sort <IN>) {
next if /^#/;
chomp;
@ -51,17 +59,10 @@ for (sort <>) {
$attr = '' unless defined $attr;
push @{$cmds{$cat}}, [$name, " $attr "];
}
close IN;
for my $cat (qw(ancillaryinterrogators
ancillarymanipulators
mainporcelain
plumbinginterrogators
plumbingmanipulators
synchingrepositories
foreignscminterface
purehelpers
synchelpers)) {
my $out = "cmds-$cat.txt";
for my $out (@categories) {
my ($cat) = $out =~ /^cmds-(.*)\.txt$/;
open O, '>', "$out+" or die "Cannot open output file $out+";
for (@{$cmds{$cat}}) {
format_one(\*O, $_);

Просмотреть файл

@ -21,8 +21,8 @@ on the standard output.
If the option `--all` or `-a` is given, all available commands are
printed on the standard output.
If the option `--guides` or `-g` is given, a list of the useful
Git guides is also printed on the standard output.
If the option `--guides` or `-g` is given, a list of the
Git concept guides is also printed on the standard output.
If a command, or a guide, is given, a manual page for that command or
guide is brought up. The 'man' program is used by default for this
@ -58,7 +58,7 @@ OPTIONS
-g::
--guides::
Prints a list of useful guides on the standard output. This
Prints a list of the Git concept guides on the standard output. This
option overrides any given command or guide name.
-i::

Просмотреть файл

@ -304,6 +304,13 @@ users typically do not use them directly.
include::cmds-purehelpers.txt[]
Guides
------
The following documentation pages are guides about Git concepts.
include::cmds-guide.txt[]
Configuration Mechanism
-----------------------

Просмотреть файл

@ -3,7 +3,7 @@ gitcredentials(7)
NAME
----
gitcredentials - providing usernames and passwords to Git
gitcredentials - Providing usernames and passwords to Git
SYNOPSIS
--------

Просмотреть файл

@ -579,7 +579,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)
}
if (show_guides)
list_common_guides_help();
list_guides_help();
if (show_all || show_guides) {
printf("%s\n", _(git_more_info_string));

Просмотреть файл

@ -195,6 +195,7 @@ git-write-tree plumbingmanipulators
gitattributes guide
gitcli guide
gitcore-tutorial guide
gitcredentials guide
gitcvs-migration guide
gitdiffcore guide
giteveryday guide
@ -204,6 +205,7 @@ githooks guide
gitignore guide
gitmodules guide
gitnamespaces guide
gitremote-helpers guide
gitrepository-layout guide
gitrevisions guide
gitsubmodules guide

4
help.c
Просмотреть файл

@ -397,10 +397,10 @@ void list_cmds_by_config(struct string_list *list)
}
}
void list_common_guides_help(void)
void list_guides_help(void)
{
struct category_description catdesc[] = {
{ CAT_guide, N_("The common Git guides are:") },
{ CAT_guide, N_("The Git concept guides are:") },
{ 0, NULL }
};
print_cmd_by_category(catdesc, NULL);

2
help.h
Просмотреть файл

@ -21,7 +21,7 @@ static inline void mput_char(char c, unsigned int num)
void list_common_cmds_help(void);
void list_all_cmds_help(void);
void list_common_guides_help(void);
void list_guides_help(void);
void list_all_main_cmds(struct string_list *list);
void list_all_other_cmds(struct string_list *list);