discuss: Thread: GNU Linux Tools Summary

Hi,

The GNU/Linux tools summary which has been in draft for an eternity (I'm 
becoming more and more busy with uni and life and as a result my 
documentation efforts are decreasing (and programming is increasing!)).

Anyway, I have discussed this document on multiple occasions on the list and 
with Tabatha, it should now be ready for review or acceptance.

A previous review had been done but only made it about half-way through the 
document.

This document is *large* (>100 pages) and has been refined over many, many 
hours work by myself and others.

Please either organise some kind of review or give me some feedback on the 
document (It will now have to be quite detailed feedback due to my lack of 
time).

Regards,
Gareth

_________________________________________________________________
Open an Online Savings Account today & collect a bonus $30*!  
http://clk.atdmt.com/1DG/go/hsb005000991dg/direct/01/

On Sat, Jun 26, 2004 at 01:26:34PM +1000, Guru - wrote:
> Hi,
> 
> The GNU/Linux tools summary which has been in draft for an eternity (I'm 
> becoming more and more busy with uni and life and as a result my 
> documentation efforts are decreasing (and programming is increasing!)).
> 
> Anyway, I have discussed this document on multiple occasions on the list 
> and with Tabatha, it should now be ready for review or acceptance.

I don't agree.  I sampled about 2% of it and again I noticed that much
of what I found were unimportant commands that will not be used
much.  For a doc like yours, only the most important commands and
options should be included.

Also, I tried out a command and it didn't work: echo \tk
It doesn't work because the shell removes th \ passing only tk to the
echo command.  Now just fixing this will not fix the likely oodles of
other things that likely need fixing, deleting, or adding.

> A previous review had been done but only made it about half-way through the 
> document.

I think the reviewer went way to far into it.  
> 
> This document is *large* (>100 pages) and has been refined over many, many 
> hours work by myself and others.
> 
> Please either organise some kind of review or give me some feedback on the 
> document (It will now have to be quite detailed feedback due to my lack of 
> time).

It's my opinion that the doc needs a lot of work by someone who has read
some books on Linux and used the command line interface a lot.   One
needs to select the most important commands and options.  So it's a big
task, likely taking hundred of hours.  I think that some computers keep
statistics on what commands are used most.  But even some of the ones
rarely used are important in emergencies.

I spent the last few minutes taking a look at it again.  I think that
some of what I read could be explained better and in more detail.  But I
still have hopes for it if someone has time to do more work on it.

Sorry to be so critical.  This doc is likely better than a lot of docs
we already have that need to be removed.

> Regards,
> Gareth
> 
> _________________________________________________________________
> Open an Online Savings Account today & collect a bonus $30*!  
> http://clk.atdmt.com/1DG/go/hsb005000991dg/direct/01/
> 
> 
> ______________________
> http://lists.tldp.org/
> 
> 
			David Lawyer

Hi,

">I don't agree.  I sampled about 2% of it and again I noticed that much
>of what I found were unimportant commands that will not be used
>much.  For a doc like yours, only the most important commands and
>options should be included."
I removed many existing commands which were unnessecary, however its still 
possible that there are remaining ones.
I did aim to document commands I considered useful, and I believe I acheived 
that aim.
If someone who uses the command line more than myself (many people) have the 
time and energy to tell me which are the "most used" commands, then I can 
re-order commands appropriately or break down sections further so that the 
most used will appear first and the "possibly useful" are seperate.
Do I have a volunteer? (No, I don't expect one, but it would be nice).

">Also, I tried out a command and it didn't work: echo \tk
>It doesn't work because the shell removes th \ passing only tk to the
>echo command.  Now just fixing this will not fix the likely oodles of
>other things that likely need fixing, deleting, or adding."

I don't know where I metioned the command that you are you referring, I did 
metion echo but not those exact options.

echo -e "stirng with \t or \n's etc. etc."

I'll try and fix that one up, and emphasise again the quoting....

">It's my opinion that the doc needs a lot of work by someone who has read
>some books on Linux and used the command line interface a lot.   One
>needs to select the most important commands and options.  So it's a big
>task, likely taking hundred of hours.  I think that some computers keep
>statistics on what commands are used most.  But even some of the ones
>rarely used are important in emergencies."

Hmm, maybe, but then again, if it comes down to it, I am doing free/open 
source work.
I have limited time and energy to spend on this single document.
If the TLDP reviewers find this unacceptable then I will retract the 
submission and it will likely be happily hosted on 
http://www.karakas-online.de/gnu-linux-tools-summary (or on my own web space 
should Chris wish me to move it).

The document is currently under review, (language review), so if it doesn't 
pass that then its not going to make it in.
I think the reviewers should decide.

>			David Lawyer

Regards,
Gareth

_________________________________________________________________
SEEK: Now with over 50,000 dream jobs! Click here:  
http://ninemsn.seek.com.au?hotmail

--- David Lawyer ####@####.#### wrote:
> On Sat, Jun 26, 2004 at 01:26:34PM +1000, Guru -
> wrote:
> > Hi,
> > 
> > The GNU/Linux tools summary which has been in
> draft for an eternity (I'm 
> > becoming more and more busy with uni and life and
> as a result my 
> > documentation efforts are decreasing (and
> programming is increasing!)).


This document does require a good amount to work and
reorganisation. I was hoping to be able to do this
earlier but havent managed to work on it yet. I will
let you know when I have the time

regards
Rahul Sundaram


		
__________________________________
Do you Yahoo!?
Yahoo! Mail is new and improved - Check it out!
http://promotions.yahoo.com/new_mail

On Wed, Jul 07, 2004 at 04:24:21PM +1000, Guru - wrote:
> ">Also, I tried out a command and it didn't work: echo \tk
> >It doesn't work because the shell removes th \ passing only tk to the
> >echo command.  Now just fixing this will not fix the likely oodles of
> >other things that likely need fixing, deleting, or adding."
> 
> I don't know where I metioned the command that you are you referring, I did 
> metion echo but not those exact options.
> 
> echo -e "stirng with \t or \n's etc. etc."

'echo -e' is non-portable; dash doesn't support it, for instance. printf
would be a better choice.

-- 
Colin Watson                                  ####@####.####

[ooops, posted a copy of this from an unsubscited address, so 
reposting here from my address that's subscribed to ####@####.####

Hello Gareth,

I've had a scan of your "GNU Linux Tools Summary".  First some general 
comments:

-- the material is presented in an unfocussed, unstructured way.  Is the 
document meant to be read linearly?  In that case it is simply confusing.

-- there's a lot of esoteric material; I'd eliminate this and increase the 
detail on the essential areas

-- there are some significant technical errors 

-- I saw many examples of sentences that were not grammatical, or 
presented multiple ideas in a single sentence

Overall, there is useful material in the document, but I'd agree with 
David Lawyer that there really is a lot of technical work still to be done 
to make it useful to the average user.  (You mention that the document is 
undergoing language review; that seems a little premature.)

Here's a question: what is the raison d'etre for this document, as 
compared to say the "Introduction to Linux" ( 
http://www.tldp.org/LDP/intro-linux/html/ ) (and perhaps the "Bash Guide 
for Beginners" ( http://www.tldp.org/LDP/Bash-Beginners-Guide/html/Bash-
Beginners-Guide.html )).  I know you may have an answer to that question, 
but then the next question is: how is that (your answer) reflected in the 
structure and writing of your guide?  The answer to that latter question 
might help you reshape the material.

Some more specific comments below...

Cheers,

Michael


=====

Your abbreviation of control characters as "cntrl-X" is idiosyncratic.  If 
abbreviated, it is usually written as "ctrl-X"; but why save just two 
vowels (as you do)?  Best write it in full: "control-X".

=====

You state in the intro:

[[
This guide is aimed at beginners to intermediate users learning about the 
command-line tools available to them. Advanced users may wish to use it as 
a command reference, but it is less likely that this document would be 
useful to them.
]]

That's fine, but then you go into far too much esoteric material.  I would 
eliminate discussions of the following altogether:

pgrep
pkill
skill
snice
slocate
lastlog
style
diff3
sdiff
figlet
join
enscript
chcase
rgrep
fgrep
The entire section 13 (Mathematical tools)
The entire Section 18. (Graphics tools (command line based)) and 19 (Audio 
tools)
and other stuff as well...

=====

4. Shell Tips

Some specific examples would make "Automatic Command Completion" easier to 
understand.

As a whole, this section seems unfocussed -- it's a kitchen sink approach 
to describing things.

=====

6.2 Usage

You say:

[[
>>

This symbol appends (adds) information to the end of a file or creates one 
if it doesn't exist. **The usage is the same as the > operator.**
]]

It is not the same as ">".  That's the point: it _appends_, as opposed to 
overwriting.  Remove that sentence.

=====

6.3.2
The notation:

    command_1 $command_2

for command substitution is simply wrong!  $command_2 will be treated as a 
*VARIABLE NAME*.  You must write:

    command_1 $(command_2)

=====
6.3.3. Using the pipe instead

Equating the use of a pipe with cmdsubs is just wrong, and the given 
example (using less(1)) is wrong as noted above.

=====

I'd be inclined to eliminate 7.1 ("Mass...") altogether.  This is somewhat 
esoteric.

=====

9.5. Recovering from a system freeze

This section is distribution specific -- not in SUSE for example.  Best to 
remove it.

-- 
Michael Kerrisk
####@####.####

"Sie haben neue Mails!" - Die GMX Toolbar informiert Sie beim Surfen!
Jetzt aktivieren unter http://www.gmx.net/info

At 02:39 AM 7/8/2004, Michael T Kerrisk wrote:
>That's fine, but then you go into far too much esoteric material.  I would
>eliminate discussions of the following altogether:
>
>pgrep
>pkill
>skill
>snice
>slocate
>lastlog
>style
>diff3
>sdiff
>figlet
>join
>enscript
>chcase
>rgrep
>fgrep
>The entire section 13 (Mathematical tools)
>The entire Section 18. (Graphics tools (command line based)) and 19 (Audio
>tools)
>and other stuff as well...

As a bit of support, in the last 8 years the commands in that list I've 
actually used are slocate, lastlog, and diff. Never even heard of a few of 
them.

Cheers,


-- 
Rodolfo J. Paiz
####@####.####
http://www.simpaticus.com

Incoming from Rodolfo J. Paiz:
> At 02:39 AM 7/8/2004, Michael T Kerrisk wrote:
> >That's fine, but then you go into far too much esoteric material.  I would
> >eliminate discussions of the following altogether:
> >
> >pgrep
> >pkill
> >skill
> >snice
> >slocate
> >lastlog
> >style
> >diff3
> >sdiff
> >figlet
> >join
> >enscript
> >chcase
> >rgrep
> >fgrep
> >The entire section 13 (Mathematical tools)
> >The entire Section 18. (Graphics tools (command line based)) and 19 (Audio
> >tools)
> >and other stuff as well...
> 
> As a bit of support, in the last 8 years the commands in that list I've 
> actually used are slocate, lastlog, and diff. Never even heard of a few of 
> them.

slocate, figlet (just wondering what it was), join, enscript, and
fgrep.  In Linux, [fer]grep is all the same animal (Gnu grep), which
changes its behaviour depending on which switches are used.

  history | awk '{print $2}' | sort -u | less

will tell you what you've been up to lately.  Mine's 71 lines long.

HISTFILESIZE=500
HISTSIZE=500


-- 
Any technology distinguishable from magic is insufficiently advanced.
(*)               http://www.spots.ab.ca/~keeling 
- -

Hi,

I don't agreee with that list and I use some of them regularly however, I 
will re-evaluate some of them.

"> > >The entire section 13 (Mathematical tools)
> > >The entire Section 18. (Graphics tools (command line based)) and 19 
>(Audio
> > >tools)"
Section 13 I can consider removing.

Section 18, no way, I don't agree. I will revise the section.

Section 19 I will probably remove (probably, no definitely).


diff3, lastlog, enscript, rgrep, fgrep and maybe style I will consider 
removing (the first 2 I will remove).

The others I'm not sure about yet, I do use quite a few of them daily.

In general (to everyone), I would like to thank you for finally giving me 
some direct feedback, rather than saying that it could be better or its not 
good enough (IMHO that achieves nothing).

This is exactly what I was looking for, not criticism directly, just 
feedback on the document itself.

Thankyou,
Gareth
>From: "s. keeling" ####@####.####
>To: ####@####.####
>Subject: Re: GNU Linux Tools Summary
>Date: Thu, 8 Jul 2004 13:14:17 -0600
>
>Incoming from Rodolfo J. Paiz:
> > At 02:39 AM 7/8/2004, Michael T Kerrisk wrote:
> > >That's fine, but then you go into far too much esoteric material.  I 
>would
> > >eliminate discussions of the following altogether:
> > >
> > >pgrep
> > >pkill
> > >skill
> > >snice
> > >slocate
> > >lastlog
> > >style
> > >diff3
> > >sdiff
> > >figlet
> > >join
> > >enscript
> > >chcase
> > >rgrep
> > >fgrep
> > >The entire section 13 (Mathematical tools)
> > >The entire Section 18. (Graphics tools (command line based)) and 19 
>(Audio
> > >tools)
> > >and other stuff as well...
> >
> > As a bit of support, in the last 8 years the commands in that list I've
> > actually used are slocate, lastlog, and diff. Never even heard of a few 
>of
> > them.
>
>slocate, figlet (just wondering what it was), join, enscript, and
>fgrep.  In Linux, [fer]grep is all the same animal (Gnu grep), which
>changes its behaviour depending on which switches are used.
>
>   history | awk '{print $2}' | sort -u | less
>
>will tell you what you've been up to lately.  Mine's 71 lines long.
>
>HISTFILESIZE=500
>HISTSIZE=500
>
>
>--
>Any technology distinguishable from magic is insufficiently advanced.
>(*)               http://www.spots.ab.ca/~keeling
>- -
>
>______________________
>http://lists.tldp.org/
>

_________________________________________________________________
Protect your inbox from harmful viruses with new ninemsn Premium. Go to   
http://ninemsn.com.au/premium/landing.asp?banner=emailtag&referrer=hotmail

Gidday,

> I don't agreee with that list and I use some of them regularly however, I 
> will re-evaluate some of them.

I think the point here is that these are commands that _you_ 
might use now and then, but they are not on the everyday list 
of tools used by people.  TO be useful, your document needs 
to be selective.  Otherwise it's only a more useful than 
typing "mak -k ."

> "> > >The entire section 13 (Mathematical tools)
> > > >The entire Section 18. (Graphics tools (command line based)) and 19 
> >(Audio
> > > >tools)"
> Section 13 I can consider removing.

Going back -- I see one command in there that is regularly 
useful to me: seq(1), for constructing for loops in shell scripts.

> Section 18, no way, I don't agree. I will revise the section.

See my comment above.  These are tools that _you_ might use, but they 
are not of general interest (IMO, but I don't think I'd be alone in that
opinion).

> Section 19 I will probably remove (probably, no definitely).
> 
> 
> diff3, lastlog, enscript, rgrep, fgrep and maybe style I will consider 
> removing (the first 2 I will remove).
>
> The others I'm not sure about yet, I do use quite a few of them daily.
> 
> In general (to everyone), I would like to thank you for finally giving me 
> some direct feedback, rather than saying that it could be better or its
> not good enough (IMHO that achieves nothing).
> 
> This is exactly what I was looking for, not criticism directly, just 
> feedback on the document itself.

You snipped a question of mine -- and I think it cuts to the heart 
of the problem with this document.  To rephrase: what is your aim, 
and how are you achieving it in the document?

Cheers,

Michael

-- 
Michael Kerrisk
####@####.####

+++ Jetzt WLAN-Router für alle DSL-Einsteiger und Wechsler +++
GMX DSL-Powertarife zudem 3 Monate gratis* http://www.gmx.net/dsl