Guidelines for Manual Page Authors

The Manual pages are different to all of the other pages on this wiki and can be identified by the name of the page having the "Manual:" prefix. These pages have been imported into the wiki from the documentation distributed with OpenSSL.

Updates to the OpenSSL documentation are automatically uploaded to the wiki and merged with any edits made by wiki contributors. Periodically updates made by wiki contributors will be packaged into a patch file and submitted to the OpenSSL development team for consideration for inclusion into the OpenSSL distribution.

Contributions and corrections to the Manual pages are welcomed and encouraged. However, some guidelines need to be considered when writing or amending these pages.

Manual Page Naming

If you are editing an existing page then you should not use the wiki to rename that page. If you need to rename a page then you should submit this as a patch to the OpenSSL project.

If you are creating a new page then all manual pages MUST have the following form: Manual:man-page-name(section), where "man-page-name" will typically be the same as the name of a function or application you are defining on the page. The section will either be (1) for all pages describing the openssl command line tool, or (3) for all pages describing libssl or libcrypto.

There are a small number of pages which do not define any functions/applications (e.g. see Manual:Crypto(3)). These are typically overview pages to introduce a whole collection of other pages, and should be given a name appropriate to the collection being introduced.

There are a handful of pages (3 at the time of writing) which are not in sections 1 or 3. The wiki cannot currently be used to create these pages. If you need to create such a page then you should submit it as a patch in the normal way.

Manual Page Mark Up

The Manual pages do not use standard wiki page mark up. Instead they use the POD documentation language. A guide to POD syntax is available here.

In addition to the standard POD syntax, an additional header section is needed on all POD files in the wiki. This header is used by the scripts that synchronise the OpenSSL distribution POD files with the wiki. The headers look as follows:

#This file is in POD format. Use POD syntax NOT Wiki syntax. All POD files must have this header - DO NOT EDIT
#Filename: crypto/crypto.pod
#Trailing Line Feeds: 1
#End of Header

If you are editing an existing manual page, do not edit anything in this header file section. If you are creating a new manual page then ensure that you insert the header section. You must provide a suitable filename of the form <lib name>/<man page name>.pod, where lib name is one of "apps", "ssl" or "crypto", and man page name is the same as the name of the manual page without the "Manual:" prefix, or the section "(1)" or "(3)" suffix.

Manual Page Content

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
• This wiki

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, or that the page will be accessed through this wiki site.

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:

EVP_PKEY_new, EVP_PKEY_free - private key allocation functions.

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) man EVP_PKEY_set1_RSA gives you the same man page as man EVP_PKEY_set1_DSA.

Linking

When writing manual page content consider how this page will be reached. This is particularly important for users accessing these pages through a web browser. It is no good having an excellent Manual page if no one can reach it! Ensure that there is a link to your page from other similar pages, and preferably from one of the "collection" pages such as Manual:Evp(3) or Manual:Bio(3).