Re: checklink: error (or opportunity for improvement?) in masquerade option and/or checklink.pod

On 23 Apr 2009, at 17:10 , C. M. Sperberg-McQueen wrote:

 > It appears that either the --masquerade option is not working, or
 > the documentation could usefully be revised to make clearer how to
 > use it.

It's often useful to decide you've done all you can, write it up, and
send off a bug report.  Because then you worry at it just a little bit
more and discover that you've sent in a bug report riddled with errors
and made a fool of yourself in public.  I'm sure I'm a better man for
the experience .

Apologies.  Further experimentation makes clear that (a) the
masquerade option does work, and (b) the tests I did which seemed to
show the opposite were bogus.

One part of my earlier problem report remains true: I find the
documentation of this feature confusing.

 > I made a test file (attached) named testdoc.html,

It's of less importance now, but this time I *do* attach it, for the
use of those who find it useful.

 > ...  I have run this test case with the local argument in the forms

 >  "."
 >  "./"
 >  "/Users/cmsmcq/2009/misc"
 >  "/Users/cmsmcq/2009/misc/"
 >  "file:///Users/cmsmcq/2009/misc"
 >  "file:///Users/cmsmcq/2009/misc/"

 > and the remote argument in the forms

 >  "http://www.w3.org/XML"
 >  "http://www.w3.org/XML/"

 > with the arguments in the order remote - local and local - remote.
 > All 24 permutations produce the same result, which suggests that in
 > no case am I succeeding in making masquerading do anything at all.

As noted already results were misleading.  They were obtained using a
for ... do construction on the bash command line in which I appear to
have made a character escaping error.  (RFE: perhaps the handling of
the --masquerade option should check for a first argument which begins
with a literal quotation mark or a second argument which ends with
one?)

Now that I seem to have gotten --masquerade to work, I can suggest
wording for the man page which I think may be clearer for some
readers.  The current man page says this about masquerade:

--masquerade "local remote"

     Masquerade local dir as a remote URI. For example, the following
     results in /my/local/dir/ being "mapped" to
     http://some/remote/uri/

       --masquerade "/my/local/dir http://some/remote/uri/"

     As of revision 3.6.2.19 of checklink, --masquerade takes a single
     argument consisting of two URIs, separated by whitespace. The
     quote marks are not part of the argument, but one usual way of
     providing a value with embedded whitespace is to enclose it in
     quotes.

I propose two alternative versions: (A), which retains the local /
remote example, and 9B), which doesn't.

(A)

--masquerade "remote local"

     Make a local dir masquerade as a remote one. For example, the
     following results in mapping URIs in http://example.com/x/y/z/
     onto the local directory /my/local/dir/

       --masquerade "http://example.com/x/y/z/ file:///my/local/dir/"

     If the document being checked contains a link to
     http://example.com/x/y/z/foo.html, then the local file system will
     be checked for file:///my/local/dir/foo.html.

     As of revision 3.6.2.19 of checklink, --masquerade takes a single
     argument consisting of two URIs, separated by whitespace. The
     quote marks are not part of the argument, but one usual way of
     providing a value with embedded whitespace is to enclose it in
     quotes.

(B)

--masquerade "real-prefix surrogate-prefix"

      Perform a simple string substitution: URIs which begin with the
      string real-prefix are rewritten using the surrogate-prefix
      before being dereferenced.  Useful for making a local
      directory masquerade as a remote one. For example:

       --masquerade "http://example.com/x/y/z/ file:///my/local/dir/"

     If the document being checked contains a link to
     http://example.com/x/y/z/foo.html, then the local file system will
     be checked for file:///my/local/dir/foo.html.

     As of revision 3.6.2.19 of checklink, --masquerade takes a single
     argument consisting of two URIs, separated by whitespace. The
     quote marks are not part of the argument, but one usual way of
     providing a value with embedded whitespace is to enclose it in
     quotes.


-- 
****************************************************************
* C. M. Sperberg-McQueen, Black Mesa Technologies LLC
* http://www.blackmesatech.com
* http://cmsmcq.com/mib
* http://balisage.net
****************************************************************