Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
International Rescue Committe

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Glossary
MoreInfo
Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
FAQ
Copyright Info
Terms of Use
Privacy Info
Disclaimer
WorkBoard
Thanks
Donations
Advertising
Masthead / Impressum
Your Account

Communication
Feedback
Forums
Private Messages
Surveys

Features
HOWTOs
News Archive
Submit News
Topics
User Articles
Web Links

Google
Google


The Web
linux-tutorial.info

Who's Online
There are currently, 67 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here

  

HOWTO Home

Current HOWTO: Man-Page


Polishing your man page

9. Polishing your man page

Following are some guidelines that increase reliability, readability and 'formatability' of your documentation.

  • Test examples to make sure they work (use cut and paste to give your shell the exact wording from the man page). Copy the output of your command into your man page, don't just type what you think your program will print.

  • Proof read, ispell, and have someone else read it, especially if you are not a native English speaker. The HOWTO you are reading has passed the latter test (special thanks to Michael Miller for a particular heroic contribution! All the remaining rough edges are entirely my fault). Additional volunteers are always welcome.

  • Test your man page: Does groff complain when you format your man page? It's nice to have the groff command line in a comment. Does the man(1) command complain when you call man yourprog? Does it produce the expected result? Will xman(1x) and tkman(1tk) cope with your manual? XFree86 3.1 has xman 3.1.6 - X11R6, it will try to uncompress usinggzip -c -d < %s > %s zcat < %s > %s

  • Will makewhatis(8) be able to extract the one-line description from the NAME section?

  • Translate your man page to HTML format using rman from http://polyglotman.sourceforge.net/, and view the result with a a set of web browsers (netscape, mozilla, opera, lynx, ...) Check that the cross-references among your man pages work as hyperlinks in the generated HTML. If your software package has a web site, post its man pages there, and keep them up-to-date.

  • The rman utility can also translate man pages into LaTeX, RTF, SGML, and other formats; check these out if you want to incorporate your man pages in a book or other larger document.

  • Try translating your man page to HTML using man2html, which has been part of the Linux man package since man-1.4. The man2html utility is a less ambitious translator than rman, but almost every Linux user has it already, so it is worth making sure that man2html does not choke on your man page.


The Linux Tutorial completely respects the rights of authors and artists to decide for themselves if and how their works can be used, independent of any existing licenses. This means if you are the author of any document presented on this site and do no wish it to be displayed as it is on this site or do not wish it to be displayed at all, please contact us and we will do our very best to accommodate you. If we are unable to accommodate you, we will, at your request, remove your document as quickly as possible.

If you are the author of any document presented on this site and would like a share of the advertising revenue, please contact us using the standard Feedback Form.


  
Help us cut cost by not downloading the whole site!
Use of automated download sofware ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and therefore is expressedly prohibited. For more details on this, take a look here

Login
Nickname

Password

Security Code
Security Code
Type Security Code


Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!


Amazon Wish List

Did You Know?
You can get all the latest Site and Linux news by checking out our news page.


Friends



Tell a Friend About Us

Bookmark and Share



Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.12 Seconds