This guide provides specific instructions for editing or adding your own content to each section of an Enumeration page in this wiki.
Enumeration pages should provide basic information about the SDL enumerations to allow users to most effectively utilize them in their projects.
Important note about Hints |
Please observe the following for all enumeration pages:
#pragma
, #acl
), DRAFT markup, etc.)-~ except:~-Return to Table of Contents-~
== Getting Started ==
1. Begin by going to the page you wish to edit and selecting
Edit (Text)
or
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(s) you want to edit. Add your content following the conventions in this style guide.
1. Find information relevant to your content in the style guide sections
below
and apply the appropriate formatting as you edit.
1. Preview your work as you go by clicking
Preview
in the left column. Preview often and any time you are unsure of formatting.
1. Save your work by clicking
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 assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>>.
~-Return to Table of Contents-~
Do not edit the Title.
The Title section consists of the page heading and its markup:
```= SDL_EnumerationName =```
For enumeration pages this is the name of the enumeration being described on the page and should match the address of the page.
Example: The page address ```https://wiki.libsdl.org/SDL_EventType``` should have matching title and describe the SDL_EventType structure.
If you believe a change is necessary please submit Feedback from that page or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>>.
~-Return to Table of Contents-~
=== Description === The Description section immediately follows the page title and does not have it's own heading.
'''Enumeration descriptions begin with:
```An enumeration of```'''
or very rarely
```A hint that specifies```
Note: Information presented in this section is meant to be limited. Extended description information for more complicated enumerations should be placed in the Remarks section instead.
Note: Exceptions to the basic description are very unusual. Follow established patterns in the wiki (based on similar pages which may be found by text search) whenever possible if an exception seems appropriate.
<( |2 30%>If the page describes __a hint__ rather than an enumeration |
Action: Use the alternate description ( |
Example: SDL_EventType, SDL_HINT_RENDER_SCALE_QUALITY |
|
<( |2 30%>If __another API page__ is referenced in the description |
Action: Be sure to hyperlink it and use () outside the link markup if it is a function. |
Example: ```SDL_FunctionName(), SDL_StructureName```, SDL_BlendMode |
|
<( 30%>If __a value on that page__ is referenced in the description |
Action: There is no special formatting for enumeration values since most are already in all caps and distinct enough. (This is different from function parameters or structure data values.) |
~-Return to Table of Contents-~
=== Table of Contents === Do not edit the Table of Contents.
The Table of Contents consists of the following markup and is generated automatically on the parsed page.
```<<TableOfContents()>>```
If you believe a change is necessary please submit Feedback from that page or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>>.
~-Return to Table of Contents-~
=== Values === The Values section provides basic information about each value in the enumeration and is presented in table format.
The basic format is as follows: ``` ||value1||description|| ||value2||description|| ... ||valueN||description|| ```
Markup: Use basic table markup. All text in the table is left-justified. Do not use bold.
Example: SDL_BlendMode, SDL_HintPriority, SDL_PowerState, SDL_WindowFlags
Action: There are a few content-dependent conventions we have chosen for consistency across pages. See the tables below for details.
<bgcolor="#EDEDED">General (whole table) |
|
<( |5 30%>If the value is __for internal use, deprecated, or unused__ (greyed out) |
Action 1: Place a text notation in parentheses at the end of the description (ie: |
Action 2: Make the text in the row grey by including the following, verbatim, in the first cell of the row between the starting table markup and the text: |
|
Note: Although a rare case, any other style markup for that row/cell should be included within the same set of angle brackets ( |
|
Markup: ``` |
<rowstyle="color: #808080;">value |
Example: SDL_EventType, SDL_LOG_CATEGORY |
|
<( |3 30%>If the value is specified as __read-only__ |
Action: Place the text notation |
Note: This also applies to the rare case that " |
|
Example: There are currently no enumeration examples of this. SDL_Surface, SDL_PixelFormat |
|
<( |3 30%>If __another API page__ is referenced and __the value is greyed out__ (see above) |
Action 1: DO NOT hyperlink the page in the table. |
Action 2: List the page, with a hyperlink, in the description and/or in the appropriate "Related" section at the bottom of the page, if appropriate. |
|
Example: There are currently no enumeration examples of this. SDL_Event |
|
<( |3 30%>If __another API page__ is referenced and __the value is not greyed out__ (see above) |
Action1: Be sure to hyperlink it and use () outside the link markup if it is a function. |
Action 2: List the page in the appropriate "Related" section at the bottom of the page, if appropriate. |
|
Example: There are currently no enumeration examples of this. SDL_Event, SDL_BlendMode |
|
<( |4 30%>If there are __important, distinct groups of values__ within the enumeration |
Action: Create sections by placing a full-width row with a grey background and centered, italics title above each group. |
Markup: Begin the row with empty table cells equal to the number of columns in the table -1 (ie: 1 empty cell for a 2 column table). Place the following markup in the last cell |
|
Note: This is a rare occurrence. Do not use sections unless they significantly improve the meaning, clarity, or usability of the information. |
|
Example: this table, SDL_AudioFormat, SDL_EventType |
|
<bgcolor="#EDEDED">Specific (description column) |
|
<( |3 30%>If __more than one statement__ must be included in the description |
Action: Separate them with a semi-colon (;) |
Note: This should be avoided whenever possible. See "If a __more detailed description__ is required to adequately explain a value" below for more details. |
|
Example: SDL_HintPriority, SDL_GLattr |
|
<( |4 30%>If a __more detailed description__ is required to adequately explain a value |
Action 1 : Append the following, verbatim, to the end of the brief description |
Action 2: Place the more detailed information in the Remarks section. |
|
Action 3: See "If the __Remarks section is large__" below for more details. |
|
Example: SDL_PixelFormatEnum, SDL_GLattr |
|
<( |4 30%>If the __Remarks section is large__ |
Action 1: Create an anchor immediately before the additional comments you are adding to the Remarks section. |
Markup: Use ``````, where |
|
Action 2: Modify the Remarks link in the parameter description (see Action 1 in "If a __more detailed description__ is required to adequately explain a value" above) to the following: |
|
Example: SDL_GLattr, SDL_PixelFormatEnum |
|
<( |3 30%>If there is __no relevant description text__ |
Action: It is acceptable to leave the description cell blank, although it is preferable to put some information there even if it is redundant with the field name or otherwise does not really provide any novel information. |
Note: If none of the values has relevant description text it is acceptable to remove the entire description column, but this should be done with caution and only extremely rarely. |
|
Example: SDL_PixelFormatEnum, SDL_AudioStatus, SDL_HINT_RENDER_DRIVER |
~-Return to Table of Contents-~
=== Code Examples === The Code Examples section is meant to contain simple, meaningful examples of how to use the enumeration in a program.
This is one of the few sections that is intended to grow and adjust as users discover more information about an enumeration that would be helpful to share with other users.
For the most part the contents of the Code Examples section will be user-generated and this section will remain as-is until users input their examples.
Please see the Code Examples Style Guide for details on editing this section.
~-Return to Table of Contents-~
=== Remarks === The Remarks section is meant to contain additional information that did not fit in the other sections as well as comments regarding the behavior and use of the enumeration in real-world applications.
This is one of the few sections that is intended to grow and adjust as users discover more information about how an enumeration behaves under different circumstances.
For the most part the contents of the Remarks section will be user-generated and this section will remain as-is until users input their comments.
Note: This is __not__ an appropriate place to post questions, suggestions, bugs, or commentary. Please use the other communication channels available to you, especially the forums and mailing lists, for these types of remarks.
Please see the Remarks Style Guide for details on editing this section.
~-Return to Table of Contents-~
=== Related Enumerations === The Related Enumerations section provides a list of enumerations specifically referenced by the enumeration or otherwise closely related to it. This section is very rarely used.
This list __should__ include:
This list __should not__ include:
Markup: Each line should begin with a single blank space and a period followed by the enumeration name enclosed in double brackets to create a hyperlink.
```
.
SDL_EnumerationName
.
SDL_EnumerationName
```
<( 30%>If there is __more than one enumeration__ in the list |
Action: List the enumerations in alphabetical order. |
<( |2 30%>If there are __no related enumerations__ |
Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant. |
Note: It is common for this section to be empty and removed from the page. |
Example: SDL_Keycode, SDL_Scancode
~-Return to Table of Contents-~
=== Related Structures === The Related Structures section provides a list of structures (or unions) specifically referenced by the enumeration or otherwise closely related to it.
This list __should__ include:
This list __should not__ include:
Markup: Each line should begin with a single blank space and a period followed by the structure name enclosed in double brackets to create a hyperlink.
```
.
SDL_StructureName
.
SDL_StructureName
```
<( 30%>If there is __more than one structure__ in the list |
Action: List the structures in alphabetical order. |
<( 30%>If the structure is __a member of the SDL_Event union__ |
Action: Include SDL_Event in this section of the page. |
<( |2 30%>If there are __no related structures__ |
Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant. |
Note: It is common for this section to be empty and removed from the page. |
Example: SDL_AudioFormat, SDL_BlendMode, SDL_PixelFormatEnum
~-Return to Table of Contents-~
The Related Functions section provides a list of functions specifically associated with that enumeration or otherwise closely related to it.
This list __should__ include:
This list __should not__ include:
Markup: Each line should begin with a single blank space and a period followed by the function name enclosed in double brackets to create a hyperlink.
```
.
SDL_FunctionName
.
SDL_FunctionName
```
<( 30%>If there is __more than one function__ in the list |
Action: List the functions in alphabetical order. |
<( 30%>If there are __no related functions__ |
Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant. |
Example: SDL_AudioStatus, SDL_HintPriority, SDL_TextureAccess
~-Return to Table of Contents-~
<tablewidth="100%" >Important! |
The Footer section consists of a horizontal rule followed by two links separated by a comma.
Markup: ```
CategoryEnum, CategoryHeader ```
CategoryEnum
is the same for every enumeration page and CategoryHeader
is enumeration-specific with Header
varying based on the header file containing the enumeration (see below).
Important! Category names do not always match the header file name. Please consult the following table for the correct name to use so the enumeration will appear in the correct list(s).
Action 1: Do not edit the CategoryEnum
link!
Action 2: The ```CategoryHeader``` link may be edited if the page still says (as on a new page) or if the structure has been relocated to another header (very rare).
Important! There are a few exceptions to this rule (pages with a category name that does not match their header file according to the table). These have been determined by the SDL team. Please do not change an existing page's category name simply because it does not match its header file. If you are concerned that a name is incorrect please submit your concern in the forums or mailing lists or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>> to confirm the change first.
Markup: Replace CategoryHeader
with the appropriate category name from the table that follows, or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>> to find out what category name to use if you are unsure or if the category appears to be missing.
<rowbgcolor="#EDEDED">Header File Containing the Structure* |
Corresponding Category Name |
SDL.h |
CategoryInit |
SDL_assert.h |
CategoryAssertions |
SDL_atomic.h |
CategoryAtomic |
SDL_audio.h |
CategoryAudio |
SDL_clipboard.h |
CategoryClipboard |
SDL_compat.h |
CategoryCompat |
SDL_cpuinfo.h |
CategoryCPU |
SDL_endian.h |
CategoryEndian |
SDL_error.h |
CategoryError |
SDL_events.h |
CategoryEvents |
SDL_haptic.h |
CategoryForceFeedback |
SDL_hints.h |
CategoryHints |
SDL_joystick.h |
CategoryJoystick |
SDL_keyboard.h |
CategoryKeyboard |
SDL_keycode.h |
CategoryKeyboard |
SDL_loadso.h |
CategorySharedObject |
SDL_log.h |
CategoryLog |
SDL_mouse.h |
CategoryMouse |
SDL_mutex.h |
CategoryMutex |
SDL_pixels.h |
CategoryPixels |
SDL_platform.h |
CategoryPlatform |
SDL_power.h |
CategoryPower |
SDL_quit.h |
CategoryEvents |
SDL_rect.h |
CategoryRect |
SDL_render.h |
CategoryRender |
SDL_rwops.h |
CategoryIO |
SDL_scancode.h |
CategoryKeyboard |
SDL_surface.h |
CategorySurface |
SDL_syswm.h |
CategorySWM |
SDL_thread.h |
CategoryThread |
SDL_timer.h |
CategoryTimer |
SDL_version.h |
CategoryVersion |
SDL_video.h |
CategoryVideo |
~-*Some exceptions exist. See above.-~ |
~-Return to Table of Contents-~
This section contains details for special formatting circumstances that are best described separately from the average enumeration page. In general these guidelines should be used in conjunction with the above.
In some cases Hints are formatted slightly differently than enumerations. Use the following formatting specifics in addition to those listed above for all CategoryHints pages::
Action 1: All Hint pages contain an additional section not present on enumeration pages - Default
Markup: Add the following section to all CategoryHints
pages between the Values and Code Examples sections.
```
```
By default...
Example: SDL_HINT_FRAMEBUFFER_ACCELERATION, SDL_HINT_RENDER_SCALE_QUALITY
Action 2: The Footer section of a Hint page follows the same guidelines as for an enumeration page with the following differences:
Note: To date there are no Related Enumerations, Related Structures, or Related Functions listed on any Hint page. Should there be, follow the same general guidelines as for enumerations.
~-Return to Table of Contents-~
<<Include(SGWikiBasics, , , from="Start SG Include here.", to="##End SG Include here.")>>