GNU logs - #38332, boring messages

Message sent to bug-vc-dwim@HIDDEN:

Subject: bug#38332: document --initialize for vc-dwim [patch]
Resent-From: Karl Berry <karl@HIDDEN>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
Resent-CC: bug-vc-dwim@HIDDEN
Resent-Date: Fri, 22 Nov 2019 22:51:01 +0000
Resent-Message-ID: <handler.38332.B.157446300325526 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: 38332 <at> debbugs.gnu.org
Date: Fri, 22 Nov 2019 15:49:38 -0700
Message-Id: <201911222249.xAMMnc1b004322@HIDDEN>
From: Karl Berry <karl@HIDDEN>
Precedence: list
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>

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>

Message sent:

Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-Mailer: MIME-tools 5.505 (Entity 5.505)
Content-Type: text/plain; charset=utf-8
X-Loop: help-debbugs@HIDDEN
From: help-debbugs@HIDDEN (GNU bug Tracking System)
To: Karl Berry <karl@HIDDEN>
Subject: bug#38332: Acknowledgement (document --initialize for vc-dwim
 [patch])
Message-ID: <handler.38332.B.157446300325526.ack <at> debbugs.gnu.org>
References: <201911222249.xAMMnc1b004322@HIDDEN>
X-Gnu-PR-Message: ack 38332
X-Gnu-PR-Package: vc-dwim
X-Gnu-PR-Keywords: patch
Reply-To: 38332 <at> debbugs.gnu.org
Date: Fri, 22 Nov 2019 22:51:02 +0000

Thank you for filing a new bug report with debbugs.gnu.org.

This is an automatically generated reply to let you know your message
has been received.

Your message is being forwarded to the package maintainers and other
interested parties for their attention; they will reply in due course.

Your message has been sent to the package maintainer(s):
 bug-vc-dwim@HIDDEN

If you wish to submit further information on this problem, please
send it to 38332 <at> debbugs.gnu.org.

Please do not send mail to help-debbugs@HIDDEN unless you wish
to report a problem with the Bug-tracking system.

--=20
38332: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D38332
GNU Bug Tracking System
Contact help-debbugs@HIDDEN with problems

Last modified: Mon, 25 Nov 2019 12:00:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.