[Mesa-dev] [PATCH] docs: Document spec quoting practices

[Ian Romanick]

From: Ian Romanick <ian.d.romanick at intel.com>

v2: Remove extra "ES" from "GLSL ES ES".  Noticed by Chris Forbes.

v3: Many updates based on (very old) feedback from Paul Berry and (more
recent) observation of what is most commonly done in the code base.

Signed-off-by: Ian Romanick <ian.d.romanick at intel.com>
Cc: Brian Paul <brianp at vmware.com>
---
 docs/devinfo.html | 84 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 76 insertions(+), 8 deletions(-)

diff --git a/docs/devinfo.html b/docs/devinfo.html
index 8ebf80f..fc0001b 100644
--- a/docs/devinfo.html
+++ b/docs/devinfo.html
@@ -81,18 +81,86 @@ Multi-line comment:
     * never used before, allocate a buffer object now.
     */
 </pre>
-We try to quote the OpenGL specification where prudent:
+
+<p id="spec_quotes">
+It is often useful to quote sections from relevant specifications near code
+that implements part of the spec.  In order to make it easier to find such
+quotations in the code (via grep and friends) and to find the quoted text in
+the specifications, use one of the following formats.
+</p>
+
+<p>
+Text quoted from the core OpenGL, OpenGL ES, GLSL, GLSL ES, GLX, or EGL
+specifications should be formatted as:
+</p>
+
+<pre>
+   /* Section ##.##.## (Section Name) of the OpenGL #.# spec says:
+    *
+    *     "Some quoted text from the specificiation.  More quoted text.  Yet
+    *     more quoted text."
+    */
+</pre>
+
+<p>
+Quotations from the GLSL or GLSL ES specifications should be attributed to
+"GLSL" or "GLSL ES", respectively (i.e., <em>not</em> the full name "OpenGL
+Shading Language" or "OpenGL ES Shading Language").  Note: There are a total
+of 5 spaces between the <tt>*</tt> and the <tt>"</tt> starting the quotation.
+</p>
+
+<p>
+The practice used to be to include the page number in the quotation.  This
+posed several problems.  First, the page number printed on the page and the
+page number in the specification PDF never match.  For this reason both page
+numbers were quoted, and it was very annoying.  Second, from version to
+version of the specification the page number could change quite
+significantly.  This made it difficult to detect when the specification had
+changed.  Differences between the Core Profile and Compatibility Profile
+specifications made this issue even worse.
+</p>
+
+<p>
+Spec quotations from OpenGL 3.2 or later should also include the Profile being
+quoted.  For example, a quote from the Core Profile spec would read:
+</p>
+
+<pre>
+   /* Section ##.##.## (Section Name) of the OpenGL #.# (Core Profile) spec
+    * says:
+    *
+    *     "Some quoted text from the specificiation.  More quoted text.  Yet
+    *     more quoted text."
+    */
+</pre>
+
+<p>
+Text quoted from an extension specifications:
+</p>
+
+<pre>
+   /* The EXT_foo_bar spec says:
+    *
+    *     "Some quoted text from the specificiation"
+    */
+</pre>
+
+<p>
+Since extension specifications are generally small, it is usually easy enough
+to find the quoted text without including a section number.  One exception to
+that is the issues section.  Even careful spec readers may miss things in the
+issues section, so it is helpful to draw attention to quotations from the
+issues.
+</p>
+
 <pre>
-   /* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
+   /* The EXT_foo_bar spec says:
     *
-    *     "An INVALID_OPERATION error is generated for any of the following
-    *     conditions:
+    *     "Issues:
     *
-    *     * <length> is zero."
+    *     (#) Got an issue?
     *
-    * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
-    * (30.10.2014) also says this, so it's no longer allowed for desktop GL,
-    * either.
+    *       RESOLVED: Have a tissue."
     */
 </pre>
 Function comment example:
-- 
2.5.5