HOW TO INCLUDE MAN PAGE IN DEBIAN PACKAGING
WHAT IS A MAN PAGE?
Manual pages(man pages) are a descriptive help system that sometimes contains procedural help ("How do I..?") and sometimes the reason the command itself was created (the goal of the program). The command to format and view these manual pages is called man.
WHAT MAN PAGE CONTAINS?
Manual pages have a particular format. When you run the manual page for any program, you will normally find some very common sections. These sections are in bold and capital letters. They are, in order of appearance:
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
BUGS
AUTHOR
SEE ALSO
These sections appear 90% of the time in any descent manual page. You will no doubt find other sections, though they are not the very common ones, and are added for extra information for the program.
NAME
This is the name of the program, followed by a short description of what it does or what the name stands for if it is in an acronym.
SYNOPSIS
Basically, this is the syntax used to run your program from the command line. An example would be like:
wget [-h]
DESCRIPTION
This is where you describe what the program does. Because this is what the user is most likely going to look at first, it is important that this section is clear.
OPTIONS
If your program uses options, as in the above SYNOPSIS section, this is where you explain what each option does. For instance, what does [-d] do when it is given as an argument to program foo? is explained here.
BUGS
If there are any bugs in your program, or anything that does not work the way you want it to, put it here so the user knows.
AUTHOR
Your name followed by your email address. Your email address is important here people to give you bug reports so you can fix up your program.
SEE ALSO
If your program is related in a way to another program, specify the program's name here, followed by its section number. For instance, program foo is a text editor. You might want to make references to say, the vi text editor as: vi(1)
HOW IT WORKS?
When you run the command man foo, what actually happens is that man runs the groff command. Suffice it to say that groff is a text formatter that reads special macros in a file and outputs a formatted file, depending upon the macros used. Read the manual page for groff for a more informative explanation on how to use it. We will be using groff macros to create our manual page. These macros always start with a dot: "." followed by the macro name, and its parameters.
TITLE HEADER
We begin with the .TH macro. This macro expects at least five parameters in the order of:
.TH [name of program] [section number] [center footer] [left footer] [center header]
Now for the explanation:
[name of program]
This is obviously the name of your program. It will be on the left and right header of each page.
[section number]
Manual pages are kept in sections. If you check /usr/man you will find up to nine manual directories. These are the sections. Each section holds a specific type of manual page:
Section 1: user commands.
Section 2: system calls.
Section 3: subroutines.
Section 4: devices.
Section 5: file formats.
Section 6: games.
Section 7: miscellaneous.
Section 8: system administration.
Section n: new.
So if your manual page is for a game, then you will use section 6. If it is a system administration program, then you will use section 8. The section number will appear beside the name of the program in brackets: foo(1)
[center footer]
You can write anything that you like here and it will be displayed at the center of the footer of every page. Normally you put the date here.
[left footer]
You can write anything that you like here and it will be displayed at the left footer of every page. Normally you put the version number of your program here.
[center header]
You can write anything that you like here and it will be displayed at the center header of every page. Most manual pages have this omitted.
the manual pages are divided into sections. These sections are defined with the .SH macro. For instance, the first section is always NAME. .SH requires just one parameter.SH [section name]
.SH will always have [ section name] converted to bold lettering. Text written below .SH will be indented.
WHAT ARE THE FONT ATTRIBUTES?
The simplest ones are bold and italics. The macro for bold is .B and the macro for italics is .I. Depending on your system, italic fonts may appear as underlined text instead of actually italicized text. Normal font (no bold or italic), is called Roman.
use the following for best results
.B = bold
.BI = bold alternating italic
.BR = bold alternating Roman
.I = italic
.IB = italic alternating bold
.IR = italic alternating Roman
.RB = Roman alternating bold
.RI = Roman alternating italic
.SB = Small alternating with bold
.SM = Small (useful for acronyms)
PARAGRAPHING
Simple paragraphing is done with the .PP macro.
Another paragraphing macro to add to your collection is IP. This is great for the OPTIONS section. What it does is takes one parameter. Anything on the next line will be indented and tabbed to the right.
HOW TO INCLUDE MAN PAGE IN DEBIAN PACKAGING
Follow the step to include the man page as part of debian package.
1. Create a file (.manpages) under debian directory
The file should contain the relative path of the man pages for the debian package
Example:
Filename: wget.manpages
Contents:
debian/wget.1
debian/
├── changelog
├── compat
├── wget.1
├── wget.manpages
├── control
├── copyright
├── install
├── postinst
├── postrm
└── rules
When the debian package is installed, the man pages specified are also installed and can be run using the man command.
CONCLUSION
The manual page is supposed to be clear. Have it proof read to make sure there are no errors. Make sure the SYNOPSIS is correct.
WHAT IS A MAN PAGE?
Manual pages(man pages) are a descriptive help system that sometimes contains procedural help ("How do I..?") and sometimes the reason the command itself was created (the goal of the program). The command to format and view these manual pages is called man.
WHAT MAN PAGE CONTAINS?
Manual pages have a particular format. When you run the manual page for any program, you will normally find some very common sections. These sections are in bold and capital letters. They are, in order of appearance:
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
BUGS
AUTHOR
SEE ALSO
These sections appear 90% of the time in any descent manual page. You will no doubt find other sections, though they are not the very common ones, and are added for extra information for the program.
NAME
This is the name of the program, followed by a short description of what it does or what the name stands for if it is in an acronym.
SYNOPSIS
Basically, this is the syntax used to run your program from the command line. An example would be like:
wget [-h]
DESCRIPTION
This is where you describe what the program does. Because this is what the user is most likely going to look at first, it is important that this section is clear.
OPTIONS
If your program uses options, as in the above SYNOPSIS section, this is where you explain what each option does. For instance, what does [-d] do when it is given as an argument to program foo? is explained here.
BUGS
If there are any bugs in your program, or anything that does not work the way you want it to, put it here so the user knows.
AUTHOR
Your name followed by your email address. Your email address is important here people to give you bug reports so you can fix up your program.
SEE ALSO
If your program is related in a way to another program, specify the program's name here, followed by its section number. For instance, program foo is a text editor. You might want to make references to say, the vi text editor as: vi(1)
HOW IT WORKS?
When you run the command man foo, what actually happens is that man runs the groff command. Suffice it to say that groff is a text formatter that reads special macros in a file and outputs a formatted file, depending upon the macros used. Read the manual page for groff for a more informative explanation on how to use it. We will be using groff macros to create our manual page. These macros always start with a dot: "." followed by the macro name, and its parameters.
TITLE HEADER
We begin with the .TH macro. This macro expects at least five parameters in the order of:
.TH [name of program] [section number] [center footer] [left footer] [center header]
Now for the explanation:
[name of program]
This is obviously the name of your program. It will be on the left and right header of each page.
[section number]
Manual pages are kept in sections. If you check /usr/man you will find up to nine manual directories. These are the sections. Each section holds a specific type of manual page:
Section 1: user commands.
Section 2: system calls.
Section 3: subroutines.
Section 4: devices.
Section 5: file formats.
Section 6: games.
Section 7: miscellaneous.
Section 8: system administration.
Section n: new.
So if your manual page is for a game, then you will use section 6. If it is a system administration program, then you will use section 8. The section number will appear beside the name of the program in brackets: foo(1)
[center footer]
You can write anything that you like here and it will be displayed at the center of the footer of every page. Normally you put the date here.
[left footer]
You can write anything that you like here and it will be displayed at the left footer of every page. Normally you put the version number of your program here.
[center header]
You can write anything that you like here and it will be displayed at the center header of every page. Most manual pages have this omitted.
the manual pages are divided into sections. These sections are defined with the .SH macro. For instance, the first section is always NAME. .SH requires just one parameter.SH [section name]
.SH will always have [ section name] converted to bold lettering. Text written below .SH will be indented.
WHAT ARE THE FONT ATTRIBUTES?
The simplest ones are bold and italics. The macro for bold is .B and the macro for italics is .I. Depending on your system, italic fonts may appear as underlined text instead of actually italicized text. Normal font (no bold or italic), is called Roman.
use the following for best results
.B = bold
.BI = bold alternating italic
.BR = bold alternating Roman
.I = italic
.IB = italic alternating bold
.IR = italic alternating Roman
.RB = Roman alternating bold
.RI = Roman alternating italic
.SB = Small alternating with bold
.SM = Small (useful for acronyms)
PARAGRAPHING
Simple paragraphing is done with the .PP macro.
Another paragraphing macro to add to your collection is IP. This is great for the OPTIONS section. What it does is takes one parameter. Anything on the next line will be indented and tabbed to the right.
HOW TO INCLUDE MAN PAGE IN DEBIAN PACKAGING
Follow the step to include the man page as part of debian package.
1. Create a file (
The file should contain the relative path of the man pages for the debian package
Example:
Filename: wget.manpages
Contents:
debian/wget.1
debian/
├── changelog
├── compat
├── wget.1
├── wget.manpages
├── control
├── copyright
├── install
├── postinst
├── postrm
└── rules
When the debian package is installed, the man pages specified are also installed and can be run using the man command.
CONCLUSION
The manual page is supposed to be clear. Have it proof read to make sure there are no errors. Make sure the SYNOPSIS is correct.
No comments:
Post a Comment