GNU bug report logs - #38332
document --initialize for vc-dwim [patch]

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 22 Nov 2019 22:50:03 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Nov 22 17:50:02 2019
Received: from localhost ([127.0.0.1]:55672 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1iYHkW-0006dL-Me
	for submit <at> debbugs.gnu.org; Fri, 22 Nov 2019 17:50:02 -0500
Received: from lists.gnu.org ([209.51.188.17]:44312)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <karl@HIDDEN>) id 1iYHkQ-0006d8-RQ
 for submit <at> debbugs.gnu.org; Fri, 22 Nov 2019 17:49:55 -0500
Received: from eggs.gnu.org ([2001:470:142:3::10]:45621)
 by lists.gnu.org with esmtp (Exim 4.90_1)
 (envelope-from <karl@HIDDEN>) id 1iYHkP-0003XF-C8
 for bug-vc-dwim@HIDDEN; Fri, 22 Nov 2019 17:49:54 -0500
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-1.5 required=5.0 tests=BAYES_50,RCVD_IN_DNSWL_MED,
 URIBL_BLOCKED autolearn=disabled version=3.3.2
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <karl@HIDDEN>) id 1iYHkL-0004vO-Nm
 for bug-vc-dwim@HIDDEN; Fri, 22 Nov 2019 17:49:51 -0500
Received: from freefriends.org ([96.88.95.60]:55970)
 by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)
 (Exim 4.71) (envelope-from <karl@HIDDEN>)
 id 1iYHkH-0004rm-DH
 for bug-vc-dwim@HIDDEN; Fri, 22 Nov 2019 17:49:47 -0500
X-Envelope-From: karl@HIDDEN
X-Envelope-To: <bug-vc-dwim@HIDDEN>
Received: from freefriends.org (freefriends.org [96.88.95.60])
 by freefriends.org (8.14.7/8.14.7) with ESMTP id xAMMndcZ004325
 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT)
 for <bug-vc-dwim@HIDDEN>; Fri, 22 Nov 2019 15:49:39 -0700
Received: (from apache@localhost)
 by freefriends.org (8.14.7/8.14.7/Submit) id xAMMnc1b004322;
 Fri, 22 Nov 2019 15:49:38 -0700
Date: Fri, 22 Nov 2019 15:49:38 -0700
Message-Id: <201911222249.xAMMnc1b004322@HIDDEN>
From: Karl Berry <karl@HIDDEN>
To: bug-vc-dwim@HIDDEN
Subject: document --initialize for vc-dwim [patch]
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]
 [fuzzy]
X-Received-From: 96.88.95.60
X-Spam-Score: -1.4 (-)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.4 (--)

I suspect I did not format the ChangeLog entry (or the diff) ideally,
but I hope it will suffice to be usable. -k

2019-11-14  Karl Berry  <karl@HIDDEN>

	doc: Document vc-dwim --initialize in manual.
	
	* vc-dwim.pl: reword --initialize documentation.
	* doc/vc-dwim.texi (Initializing vc-dwim): new node.
	(vc-dwim Invocation): mention --initialize; move most of
	description to new node.

--- doc/vc-dwim.texi	2019-11-13 17:36:14.920575492 -0800
+++ init.texi	2019-11-14 18:31:13.419347192 -0800
@@ -129,4 +129,5 @@
 @menu
 * Using vc-dwim::               How can you use vc-dwim?
+* Initializing vc-dwim::        Setting up a source tree with no ChangeLog file
 * vc-dwim Invocation::          Invoking vc-dwim
 @end menu
@@ -193,4 +194,33 @@
 
 
+@node Initializing vc-dwim
+@section Initializing vc-dwim
+
+vc-dwim operates based on a ChangeLog file; if you maintain a ChangeLog
+as part of your source tree, you don't need to do anything special to
+set up to use vc-dwim; just run it.
+
+However, it is common practice nowadays for source trees not to have
+ChangeLog files, but instead to have them derived for distributions or
+on demand (@code{make ChangeLog}, with a hone common GNU infrastructure).
+So, how to use vc-dwim in this case? It still needs a ChangeLog.
+
+The answer is to run @code{vc-dwim --initialize}. This sets up your own,
+private @file{ChangeLog} file in a git repository rooted at
+@file{@var{VCDIR}/c/}, with a symlink to it from the top level directory
+of the source tree in which you'd like to use vc-dwim.
+
+Your own source tree need not use git; @var{VCDIR} in the above refers
+to the version-control system's control directory, such as @file{.svn},
+@file{_darcs}, etc., as well as @file{.git}.
+
+Then you can make ChangeLog entries as usual, and proceed with use of
+vc-dwim.
+
+You can also set up your own repository of whatever type and make your
+own symlinked top-level ChangeLog into it; there's nothing magical about
+@code{--initialize} or the @file{@var{VCDIR}/c/} location.
+
+
 @node vc-dwim Invocation
 @section Invoking vc-dwim
@@ -202,4 +232,5 @@
 vc-dwim @ovar{option...} --diff @ovar{file...}
 vc-dwim @ovar{option...} --print-vc-list
+vc-dwim @ovar{option...} --initialize
 @end example
 
@@ -227,11 +258,8 @@
 
 But what if you'd like to use @command{vc-dwim} on a project that
-doesn't have or want a @file{ChangeLog} file?  In that case, you can
-maintain your own, private, version-controlled @file{ChangeLog} file in
-a different hierarchy.  Then just make a symlink to it from the top
-level directory of the hierarchy in which you'd like to use it and
-everything should work.  Your private @file{ChangeLog} file need not
-even use the same version control system as the rest of the project
-hierarchy.
+doesn't have or want a @file{ChangeLog} file? In that case, you can
+maintain your own ChangeLog file.  This is what the
+@option{--initialize} option sets up for you, or you can perform
+equivalent steps by hand (@pxref{Initializing vc-dwim}).
 
 @noindent
@@ -261,4 +289,8 @@
 Print the list of recognized version control names, then exit.
 
+@item --initialize
+Prepare a source tree with no @file{ChangeLog} file for use with vc-dwim
+(@pxref{Initializing vc-dwim}).
+
 @item --verbose
 Generate verbose output.
--- vc-dwim.pl	2019-11-13 17:36:14.932575295 -0800
+++ init.pl	2019-11-17 18:31:47.178192024 -0800
@@ -1234,12 +1234,12 @@
 =item B<--initialize>
 
-This option is useful in a project that does not version-control
-a ChangeLog file.  Use this option in the top-level project
-directory to create your personal ChangeLog file -- that file
-will be a symlink to a git-version-controlled ChangeLog file
-in a just-created single-file repository residing in the VC-admin
-directory (.git, .hg, etc.).  If there is an existing ChangeLog file
-in the working directory, running B<vc-dwim --initialize> first
-renames it to ChangeLog~.
+This option, or the equivalent operations, is needed in a project that
+does not version-control a ChangeLog file. Use this option in the
+top-level project directory to create your personal ChangeLog file --
+that file will be a symlink to a git-version-controlled ChangeLog file
+in a just-created single-file repository residing in the VC admin
+directory (.git, .hg, etc.). If there is an existing C<ChangeLog> file
+in the top-level directory, running B<vc-dwim --initialize> first
+renames it to C<ChangeLog~>.
 
 =item B<--help>