Difference between revisions of "Help:Style Guide"

From OpenGL.org
Jump to: navigation, search
(Creating a stub.)
 
(Rough draft of style guide.)
Line 1: Line 1:
The '''Style Guide''' describes the formatting style for the OpenGL Wiki. Much of this is taken from Wikipedia's Manual of Style, but some is original.
+
The '''Style Guide''' describes the formatting style for the OpenGL Wiki.
 +
 
 +
== Basics ==
 +
 
 +
For titles, naming conventions, introductory sections, and so forth, we default to [http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style 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 [[Template:infobox feature|<nowiki>{{infobox feature}}</nowiki> 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. [[OpenGL_Extensions#Core_Extensions|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.
 +
 
 +
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 put this line right before what it would overlap with, to prevent overlapping:
 +
 
 +
<nowiki><br style="clear: both" /></nowiki>
 +
 
 +
=== 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 [[Template:deprecated|<nowiki>{{deprecated}}</nowiki> 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 [[Help:Formatting_Templates|very useful formatting templates specific to this OpenGL wiki]]. Please use them when writing your text.
 +
 
 +
Of particular interest is the [[Template:apifunc|<nowiki>{{apifunc}}</nowiki> template]], which links directly to the documentation of the core OpenGL 4.3 functions.
  
 
{{stub}}
 
{{stub}}

Revision as of 11:56, 5 September 2012

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. 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.

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 put this line right before what it would overlap with, to prevent overlapping:

<br style="clear: both" />

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.3 functions.