#pragma section-numbers off
#pragma camelcase off
#acl All:read

= Style Guide: Code Examples =
All [[SGWikiBasics#api|API pages]] in this wiki contain a section for code examples.  This guide provides instructions for adding your own content to the Code Examples section of these pages.

'''The Code Examples section should provide simple examples of real-world applications of the API.'''

<<Anchor(ToC)>>
<<TableOfContents()>>

== General Guidelines ==
'''Please post code examples showing how you have used the API that may benefit other users.'''
 * Do not post anything that you do not have permission to post publicly.
 * Code examples should have adequate comments to make them clear and useful.
 * Please remember to keep it accurate, simple, and easy to understand.

~-[[#ToC|Return to Table of Contents]]-~

== Adding Your Code Examples ==
 1. Begin by going to the page you wish to edit and selecting <<Color2(blue,Edit (Text))>> or <<Color2(blue,Edit (GUI))>> in the left column to begin editing.
  {i} ~-Markup info provided here is specifically for use in the Text editor but should work in both.-~
 1. Scroll down in the edit window to the section that begins with {{{== Code Examples ==}}}.  Add your content below this heading following the conventions in this style guide.
 1. Find information relevant to your content in the style guide sections [[#formatting|below]] and apply the appropriate formatting as you create your content.
 1. Preview your work as you go by clicking <<Color2(blue,Preview)>> in the left column.  Preview often and any time you are unsure of formatting. 
  . ~-(Keep in mind that a few things (like [[SGWikiBasics#color2|Color2 text]]) don't preview exactly as they parse.)-~
 1. Save your work by clicking <<Color2(blue,Save Changes)>> in the left column after you are satisfied with your content and have filled in the Comment field under the editing box. 
For additional assistance with editing, saving, or wiki-appropriate markup see the [[SGWikiBasics|Wiki Basics]] Style Guide.

~-[[#ToC|Return to Table of Contents]]-~

<<Anchor(formatting)>>
== Formatting Your Code Examples ==

=== Location ===
||<( |3 30%>''If'' your code example is the __first on the page__||''Action'': Replace the following text with your code<<BR>>{{{You can add your code example here}}}||
||<<Color2(red,''Important!'')>> Do not change or remove any of the markup immediately above or below that line.||
||''Example'': [[SDL_StopTextInput]]()<<BR>> ~-(Code Examples were empty at the time this was selected.-~)||
||<( |4>''If'' there are __existing code examples__ on the page||''Action'': Add a new code box with your code to the end of the Code Examples section, or to a related grouping if there are existing code examples covering the same topic||
||''Markup'': Insert the following into the spot where your example will be located and place your content on the blank line between the markup:<<BR>>`{{{`{{{#!highlight cpp}}}<<BR>><<BR>>`}}}`||
||<<Color2(red,''Important!'')>> Do not change or remove any of the existing content.||
||''Example'': [[SDL_Init]]()||

~-[[#ToC|Return to Table of Contents]]-~

=== Using an Include ===
Since many functions commonly occur in programs as pairs or small groups of related functions, it may occasionally be appropriate to repeat the same code example on more than one page.

In general this is best accomplished by copying and pasting and keeping pages separate.  

Very occasionally it may be appropriate to use an [[SGWikiBasics#Includes|Include]] to link the pages together and automatically copy the example (and any future changes) from one "source" page to one or more other pages.

<<Color2(red,''Important!'')>> This should only be done if the code example:
  a. shows a fundamental use of all functions it is copied to
  a. is not repeating the same information as another existing example on any of the pages (no unnecessary redundancy)
  a. offers useful information to users on every page it is copied to

''If'' it is determined that an Include is the best way to go, please follow these guidelines:

''Action'': In addition to following the other guidelines in this style guide, also follow the general instructions found in the [[SGWikiBasics#Includes|Wiki Basics]] style guide to create the Include markup on each page.

''Action'': We are keeping a list of all pages using Includes for future reference.  In order to keep this list up to date, please email <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>> with a list of all pages that received the Include and what page was used as the source.  We appreciate your taking time for this extra step to help us keep our records accurate and useful.  Thank you!

~-[[#ToC|Return to Table of Contents]]-~




<<Include(SGWikiBasics, , , from="Start SG Include here.", to="##End SG Include here.")>>