Help:Formatting Templates

From OpenGL.org
Jump to: navigation, search

Formatting Templates are MediaWiki templates that have been created to make it easier to express certain things, or to describe features of an article or section. There are several categories of templates that you may wish to use:

Information Boxes

These templates create the offset boxes that describe an article in some way. They are:

  • {{infobox feature}}: These denote articles or sections that describe an OpenGL feature bound to a specific version, OpenGL extension, or other such. It has options for an entire array of history for that extension, from vendor-specific extensions to the version where it was adopted into core. You can even discuss features that were removed and remove the "core in version" line, to let people know when they were removed.
  • {{pipeline float}}: This is used for articles that explain stages of the OpenGL pipeline in detail. It makes it easy to jump from pipeline to pipeline. If an infobox needs to be on the page, then it should come first, and the infobox should be stacked with the pipeline (see below).

There are some useful tools for handling info-boxes:

  • {{clear float}}: Normally, infoboxes float to the right side; other kinds of boxes (like code blocks, section headers, and the like) will overlap with them. If you use this template right before a code block, then the code block will be pushed below any such floats. Remember: just because it doesn't overlap on your monitor doesn't mean that it won't overlap on someone else's.
  • {{stack|}}: This template contains a list of boxes that should all float as a single unit. This is useful for combining an infobox with one of the other floats.

Admonitions

Admonitions are paragraphs that are offset from the main flow of the text, usually to indicate a notification of some kind. There are several admonition templates. They all take one unnamed (positional) parameter: the paragraphs of text to offset.

  • {{note}}: Used for general notes.
    • {{legacy note}}: Used for notations that are specifically about deprecated and removed functionality, or simply old extensions or behaviors that may no longer be applicable for modern use. The text in these admonitions is not for current hardware or current core OpenGL versions.
  • {{warning}}: Used for warnings; typically specific "gotchas" that a user may encounter.
  • {{comp note}}: Used for information about the compatibility profile.
  • {{recommend}}: Used for recommendations about how to use some OpenGL feature.
  • {{plat note}}: Used for platform-specific annotations. You must provide two parameters; the first is a string defining the platform. So you would do {{plat note|AMD|AMD-specific issue.}}.

Functions

When writing a function definition, use {{funcdef}}. It uses better styling than preformatted text:

uint atomicCounter(atomic_uint c​);

Instead of:

uint atomicCounter(atomic_uint c​);

Inline Formatting

These templates are useful for doing inline formatting of various code.

  • {{apifunc}}: Use this when writing API functions. It will automatically link to the documentation for them. Only works for APIs already in the wiki (4.4 core).
  • {{enum}}: Use this instead of <code></code> tags for enumerators.
  • {{param}}: Use this instead of '' '' for names of function parameters.
  • {{code}}: Use this instead of <code></code> tags for inline bits of code. This makes it easier to change the formatting of these tags as needed.
  • {{extref}}: Use this to link to extensions.
  • {{require}}: Use this to have inline OpenGL version and extension citations. This is for when you want to say that something needs a GL version or an extension.

Alerts

Alerts are templates that specify that something is wrong with a section or article. These should be used with care, and they should always be coupled with a discussion on the appropriate talk page. And you should only ever use them if you do not have the time/knowledge to fix the problem yourself.

  • {{stub}}: Put this on a page that is short and incomplete. It denotes pages that need work.
  • {{cleanup}}: Used when a section or article has formatting that is in need of repair. Do this only when you don't have the time/knowledge to repair it yourself.
  • {{inaccurate}}: Used when a section or article contains substantial factual inaccuracies. Only use this if you don't have the time/knowledge to repair it yourself.
  • {{todo}}: Used when you are leaving a section deliberately blank, to come back in later to add information.
  • {{missing}}: Used when a particular section or article contains substantial on-topic information that is missing, and without links to pages where that information is adequately described. Use this only if you don't have the time/knowledge to repair it yourself.

Miscellaneous

These are useful templates, but don't fall under a general category.

  • {{current version}}: The current OpenGL version number. Use this anywhere in place of the current version.
  • {{main}}: Use this at the top of a section if that section is a short description for something that has a longer, more indepth article.
  • {{deprecated}}: Used when a section or article is covering material that has been deprecated and removed in the current core version of OpenGL. It looks like an Alert, but it isn't.