Difference between revisions of "Guidelines for Manual Page Authors"

From OpenSSLWiki
Jump to navigationJump to search
m (Added link to FAQ on submitting patches.)
(no one edits the pages here and we will be removing them, so update the advice on how to submit man page changes)
 
Line 1: Line 1:
−
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.
+
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]
  
−
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.
+
However, some guidelines need to be considered when writing or amending these pages.
  
−
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 Content==
−
 
 
−
==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: <code>Manual:''man-page-name''(''section'')</code>, 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 [http://www.openssl.org/support/faq.html#MISC3 submit it as a patch] in the normal way. '''Note''': patches and other material sent to [http://rt.openssl.org/ RT] via ''rt@openssl.org'' are usually ignored.
 
−
 
 
−
==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 [http://perldoc.perl.org/perlpod.html here].
+
Manual pages are written in the POD documentation language. A guide to POD syntax is available [http://perldoc.perl.org/perlpod.html 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:
 
−
 
 
−
<pre>
 
−
#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
 
−
</pre>
 
−
 
 
−
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 <code>&lt;lib name&gt;/&lt;man page name&gt;.pod</code>, where <code>lib name</code> is one of "apps", "ssl" or "crypto", and <code>man page name</code> 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:
 
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
−
* 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.
+
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 60: 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 [[Manual:Evp(3)]] or [[Manual:Bio(3)]].
+
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).

Retrieved from "https://wiki.openssl.org/index.php?title=Guidelines_for_Manual_Page_Authors&oldid=2643"