Difference between revisions of "Guidelines for Manual Page Authors"
(Initial draft guidelines) |
(no one edits the pages here and we will be removing them, so update the advice on how to submit man page changes) |
||
| (One intermediate revision by one other user not shown) | |||
| Line 1: | Line 1: | ||
| − | + | OpenSSL Manual pages are included in the [https://github.com/openssl/openssl/tree/master/doc main source tree]. Contributions and corrections to the Manual pages are welcomed and encouraged by opening an [https://www.openssl.org/community/#bugs issue on GitHub] | |
| − | + | However, some guidelines need to be considered when writing or amending these pages. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| + | ==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: | 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 | * Linux/Unix style "man" pages | ||
* HTML docs | * 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 | + | 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: | The different headings shown in each page do vary slightly. Generally you should at least include the following: | ||
| Line 61: | Line 33: | ||
==Linking== | ==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 | + | 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 Evp(3) or Bio(3). |
Latest revision as of 15:40, 8 March 2018
OpenSSL Manual pages are included in the main source tree. Contributions and corrections to the Manual pages are welcomed and encouraged by opening an issue on GitHub
However, some guidelines need to be considered when writing or amending these pages.
Manual Page Content[edit]
Manual pages are written in the POD documentation language. A guide to POD syntax is available 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:
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[edit]
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 Evp(3) or Bio(3).
