11/26/2018 UNIX Man Pages - Gururaj B S HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Scope of This Session UNIX operating system UNIX user profile Man pages overview Man page content Invoking a man page Formatting macros Header macros Writing a man page – an exercise November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 UNIX Operating System UNIX is a good operating system for experienced programmers. The operating system was designed and implemented by experienced programmers so everything which the experienced programmer needs is present but not much else. The material is completely reference-oriented with very little tutorial information. Experienced programmers find the man pages very useful but a naïve user often finds them overwhelming. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 UNIX Operating System Architecture and Components November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 About Man Pages What are man pages? Brief reference tools or help files that contain almost everything to define how UNIX works Also called “Manual Entries” and “Reference Pages” Man pages are often terse, precise, and obscure. Examples are rare. Some topics are difficult to find because they are features of a shell program, such as the else command of the ksh shell, rather than functions of basic UNIX itself. Available online through the man command if the man pages are present on the system in the /usr/share/man directory in compressed format. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

What happens when you type “man ..” at the UNIX command prompt? 11/26/2018 About Man Pages What happens when you type “man ..” at the UNIX command prompt? File search - /usr/share/man, /usr/contrib/man, and /usr/local/man. MANPATH variable overrides the above default paths. Within each of the the above directories, man searches in cat*.Z, cat*, (formatted version) man*.Z, and man* (nroff-compatible source text) directories. The files in compressed format are uncompressed by Uncompress before printing them for display. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 About Man Pages Naming Convention For a single command, utility or function eg: inetd (1M) For multiple commands or routines - the integrated man page is named for the 1st command or function that appears in the NAME section. For example, the gethostent(3N) man page describes the gethostbyname, gethostbyaddr, sethostent etcetera – Use “ln -s” to link multiple man pages to a single man page. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Use of Man Pages C and Command-Line Interfaces A reference page for a class includes all the documentation for the member functions, constructor, operators, which could result in extremely long man pages. Man pages do not seem to work well with object-oriented languages like C++ and Java. If there is a C++ class named "Foo" and a Java class named "Foo", which one should the user see when they enter "man Foo"? There are situations in which a programmer might be using both languages, for example, writing a Java client and a C++ server application. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Using Basic Commands Within man use the spacebar to see the next page and Q to stop (Space and "Q" work in most UNIX tools, also / to search for a string using a regular expression). Use man -k to list man page descriptions that contain a keyword. You must have a man page index file (/usr/lib/whatis or /usr/share/lib/whatis on on HP-UX), which is created by logging on as root (superuser) and then doing catman -w. The catman command takes a long time to run, so you run it in the background (catman –w &). November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Converting Man Pages to HTML 11/26/2018 Converting Man Pages to HTML Use these tools: Rik Harris's man to HTML converter Jim Garlick's man2html man2html A Perl program to convert Unix man pages to HTML, is available from Earl Hood's home page. RosettaMan is a filter for UNIX manual pages. rman.pl is a CGI-form interface to RosettaMan. RosettaMan man-cgi is shell-sed-awk script that converts on the fly the output of the "man" command to HTML. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Man Page Sections (Extensions) 11/26/2018 Man Page Sections (Extensions) 1 - User Commands eg: sendmail(1) 1M - System Administration Commands/Daemon eg: inetd(1M) 2 - System Calls eg: open(2) 3 – Library Functions eg: Shell(3) 4 – File Formats eg: inetd.conf(4) 5 – Header files, Character Sets, Macro Packages eg: curses(5) 7 – Device Special Files eg: fddi(7) 9 – General Introduction and Definition of terms used in the UNIX environments eg: introduction(9) November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Print Layout of a Man Page 11/26/2018 Print Layout of a Man Page November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page Gives names of the commands, functions, or features and briefly states the purpose NAME SYNOPSIS DESCRIPTION DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page Summarizes the syntax of the command or program entity NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page Discusses the function and behavior of each man page entry. NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Lists and describes the options or arguments supported by the command or utility documented by the man page. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Describes diagnostic information that may be produced. Self-explanatory messages are not listed. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Lists function error conditions and their corresponding error messages November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Provides examples of typical usage of the command or parameters documented by the man page November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Lists potential problems and deficiencies November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Describes variations in HP-UX operation that are related to the use of specific hardware November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Indicates the origin of the software documented by the man page November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Lists file names that are used or affected by the program or command November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Organizing Information in a Man Page 11/26/2018 Organizing Information in a Man Page NAME SYNOPSIS DESCRIPTION Options/Arguments DIAGNOSTICS ERRORS EXAMPLES WARNINGS DEPENDENCIES AUTHOR FILES SEE ALSO Provides pointers to related man pages or other documents November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

About nroff/troff Formats 11/26/2018 About nroff/troff Formats nroff is a text formatting program that interprets source text contained in file and prepares it for printing on typewriter-like devices and line printers. troff formats text for typesetting or laser printing. To edit a man page, open the man page in VI editor i.e., vi ftpcount.1 November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Viewing a Man Page in VI November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

The nroff Header Macros 11/26/2018 The nroff Header Macros .TA <first letter of the man page> .TH - title & entry heading .ds - .SH text - section head text .SS text - subsection head text November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

The nroff Paragraph Macros 11/26/2018 The nroff Paragraph Macros Please refer to the handout given to you for helpful information on paragraph and font macros. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

Man Page Author’s Checklist Edit the man page for tracking purposes. Revise the $Header line with a new date and your name. Check spelling. Run the spell command. Spell checkers do not find everything. Visually check for the wrong word rightly spelt; for example, they're, their, there; its (possessive) or it's (it is). Check grammar and style. There is no command for that, so you will have to use your best judgment. Here are a few points to remember: Use simple sentences. Check that the man page prints correctly, especially with nroff. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Exercise - Solution November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Any Opens? November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

UNIX Man Pages: STC Learning Session @ HP 11/26/2018 Acknowledgements HP management for providing the facility and resources. My peers, IE team, for their wonderful support and encouragement. November 26, 2018 UNIX Man Pages: STC Learning Session @ HP HP_presentation_template

11/26/2018 Thank you… Gururaj B S Ph : +91 (080) 205 3079 E-mail : gururajb@india.hp.com, gururaj_bs@fastmail.fm HP_presentation_template