Re: Longer worked examples in the findutils documentation - comments?

[Bob Proulx]

James Youngman wrote:
> The Findutils documentation (in the development CVS tree) now includes
> two longer worked examples which include several possible approaches
> to solving some common problems with a discussion of why some ways of
> solving the problem are better than others.

I think having an examples such such as this, along with the
rationale, is a very good thing.  Often I know I can deduce something
from first principles but I just want to select one of the precompiled
answers so I can move on.

But I found the "Common Tasks" section and the "Worked Examples"
section to be more the same than they are different.  I think there is
enough material to warrant two sections.  But I would make them
adjacent sections.  Otherwise someone casually reading one section or
the other may not notice that there are two different ones.

> I'd be glad of some feedback on these examples: are they useful of
> themselves?  Are there other good ideas for useful examples which
> offer an opportuinity to cover things that people should know about
> using findutils? 

I have a few common tasks that I would like to see added.  I will see
what I can put together.  But first I have comments on the new
examples.  I looked first at the timestamp example.

> Please note that I haven't actually checked the examples in the
> timestamps section.  I'm hoping to do it at some stage this weekend,
> but I'm not completely sure I'll have time.

First some typographical items:

  s/modicifcation/modification/

Some examples had a hanging ":-" instead of just a ":".  It did not
matter to me which was used but simply ":" seemed more common through
the documentation.

  s/:-$/:/

The description of the problem with the simple case was not so
simple.  Referring to:

  find subdir -newer timestamp -exec touch -r @address@hidden timestamp \; 
  ...

  This does the right sort of thing but has a bug.  Suppose that two
  files two files in the subdirectory have been updated, and that these
  are called @file{file1} and @file{file2}.  The command above will
  update @file{timestamp} with the modification time of @file{file1} or
  that of @file{file2}, but we don't know which one.  Since the
  timestamps on @file{file1} and @file{file2} will in general be
  different, this could well be the wrong value.

Let me suggest being more explicit with the problem.  How about this?
To my mind it is slightly more clear to the reader trying to learn
from the example.

  This does the right sort of thing but has a bug.  Suppose that two
  files two files in the subdirectory have been updated, and that these
  are called @file{file1} and @file{file2}.  The timestamps on
  @file{file1} and @file{file2} will in general be different.  The
  command above will update @file{timestamp} with the modification time
  of both @file{file1} and @file{file2} as individual touch commands,
  but we don't know which one gets updated last.  The find will produce
  them in directory order.  If file2 is found last but has an earlier
  timestamp then the value left on the timestamp file will not be that
  of the newest file in the collection.

The first example:

  find subdir -newer timestamp -exec touch -r {} timestamp \;

But the directory is also a file.

  touch subdir/file3
  find subdir -newer timestamp -print
  .
  ./file3

And:

  touch subdir/file3
  rm subdir/file3
  find subdir -newer timestamp -print
  .

So something needs to be done to restrict the result to the files in
the directory or the timestamp could actually be timestamp of the last
directory operation.  This is also true of the other examples.

In one example:

  find subdir -exec test @address@hidden -nt timestamp \; -exec touch -r 
@address@hidden timestamp \; 
In the next example:
  find subdir -newer timestamp -a \
       -exec test @address@hidden -nt timestamp \; -a \
       -exec touch -r @address@hidden timestamp \; 

The "-a" usage is different and I believe would benefit the reader to
have a word of comment as to why.  Personally I would make the style
of all of the examples the same with regards to -a/-and usage unless
that is the point of the example.

In another example:

  newest=$(find subdir -newer timestamp -printf "%A@:%p\n" | 
             sort -n | 
             tail -1 | 
             cut -d: -f2- ) 
  touch -r "address@hidden:address@hidden" timestamp

I would avoid using 'tail -1', although -1 is back again.  I would
probably use "sed -n '$p'" there just to avoid the issue.  In which
case both it and the cut can be combined.

  newest=$(find subdir -newer timestamp -printf "%A@:%p\n" | 
             sort -n | sed -n '$s/^[[:digit:]]*://p')

I will grant that the different is style and others will perhaps like
the original better.

  touch -r "address@hidden:address@hidden" timestamp

I don't prefer this because the touch is always performed.  I would
prefer if the touch were conditional so that nothing is changed if
nothing has changed.

  if [ -n "$newest" ]; then
    touch -r $newest timestamp
  fi

Or:

  test -n "$newest" && touch -r $newest timestamp

As a general comment I think progressing into the newest.pl perl
solution is interesting.  But I think perhaps going too far.  If find
needs that then I would probably use ls sorting.

  ls -t | sed 1q

Yes, I know, does not handle odd filenames.  I think ls really needs a
-z output format.  (But I would not suggest another short option.
Perhaps --null instead.)  But thinking about this perhaps the perl
example is about the best that can be done.  I will think some more.

I am out of keyboard time for the moment.  And if I don't send this
message now there will be a longer delay.  So hopefully this feedback
has been useful.  I really like the extended examples in the
documentation.  Good stuff.  Thanks for adding them.

Bob