Thanks for the review! I've attached a new patch with some revisions. I've pasted the new Markdown version at the end of this email too.
>> Here's a plain text version of the examples in the patch if you (like
>> me) don't want to read raw roff. I actually wrote them in Markdown and
>> converted them with pandoc, very happy to adjust my conversion script or
>> anything else.
>
> Yes 1 or 2 examples is fine and useful.
> but yes they must be very carefully considered.
Very much agreed, in such a short format it's always very important to choose
the examples very carefully.
>
>> HEAD
>> --------------------
>>
>> Print first 10 lines of `file.txt`:
>>
>> head file.txt
>>
>> Print first 40 lines of `file.txt`:
>>
>> head -n 40 file.txt
>
> I wouldn't give two examples of essentially the same functionality.
> I'd also use the example to show correct form when there are variants.
> So for head we could have:
>
> head -n 10 file.txt # first 10 lines
> head -n -1 file.txt # all except last line
I like that, adjusted this (and the tail example) to use that format
>>
>> KILL
>> --------------------
>>
>> Send a SIGTERM signal to the process with PID 1234:
>>
>> kill 1234
>>
>> Send a SIGKILL signal to PID 1234. The process can't block this signal,
>> so it will usually terminate immediately:
>>
>> kill -9 1234
>>
>> Send a SIGHUP signal to PID 1234:
>>
>> kill -HUP 1234
>
> Again no need for variants of same functionality. Ok to have:
>
> kill 1234 # send SIGTERM to pid 1234
> kill -HUP 1234 # send SIGHUP to pid 1234
> kill -l $? # show if last command was terminated with signal
Brought it down to just 2 examples (kill and kill -HUP). I left out
`kill -l` for now since it sounds like it may not be the best example
from the discussion.
>
>> MV
>> --------------------
>>
>> Rename `a.txt` to `b.txt`:
>>
>> mv a.txt b.txt
>>
>> Move `a.txt` to the directory `/home/heather`:
>>
>> mv a.txt /home/heather/
>>
>> Move all files ending in `.jpg` in the current directory to the `photos`
>> directory:
>>
>> mv *.jpg ./photos/
>
> This form may fail if there are too many jpg files,
> so we should avoid examples like that.
> Perhaps it's worth showing:
>
> find . -name '*.jpg' -print0 | xargs -r0 mv -t photos/
I just removed the `mv *.jpg` example for now. I'd rather not
accidentally make users think it's _required_ to use `find`
to move multiple files: I think I've only encountered a case
once in my life where there were too many files in a directory
to move them with a *.
--------------------------
HEAD
-----------------------------
Print first 40 lines of `file.txt`:
head -n 40 file.txt
Print all except the last line of `file.txt`:
head -n -1 file.txt
TAIL
-----------------------------
Print last 40 lines of `file.txt`:
tail -n 40 file.txt
Print all except the first line of `file.txt`:
tail -n -1 file.txt
Print new lines added to `/var/log/messages.txt` as they're added:
tail -f /var/log/messages.txt
KILL
-----------------------------
Send a SIGTERM signal to the process with PID 1234:
kill 1234
Send a SIGHUP signal to PID 1234:
kill -HUP 1234
MV
-----------------------------
Rename `a.txt` to `b.txt`:
mv a.txt b.txt
Move `a.txt` to the directory `/home/heather`:
mv a.txt /home/heather/
examples-v2.patch
Description: Binary data
