discuss: Review of GNU/Linux Tools Summary
Subject:
Re: Review of GNU/Linux Tools Summary
From:
rahul ####@####.####
Date:
14 Dec 2003 08:20:53 -0000
Message-Id: <3FDC1D6B.3040702@yahoo.co.in>
Guru - wrote:
> Hi rahul and everyone else,
>
>> consistency: The document should state the syntax first and example
>> second of vice versa for every command. If the command has a
>> complicated syntax
>> a simplified one can be presented. I find some commands has only
>> example, some
>> has only syntax and some has neither.
>
> Yes, I realise this I haven't being able to create any kind of useful
> example for commands.
> I haven't decided whether I should keep both command syntax and
> example or just replace the command-syntax wth example because the
> syntax is quite generic and doesn't really change much from command to
> command.
> You could get the same information from reading the first paragraph of
> a man page on the command.
> Any comments?
Yes you can get that kind of information from man pages but I dont see
any reason for the inconsistency. Your howto should give readers who are
not familiar with the command a fairly good idea
Here is how you can do it
Command
Short explanation
Syntax(simplified)
Example
Warnings as applicable
References
>
>>
>> References
>>
>> If there are other documents related to the topic the links should be
>> presented
>> within the section itself
>
> Yes thats a good idea, I'll try and fit them in somewhere. The problem
> is that often I don't know any good references (I was hoping people
> would suggest some along with hyperlinks and short descriptions).
>
>> Order and Grouping
>>
>> I find the order and grouping to be sub optimal. The commands which
>> are more
>> used should come first and they should be grouped with similar
>> commands within
>> the same section ex) netstat and nmap . In certain cases, it is not
>> possible to
>> determine which commands are used more and it can done arbitrarily
>> while taking
>> care of grouping only.
>
> I've changed order and grouping many many times.
> I'll try again to re-arrange them thats not a bad idea.
>
>> 1.1
>> The introduction part to assume that the user is fairly technical. It
>> would be
>> better to avoid using technical terms as much as possible in the
>> introduction
>> especially so if the terms are explained within the documentation
>> itself.
>
> I'll try and work on it.
>
>> It is not clear to me whether the document is meant for end users who
>> want to
>> understand the command line or newbie system administrators or
>> somewhere in
>> between.
>
> Intermediate users, users with a basic understanding of the CLI and
> newbie admins.
>
>> 1.2
>> The audience section seems to overlap the introduction. For example
>> the idea
>> that it is not possible to list everything is expressed in both.
>> While this is
>> entirely true I find it redundant.
>
> Yes, I've put it twice because people just don't get to seem the point.
> I'll try make it a little better though.
>
>> 1.7
>>
>> It has explanations of package management starting with mandrake,
>> redhat and then debian. It seems that redhat, debian and mandrake
>> along with
>> slackware is more appropriate based on popularity
>>
>> If the audience is a newbie it would be good to have a explanation of
>> what a
>> package manager does in a short manner
>>
>> For example " A package manager is a utility for centrally managing the
>> installation, upgradation, removal and querying of software in the
>> system"
>>
>> Also appropriate is an explanation of apt-get and yum(fedora).
>
> I'll try and do apt-get and yum when I get time, this will require yet
> more research... Ie. this could be a long time before I get around to it.
> The re-ordering I can do fairly easily.
apt-get install packagename
apt-get update - updates package headers
apt-get upgrade- updates packages
apt-get dist-upgrade - upgrades the distribution
apt-get -f install - fixes dependencies
apt-cache search packagename
yum update
yum update
yum install
yum info
yum remove
yum list
yum search
yum provides
yum check-update
>
>> There should be a differentiation between package management and
>> dependency resolving tools.
>
> How would you define a dependency resolving tool? Are you referring to
> apt-get? and urpmi? and yum?
Yes. all three. Slackware has a tool called swaret which I havent used.
Its included in the latest slackware cd but not installed by default
>
>> 2.Legal
>> You have choosen the GNU FDL as the license. Here are some issues to
>> consider
>> http://www.google.co.in/search?q=cache:SErldDCN1KMJ:people.debian.org/~srivasta/
>>
>> Position_Statement.html+debian+fdl+position+&hl=en&ie=UTF-8
>>
>> Alternatives include the OPL(without restrictions) and Creative
>> commons share
>> alike license.
>
> I'm waiting for the debate about licenses to finish before I do
> anything about the license.
>
Fine. Just wanted to make sure you are aware of the issues and choices
>> 3. The Unix tools philosophy
>>
>> It would be better to call it design rather than philosophy when it
>> talking a
>> hands on approach. Instead of using the word "Unix based" a better
>> wording would
>> be "Unix-like". Also acknowledge any trademarks as such.
>
> Unix based is not always the correct word for it, its Unix-like not a
> copy of Unix source.
You have used unix-based. I am suggesting you use unix-like.
>
>> 4. Shell tips
>>
>> You have used the word cntrl to specify control keys. I find ^ and
>> ctrl to be
>> more common usage. Considering using them instead if not specify the
>> word
>> "control" itself each time. This would make the document lend itself
>> better as a
>> reference.
>
> I tihink cntrl vs ctrl is very minor although using the "^" symbol
> wouldn't be a bad idea. I've seen it used more in techincal manuals so
> I might as well start using it here. (I've seen the '-' used in many
> other places too), also a minor issue...
>
Yes. Its a minor issue but makes the document look better.
>> You can include a section about using back quotes too.
>
> I already have one, section 6.3 "command substitution".
>
>> 4.1 Virtual terminals
>>
>> The explanation could include the difference between x the protocol
>> and Xfree86
>> the implementation (foot notes or references where appropriate).
>
> Yes that might be a good idea, but thats starting to push outside the
> scope of the document. So I don't think I'll add that.
Since you mentioned XFREE86 you can refer to the xfree86 howto.
>
>> 5.Help
>>
>> apropos is a alternative for man -k. It does not search whatis strings?
>> A section on using konqueror and nautilus to view man and info pages
>> might be
>> considered even though this document is entirely about command line
>> tools.I
>> personally find konqueror to be a handy tool even when relying on the
>> command
>> line stuff to do the actual task. This way you can use info and man
>> pages
>> without relearning key bindings.
>
> I'm not sure how you do it in Konqueror and nautilus, if you do know
> than please tell me because I don't have enough space to install them
> on this computer at the moment. And I don't have enough time to
> research everything myself.
>
konqueror -
man:/ - list man pages
info:/ - list info pages
man:/command or #command
info:/command or ##comand
I am not sure about nautilus
>
>> 9.2 Shutting down
>>
>> halt can be explained first followed by shutdown commands.poweroff
>> can be
>> included too.
>
> I'm not familiar with poweroff, I'll have to check whether it exists
> on my mandrake system.
type poweroff with turn off the system where hardware supports it
halt will stop all the processes but the system will remain switched on.
>
>> 9.3 Controlling Processes
>>
>> ps aux | grep is a fairly common usage.
>
> Yes I use it all the time, I think it might be listed under the ps
> section.
>
>> kill -9 can be explained here.
>
> Didn't I explain that under the description of kill?
I dont think so. check again.
>
>> 9.4 Controlling services
>>
>> service start, status and restart can be explained here
>> update-rc.d is the debian equivalent?
>> slackware?
>
> Yes I'll check out the debian equivalent, this is the kind of feedback
> I need. :)
>
>> 11. Text related tools
>>
>> Pico or nano might be appropriate for new user
>
> Yes I could probably mention them I guess....(without starting some
> kind of text-editor war on which ones should and shouldn't be mentioned).
Just mention the commands without advising anything.
>
>> 11.2 Text based tools
>>
>> The order of listing can be changed according the common usage.
>>
>> cat
>> less
>> tail (-f option is very common for real time lookups)
>> sort
>> .....
>
> I'll try it.
> But I'm not entirely sure on what order they are most often used in.
I will try to be specific on the next update
>
> I've should probably add them. bzip2 is mentioned! along with gzip!
You have mentioned the commands but not the differences.
>
>> 24. Mini guides
>>
>> Rpm is explained but debian and slackware systems could be added.
>
> Yes but I don't know how they work and I'm not sure whether to keep
> the RPM section or not...
> Because there are a lot of tutorials written already on RPM, Debian,
> slackware package management.
>
Refer to maximum rpm guide and other references you can find. That
should do. You can find the debian and slackware equivalents in
debian.org and slackware.org.
I cant see your notes in Lyx unless I view it in the editor which I
didnt. Wait for more peer reviews. I will send some specific content in
a couple of days
Regards
Rahul Sundaram
