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

[Kenneth Graunke]

On Wednesday, May 18, 2016 1:12:29 PM PDT Ian Romanick wrote:
> 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."
> +    */

I've always done:

/* ...something something OpenGL...:
 *
 * "Some quoted text from the specification.  More quoted text.  Yet
 *  more quoted text.  Still more quoted text.  Multiple lines of quoted
 *  text get indented so they line up with the text, not the open quote."
 */

I don't care for the four space indent (it just gives you less space),
and I think it looks nicer if the opening quote is offset by 1 so that
the actual quoted text lines up.  It's just something I've always done.

Having more consistency on the first line seems like a good idea,
and I'm fine with what you proposed.

> +</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:
> 

Heh :) Nice.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20160518/3b29de9b/attachment.sig>