Linux Documentation

From openSUSE

The information about Linux is everywhere and it is not easy even to sort all sources of information, but here is one attempt to list them:

• On your computer, as part of software packages:
  • Classic Help menu in newer graphic applications,
  • openSUSE help
  • Manual Pages,
  • Info formatted manuals,
  • Documentation in /usr/share/doc

• In the Internet:
  • Search engines:
    • Google for Linux
    • Using
  • Web pages about Linux and openSUSE
    • About programs that run in Linux
    • About protocols
  • User discussions:
    • Mail lists,
    • Web forums,
    • Newsgroups,

• Online books

• Classic books

Here we'll start from answer to question how to access documents. For that we should know in what formats they are stored on computer in order to use appropriate reader, and where they are located.

Documentation for Linux is trough the time written in many formats, from plain text, man pages and articles written in info format to the Postscript (Ghostscript), PDF, HTML and more.

Text Mode Formats

It was used in the very beginning, when everything was in text mode as:

• plain text README, FAQ, HowTo's.
• man pages is format improved over plain text that allows search, highlight and more. It is considered as must be provided even today. The reason is simple, reflex of each *nix administrator and experienced user is to look application help, than man page, and later for detailed tutorial and other sources.
• info is again improved format over man pages that allows some kind of links and smaller pages that fit in one screen. The really useful is when you use Konqueror and in Location enter, instead of web address info: and name of info page which is usually name of program. Try this with info:grub and you will see a lot of information about GRUB boot loader, that you can browse just as any web page.

To see how it works you can look in article Manual Pages.

Note that all articles are not available in all formats, it is specially true for all kind of README that were, and are, the simplest form used by developers to explain basics about their software. When info was introduced many wrote manuals in that format, including mini man page to list few commands and note that more can be found in info format. As mentioned man page is the minimum that must be provided.

Graphic Mode Formats

Later with development of GUI came in graphic mode editors with abilities never dreamed of in text mode. Formats and programs using new functionality popped up:

• TeX was never in wide use, but it was long time the only way to produce high quality books. It is used online too, for instance, on Wikipedia to present mathematical symbols.
• Ghostscript is the Postscript equivalent, that was the only choice for nice looking documentation before PDF.
• HTML came, with development of Internet, replacing info format and it become format of choice for many authors. It's relative easy to write and everybody that have web browser can read it.
• PDF is relative recent form that allows authors to decide about graphic layout of document, which HTML doesn't guarantee, as rendering in web browser depend on used web browser and fonts installed on user's computer.
• DocBook is XML format for technical documentation and the newest in the family.

Without programs that can convert our typing in some file that will be stored on hard disk, and later convert that file in something readable on the screen, we have no much use of all nice formats and functionality they provide.

Text Mode

• Any text editor is good to read README and other plain text documents.
• man is console (terminal) reader for manual pages.
• info is the same for the documents written in info format.

Graphic Mode

Here is number of choices way higher.

• gs is reader for Postscript formatted documents. Note for new to Linux that command ps is not Postscript reader, but program that lists currently running processes.
• Any web browser is good to read documents in HTML format.
• PDF is possible to read with original Adobe Acrobat Reader, KDE application kpdf and more. For writing you can use again original Adobe product, or export function of OpenOffice Writer program.

Format Converters

Trough the years the collection of documents grew and there was need to convert some to new formats. The man pages and articles written in the info format were the most prominent candidates, as we still keep and use them on computers that don't need GUI, as reference.

• man2html man pages to HTML
• info2html info format to HTML

For a new, first time, Linux users, it is obvious to look for help by clicking "Help" menu at the top of the each application window. This is available in Linux too, but in Linux you can find much more documents that cover almost every aspect of computing. Many documents can be found online, but some of them that are used on daily basis are included in openSUSE distribution and they are already installed by default, like man pages or can be installed, like collection of HOWTO articles.

On Your Computer

• Manual Pages are installed by default with every program that is installed. The location is:

/usr/share/man

and new man pages are going to subdirectories. More about man.

There is automatic way to scan manuals for the specific topic. The console command apropos followed by the topic:

 apropos <topic> 

will list all manpages on your system that reference topic.

• Collection of HOWTO is not necessary installed by default. When it is than you can find all articles in:

/usr/share/doc/howto/<lang>/<format>

<lang>   is language code, like '''en''' for English
<format> is document format, like html

Be aware of fact that most of HOWTO articles you can find in English, because not all are translated to other available languages.

On Internet

The web has a lot of articles about anything imaginable, including Linux. The problem is that they are not always comprehensive, sometimes out of date and in extreme cases plain wrong. Luckily the last is a minor number, specially about Linux, but for new Linux user that can accept any information as valid, the best way to avoid pitfalls is to use reputable sources.

• http://tldp.org is home for The Linux Documentation Project, where you can find HOWTOs, Guides (longer, in-depth books), FAQs (Frequently Asked Questions), man pages (help on individual commands).

• Text mode
• Manual pages
• PDF
• HTML

• Wikipedia

• Documentation

• http://www.tldp.org The Linux Documentation Project
• openSUSE 10.2 official Guide at Novell