View source for Guidelines for Manual Page Authors

==Manual Page Content==

Manual pages are written in the POD documentation language. A guide to POD syntax is available [http://perldoc.perl.org/perlpod.html here].

The POD syntax used in the manual pages is quite versatile and is used to generate manual pages in a number of different formats:
* Linux/Unix style "man" pages
* HTML docs

When writing content you should be mindful of all the different formats that your page will be translated into. You should not assume for example that the end user will be using a web browser.

The different headings shown in each page do vary slightly. Generally you should at least include the following:
* Name
* Synopsis
* Description
* See Also

Where possible you should also include a "History" heading. Pages describing libssl and libcrypto functions usually also include a "Return Values" section.

Refer to the other existing pages for examples of what should go in to each of these headings. The content under the "Name" heading is particularly important and should conform to a standard format. Here you should provide a comma separated list starting with the name of the page itself followed by all of the aliases that this page can have. After the list there should be a minus, "-", followed by a brief description of the page. For example:

<pre>
EVP_PKEY_new, EVP_PKEY_free - private key allocation functions.
</pre>

This is particularly important for pages describing libssl and libcrypto functions. The aliases should include all of the different functions that are described on the page.

This list of aliases is used during Linux/Unix man page generation so that (for example) <code>man EVP_PKEY_set1_RSA</code> gives you the same man page as <code>man EVP_PKEY_set1_DSA</code>.