Help:Style Guide

From OpenGL.org
Jump to: navigation, search

The Style Guide describes the formatting style for the OpenGL Wiki.

Basics

For titles, naming conventions, introductory sections, and so forth, we default to Wikipedia's Manual of Style.

OpenGL specific

OpenGL has many versions, some removed functionality, and so forth. Thus, it is important to be clear at all times what version a particular page, section, or sentence is referring to.

The assumed default for the Wiki is OpenGL 3.3, core profile. That is, pages that discuss 3.3 core features do not need explicit text explaining that they are in fact 3.3 (or below) core features. They may use the feature infobox (see below), but they do not have to.

Page and section versioning

Pages and sections that discuss a specific OpenGL feature from a specific GL version should use the {{infobox feature}} template to describe the feature. It should specify the specific version that functionality became core in (if it never became core at all, then "version=" should be used to prevent the writing of a version), what extensions exposed that functionality, and so forth. Details for how to use the template are available on the template's page.

Any extensions should always provide a link to the extension specification, preferably with the {{extref}} template. Core extensions should be labeled as such with the "core_extension=" directive. You must look at the extension spec to find out. If it's defines or functions end in ARB, then it's not a core extension. If it has no defines or functions (like ARB_arrays_of_arrays), then you can decide for yourself if it is core or not.

This template should be used for page or section headers only. Do not use it in the middle of a section. If you need to state that a sentence or paragraph pertains to a version or extension, use {{require}} template.

When using the feature infobox in sections, they can sometimes overlap with code blocks, later section headers, and the like. To prevent this, you can use the {{clear float}} template right before whatever might overlap with an infobox.

Inline versioning

Sometimes, it is useful to state that some functionality exists in a later version or an extension. And a section break would be disruptive to the flow of text. Sometimes, a mention of a feature with a link is sufficient.

The goal here is to simply be as descriptive as possible. If the link goes to a page/section with a nice infobox right there explaining where it comes from, then there is no need to explicitly state version and/or extension (though it would still be nice). If there is no such link, then the text should clearly state what OpenGL version and/or extension the stated functionality comes from.

Non-core functionality

Functionality that was removed from core OpenGL can be discussed. But it must be very clearly labeled as such. The {{deprecated}} template should be used to mark pages or sections that discuss removed functionality. You should avoid inline discussions of removed functionality where possible; they should be relegated to their own section on the page.

FAQs

Note that the various FAQ pages and the like do not have to conform too much to this standard

Inline elements

There are a number of very useful formatting templates specific to this OpenGL wiki. Please use them when writing your text.

Of particular interest is the {{apifunc}} template, which links directly to the documentation of the core OpenGL 4.4 functions.