Jim Mohr's SCO Companion

Index

Copyright 1996-1998 by James Mohr. All rights reserved. Used by permission of the author.

Be sure to visit Jim's great Linux Tutorial web site at http://www.linux-tutorial.info/

Basics of SCO UNIX


Reading all about it — SCO Documentation

Previous: What SCO is all about

Software documentation is a very hot subject. It continues to be debated in all sorts of forums from CompuServe to user groups. Unless the product is very intuitive, improperly documented software can be almost worthless to use. Even if intuitive to use, many of the functions lay hidden unless you have decent documentation. Unfortunately for many, UNIX is not very intuitive. Therefore, good documentation is essential to be able to use SCO UNIX to its fullest extent.

Despite what many customers want to believe, SCO provides good documentation. Well over half of all the calls to support can be avoided by following the step-by-step procedures in the appropriate section or sections in the manual. A large part of the remainder can be avoided by not just following the steps, but understanding what is being done and not just blindly following instructions.

Unfortunately, few administrators and very few users take the time to read the manuals. This is not good for two important reasons. The first is obviously the wasted time spent calling support for help on things in the manual. The second is that you miss many of the powerful features of the various programs. When you call to support, you usually get a quick and simple answer. Tech support does not have the time to train you how to use a particular program. Two weeks later when you try to do something else with the same program, you're on the phone again.

The biggest problem is that people see the stack of manuals that come with a SCO UNIX system and are immediately intimidated. They would rather spend the money to have support explain things rather than spend time "wading" through all documentation. Some customers do that and they pay a price. Most companies cannot afford the thousands of dollars needed to get that kind of service.

The nice thing is that you don't have to. You neither have to wade through the manuals nor spend the money to have support hold your hand. The SCO manuals are like most books, they have a table of contents, chapters that are logically grouped and at the end of almost every manual is an index. In SCO OpenServer the manuals are on line. This makes searching that much easier. In fact, you can search every manual at once, if you like. You can even bounce between difference places, using what are called "hypertext links."

Since knowing where to look is the biggest problem, that's the issue we are going to address. I don't need to teach you how to read, or understand a table of contents of how to interpret an index entry. However, by making you more familiar with how the documentation is laid out and where to look, you have a much better chance of finding out the answers on your own.

There is no law that says to list a directory the command that you must use is ls or the way to add a user has to be added through the sysadmsh or SCOAdmin. These are merely conventions that SCO has adopted. If you are new to this environment, then many of the commands and utilities seem very obscure to you. In order to be able to fully utilize them, you need to know what they do. Often, the reverse is true as well. The user (or administrator) knows there is a tool on the system to do a certain, but doesn't know where it is.

This is where to documentation comes in. By looking at the appropriate manual, you can quickly find what you are looking for. As those of us who have been in the business for a while know, this is easier said than done. SCO Documentation provides a wealth of information. Almost any task that you need to get accomplished is possible through reading the documentation. Often times, documentation is not effectively used because the user or administrator isn't sure where the information he or she wants is located.

There are two major groups of documentation in SCO systems. The first group is the "guides." These include the System Administrator's Guide and User's Guide, which give step-by-step, often very detailed instructions on procedures and activities on the system. In the table of contents, each section heading is listed along with its page number. A quick glance through the table of contents can quickly point you to the right place. If that doesn't work, there is an extensive index.

The User's Guide is user oriented, although a beginning administrator would find of the information here to be very useful. The User's Guide provides explanations of the various shells, file manipulation programs such vi, sed and awk. There are also chapters on communication with other users with mail or other sites using UUCP.

For the administrator, there is a System Administrator's Guide. Although it contains many of the same subjects, such as mail and UUCP, these are from the administrative perspective. They describe how to set-up and configure these programs and services. In most cases, they provide step-by-step instructions for basic installation and configuration. If that is not sufficient, there is enough supplemental information for you to understand how things are configured and interact to enable you to configure your system far beyond the basics.

In addition and supplemental to the guides are the "references." These include the System Administrator's Reference and the User's Reference. Since these are simply descriptions of various commands and utilities, often limited to a few pages, they are commonly referred to as manual pages or man-pages for short. In many places, including this book, you are encouraged to read the man-page for a particular command, this is what we are talking about.

Unfortunately, the break down of commands listed in the man-pages is not a clear cut as what is described in the Administrator's or User's Guide. Often commands that serve administrative functions are listed in the User's Reference or commands that users need is listed in the Administrator's Reference.

This nice thing is that you usually don't have to know whether a particular command is considered an admin command or a user command. The system will tell you. Unless they have been removed or intentionally not installed, man-pages exist on-line on your system. They are part of the base installation and must either be explicitly removed or intentionally not installed.

Built into the system is a command to read these man-pages: man. By typing man <command> you can find out many details about the command <command>. There are several different options to man that you can use to find out about by typing man man, which will bring up the man man-page. (or the man-page for man)

Often times there are entries in multiple sections. For example, in the C section (where the commands are found) there is an lp entry that explains are the various options to the lp command. Additional, there is an lp man-page in the HW (hardware) section that describes the various parallel port possibilities. There is a man-page for tar in the C section that talks about how to use the tar command. In the F (file format) section, there is a man-page for tar that describes the format of a tar archive. At the front of both the User's Reference and Administrator's Reference is an alphabetical list of all the commands found in that book, along with a brief description of their function.

With OpenServer things are even different still. The only document that is delivered standard is the SCO OpenServer Handbook. This is comparable to the Release Notes and Installation Guide in previous releases. If you want hard copies of the other doc you need to order it. Keep in mind that all the documentation is already on-line.

Should you have Open Desktop installed or one of the extension products, there are additional man-page for these products. If the SCO Development System is installed, there are also several different man-page categories available. Also, SCO ODT comes with additional documentation such as the Graphical Environment Administrator's Guide which contains information about customizing and administering the graphical portion of ODT.

You will see very often in SCO Documentation when referring to a particular command the name followed by one of the above letters in parenthesis, such as ls(C). This indicates that the ls command can be found in the C section of the man-pages. By including the section, you can more quickly find what you are looking for. Here I will be making reference to files usually as examples. I will not be adhering to that practice here. I will only say what section they are in when I explicitly point you toward the man-page.

One very useful aspect of the man-pages is their reference to other man-pages. At the bottom of many of the man-pages is a "See Also" section. This points to man-pages that are related to this one in some way. The reference might be to a command with similar functionality, such as the rm (remove) command has a reference to the rmdir (remove directory) command. In other cases, the reference is to the same heading in a different section, such as the tar(C) man-pages refers you to the tar(F) man-page.

The references and guides that I talked about are not all there is to SCO documentation. There are several other books that are supplied with your product that contain different pieces of information. Some of it can only be found in these books, while other pieces are overviews and reviews of what appears elsewhere.

One common piece of documentation that is overlooked is the Release Notes. The people that most often overlook the Release Notes are those that have either been with SCO for some time or are familiar with other UNIX dialects. Their attitude is that they "know it all" or at least they know everything of importance and the manuals cannot tell them anything new. This is not an exaggeration. On many occasions I received calls from customers saying that they "know how to do an SCO install." When they run into problems, they call support only to find the solution in the release notes.

Of all the books that can prove them wrong, the Release Notes is the most significant. One of the key things that the Release Notes talks about it difference between previous releases and the current one. (Get it? They are notes about this release.)

After about twenty, I lost track of all the customers who called in saying that there was a bug in the new version (SCO UNIX 3.2. version 4.0 and later) in that it didn't recognize their parallel or serial port. In that the freshly installed or upgraded system did not recognize these ports, they were 100% accurate. Where they were off target was in the fact that it wasn't a bug. The release notes clearly state that this is the case.

The reason that these drivers are intentionally left out is an issue of space. With the release of SCO UNIX 3.2. version 4.0, there was a substantial increase in the number of devices that it supported. Many of them, such as SCSI host adapters, needed to be recognized during the installation. To be able to do this they needed to be included in the kernel on the installation disks. As a result, the kernel became too large to fit on a floppy, so something had to go. What else make sense other than something that is not absolutely needed during installation such as serial or parallel ports?

In the Release Notes there is a list of all the documentation that comes with the product. Here the Release Notes are described as "crucial information for Open Desktop installation and configuration." In many cases this is true. For example, if you have only SCSI hard disks in your system you must tell the system CMOS that there are no hard disks. If you don't, the hardware will be looking for an IDE or ESDI hard disk and you'll never be able to install. (This is crucial because if you don't do it right, you can't boot.)

Another piece of documentation that is ignored and contains a wealth of information is the Installation and Update Guide or the SCO OpenServer Handbook. Again, the attitude is that this can't tell them anything new. This is more likely to be true for someone who has been working with SCO for a long time. However, if this is the first time you are working with a particular release, there will definitely be something here that's new.

This book is especially important to people who are new to SCO. Countless customers will call in saying that after installation, they are missing half of their harddisk. I have even dealt with people on CompuServe with this same problem. Within a minute on the phone or by reading the CompuServe message, I know that, no, the space is not missing, they just didn't read the Installation and Update Guide. If they had, they would have known that the "missing" hard disk space is now part of a /u you filesystem and you have to tell the system to go look at it.

If the customer does take up support on this offer (or they already have a support contract) they then get to talk to support analyst. When they are told that this is clearly documented the reaction is often that they don't have time to read all the manuals. Well, they aren't expected to, just the one relevant to the task at hand: installation. The ironic part is that they have the time to call up support and wait to talk to a support engineer, but don't have the time to look for things in the manual.

Accompanying the Release Notes and Installation Guide is the Hardware Configuration Guide. This gives a lot of hardware specific information that can help during installation. In addition, this is a very useful piece of documentation later when you decided to add hardware to an existing system. Information about supported hardware is also available from SCO Sales before you buy your system.

Once the system is installed, a good place to start is the Tutorial. If you are new to SCO, or UNIX in general, this gives a quick overview of the system. Even if you are an experienced SCO user, you might learn a few tricks.

The documentation provided in SCO OpenServer took a giant leap forward. Unless you specifically request hardcopy versions, then the majority of SCO documentation only comes in its on-line version. At first, I was bothered by this, as I like having the doc in front of me. However, the only documentation that you really need to have in hardcopy format is the release notes and installation guide, and that's what you get.


The fundamental structure of scohelp is the same as the MOSAIC interface developed by the National Center for Supercomputing Applications (NCSA) that many people use for their World Wide Web browser. As with the WWW browser, documents, images and other items are connected via "hypertext" links. Because if this similar and the use of the http daemon, scohelp can also provide file across the network.

Each of the hundreds of files composing the SCO Documentation Library is conceptually the same as pages and go to form what are referred to as "virtual" books. These books are what we normally think of as documentation, such as the Administrator's Guide, etc.

The files themselves are written in the hypertext markup language (HTML), which can be used to link not only text but graphics and even photographic images to documents. In some cases the document may contain a reference to a particular image, which appears automatically on the screen with that page is displayed. In other cases, you click on a hypertext link, which causes scohelp (or Mosaic) to go get and then display the image.

Hypertext links do not have to point to images. They can also point to other documents, as well. Using this technique you can move between different areas of the documentation, reviewing related topics and then returning to your starting point. Because the documentation is composed of individual files that are connected via these hypertext links, changes can be made to individual pages without having to redo the entire doc. When updates or patches are installed, new or corrected pages can be installed into the SCO Documentation library without anyone noticing. Because of the way the links are defined, someone could be currently using scohelp and, provided he or she is not using that exact page, the changes would be in effect when they move to that page.

Also built into scohelp is the ability to define "book marks." These are pages (documents) that you have called-up and want to remember. Like a real bookmark, these mark your place within a particular book, allowing you to jump back to that exact page at the click of a button. Although very limited in ability, scohelp does provide a search mechanism.

What's Next?

So, after two chapters we know what an operating system does and what goes into making the SCO UNIX product offering. With the understanding of how things interact and what components are available we can now starting thinking about what the system can do for us. We are now ready to begin working with the system and see just what we need to do to get the system to work for us the way we want.



Next: Shells and Basic Utilities

Index

Copyright 1996-1998 by James Mohr. All rights reserved. Used by permission of the author.

Be sure to visit Jim's great Linux Tutorial web site at http://www.linux-tutorial.info/


Popular Pages