TXP Defined Function Editing Reference
From Textbook
Contents |
About Editing Function Pages
All function pages should have a similar look and feel to them to make them more accessible and to make all the information easily accessible.
This page describes the style that these function pages in the wiki should be made.
Page Editing
Header
Each of the function pages as well as the function index pages has a small link trail header section for easier navigation. This should be the first thing on any of the pages, and should be the following:
<div class="linktrail">[[en/Main Page]] | [[TXP Defined Function Editing Reference | Function Editing Instructions ]] | [[TXP Defined Functions (By File)]] | [[TXP Defined Functions | TXP Defined Functions (Alphabetically)]]</div>
Sections
The page is broken down into a few sections for simplicity. These are as follows.
- About This Page
- General Information
- Name
- Purpose
- Location In Source Code
- This Page Last Updated
- Information Retrieved From
- Parameters
- Examples
"About This Page" Section
This section is the first one, and it's purpose is to notify readers that the information on any given function may not be completely up to date, so it is the reader's responsibility to check the development browser for the final status on the code. This is stated on function pages as follows:
This page is a reference for a function in the core code.<br /> Please note that it is possible that below information has changed since the last update, and as such, you should be sure to check out the [http://dev.textpattern.com/browser/ development browser] for the final definitive information about this function.
"General Information" Section
This section is to give some general information about the page and the function
"Name" Section
This is simply the name of the function. This is as the wiki format does not allow for pages to have a lower case letter as the first letter of a page. For example,FuncName()
"Purpose" Section
This section is to descirbe what purpose this function has in the core code. It should include information as to whether or not it is a function of a class, whether or not is it deprecated, and any relevant information that can be gleaned from the in code comments.
As well, if this function was added to the core after the latest public release (currently 4.0.4), this should be noted, as well as when it was added to the core along with a link to that changeset in the development browser. An example of this is as follows:
This function was added to the core after the release of 4.0.4, in [http://dev.textpattern.com/changeset/1972 revision 1972].
"Location In Source Code" Section
This section is simply to give a reference as to where this function exists in the code. This information should be a link the the file page, along with a line number. For example,
[[textpattern/lib/classTextile.php File | textpattern/lib/classTextile.php]] :: line ##
"This Page Last Updated" Section
This section is to let the reader know how relevant this information actually is. If the page hasn't been updated in a year, the information is not going to be terribly relevant, more likely than not. This should be done with the wiki syntax for adding your signature (that is, ~~~~).
"Information Retrieved From" Section
This section is to let the reader know where this information was retreived from. This should normally be one the the phpxref sites that exist for Textpattern. A current version is maintained here.
"Parameters" Section
This section is just a list (unordered) of the parameters that the function takes. Each parameter should be wrapped in <code> tags.
"Examples" Section
This section is for listing some example usages of the function. If no standalone uses of this function exist, then this should be stated.
Putting It All Together
The following is a basic page template for any given function. It follows the above formatting for function pages.
<div class="linktrail">[[en/Main Page]] | [[TXP Defined Function Editing Reference | Function Editing Instructions ]] | [[TXP Defined Functions (By File)]] | [[TXP Defined Functions | TXP Defined Functions (Alphabetically)]]</div> == About This Page == This page is a reference for a function in the core code.<br /> Please note that it is possible that below information has changed since the last update, and as such, you should be sure to check out the [http://dev.textpattern.com/browser/ development browser] for the final definitive information about this function. == General Information == === Name === <code>FuncName()</code> === Purpose === ''(needed)''<br /> (IF NECESSARY) This function was added to the core after the release of 4.0.4, in [http://dev.textpattern.com/changeset/1972 revision 1972]. === Location in Source Code === [[textpattern/lib/classTextile.php File | textpattern/lib/classTextile.php]] :: line ## === This Page Last Updated === ~~~~ === Information Retrieved From === http://www.ako-k.com/txpref/textpattern/lib/classTextile.php.source.html == Parameters == * <code>$param</code> == Examples == ''(needed)''
