Re: [Bug-vc-dwim] "man vc-dwim" says @@ME@@ a lot

[Jim Meyering]

Paul Eggert wrote:
> After installing vc-dwim 1.3, I noticed that
> the command "man vc-dwim" outputs stuff like this:
>
> NAME
>        @@ME@@ - use new ChangeLog entries to direct and cross-check a
>        version-control "diff" or "commit" command
>
> SYNOPSIS
>        @@ME@@ [OPTIONS] [CHANGELOG_FILE...]
>
>        @@ME@@ [OPTIONS] --commit CHANGELOG_FILE...
>
>        @@ME@@ [OPTIONS] --diff [FILE...]
>
>        @@ME@@ [OPTIONS] --print-vc-list
>        ...
>
> I suppose the simplest fix is to uniformly replace "vc-dwim" with "@@ME@@"
> in vc-dwim.pl, but I figure that those @@ME@@s are in there for some
> reason and I'm not sure what the "right" fix would be.

Hi Paul,

Thanks for reporting that.
I've unfactored, as you suggest, and removed the now-unused machinery
that performed the substitution:

>From e6b932b2e94ae3c25037e4d6e95e54bcae8eeb2d Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Wed, 5 Jan 2011 16:17:47 +0100
Subject: [PATCH] doc: don't emit @@ME@@ strings into generated man page

Do hard-code the program name, vc-dwim, in the --help POD sources,
rather than using @@ME@@ and substituting at output time.  The man
page generation process, $(POD2MAN), didn't know to perform that
substitution.
* vc-dwim.pl: s/@@ME@@/vc-dwim/, as above.
(package PodTemplate): Now that we no longer substitute anything
in --help output, remove the embedded package and its functions.
Reported by Paul Eggert.
---
 ChangeLog  |   12 ++++++++++++
 vc-dwim.pl |   54 ++++++++++++------------------------------------------
 2 files changed, 24 insertions(+), 42 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index bd49133..3e7a41f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2011-01-05  Jim Meyering  <address@hidden>
+
+       doc: don't emit @@ME@@ strings into generated man page
+       Do hard-code the program name, vc-dwim, in the --help POD sources,
+       rather than using @@ME@@ and substituting at output time.  The man
+       page generation process, $(POD2MAN), didn't know to perform that
+       substitution.
+       * vc-dwim.pl: s/@@ME@@/vc-dwim/, as above.
+       (package PodTemplate): Now that we no longer substitute anything
+       in --help output, remove the embedded package and its functions.
+       Reported by Paul Eggert.
+
 2010-11-07  Jim Meyering  <address@hidden>

        tests: don't fail symlinked-changelog when email not define in ~/.bazaar
diff --git a/vc-dwim.pl b/vc-dwim.pl
index 0efd7a0..ee08d01 100755
--- a/vc-dwim.pl
+++ b/vc-dwim.pl
@@ -31,37 +31,6 @@
 use strict;
 use warnings;

-package PodTemplate;
-use Pod::PlainText;
-our @ISA = qw(Pod::PlainText);
-
-sub new
-{
-  my $this = shift;
-  my $class = ref($this) || $this;
-  my %params = @_;
-  my $self = { %params };
-  bless $self, $class;
-  $self->initialize();
-  return $self;
-}
-
-sub _lookup($$)
-{
-  my ($dict, $word) = @_;
-  return exists $dict->{$word} ? $dict->{$word} : $word;
-}
-
-sub preprocess_paragraph
-{
-  my ($self, $text) = @_;
-  $text =~ s/address@hidden@(.*?)address@hidden@/_lookup($self->{dict},$1)/eg;
-  return $text;
-}
-
-
-package main;
-
 use Getopt::Long;
 use File::Basename; # for basename and dirname

@@ -83,6 +52,7 @@ BEGIN
 use Coda;
 use VC;
 use ProcessStatus qw($PROCESS_STATUS process_status);
+use Pod::PlainText;

 our $VERSION = '@VERSION@';
 (my $ME = $0) =~ s|.*/||;
@@ -100,7 +70,7 @@ sub usage ($)
     }
   else
     {
-      my $parser = PodTemplate->new (sentence => 1, width => 78,
+      my $parser = Pod::PlainText->new (sentence => 1, width => 78,
                                      dict => {ME => $ME});
       # Read POD from __END__ (below) and write to STDOUT.
       *STDIN = *DATA;
@@ -1076,25 +1046,25 @@ __END__

 =head1  NAME

-@@ME@@ - use new ChangeLog entries to direct and cross-check a
+vc-dwim - use new ChangeLog entries to direct and cross-check a
 version-control "diff" or "commit" command

 =head1  SYNOPSIS

-B<@@ME@@> [OPTIONS] [CHANGELOG_FILE...]
+B<vc-dwim> [OPTIONS] [CHANGELOG_FILE...]

-B<@@ME@@> [OPTIONS] --commit CHANGELOG_FILE...
+B<vc-dwim> [OPTIONS] --commit CHANGELOG_FILE...

-B<@@ME@@> [OPTIONS] --diff [FILE...]
+B<vc-dwim> [OPTIONS] --diff [FILE...]

-B<@@ME@@> [OPTIONS] --print-vc-list
+B<vc-dwim> [OPTIONS] --print-vc-list

 =head1  DESCRIPTION

 By default, each command line argument should be a locally modified,
 version-controlled ChangeLog file.  If there is no command line argument,
-B<@@ME@@> tries to use the ChangeLog file in the current directory.
-In this default mode, B<@@ME@@> works by first computing diffs of those
+B<vc-dwim> tries to use the ChangeLog file in the current directory.
+In this default mode, B<vc-dwim> works by first computing diffs of those
 files and parsing the
 diff output to determine which named files are being changed.
 Then, it diffs the affected files and prints the resulting output.  One
@@ -1104,7 +1074,7 @@ It detects that by searching for an editor temporary file 
corresponding
 to each affected file.  Another common error you can avoid with this
 tool is the one where you create a new file, add its name to Makefiles,
 etc., mention the addition in ChangeLog, but forget to e.g., "git add"
-(or "hg add", etc.) the file to the version control system.  B<@@ME@@>
+(or "hg add", etc.) the file to the version control system.  B<vc-dwim>
 detects this discrepancy and fails with a diagnostic explaining the
 probable situation.  You might also have simply mistyped the file name
 in the ChangeLog.
@@ -1113,7 +1083,7 @@ Once you are happy with your ChangeLog-derived diffs, you 
can commit
 those changes and the ChangeLog simply by rerunning the command with
 the --commit option.

-But what if you'd like to use B<@@ME@@> on a project that doesn't have
+But what if you'd like to use B<vc-dwim> on a project that doesn't have
 or want a ChangeLog file?  In that case, you can maintain your own,
 private, version-controlled ChangeLog file in a different hierarchy.
 Then just make a symlink to it from the top level directory of the
@@ -1165,7 +1135,7 @@ Generate debug output.

 =head1  EXAMPLE

-Here's how to use B<@@ME@@> in a project that does not version-control
+Here's how to use B<vc-dwim> in a project that does not version-control
 a ChangeLog file.  Create a repository just for your personal
 ChangeLog file and make a symlink to it from the top-level directory
 of the project.  For projects that use git, I put this tiny
--
1.7.3.4