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

Wed May 18 22:18:16 UTC 2016

On 05/18/2016 02:21 PM, Kenneth Graunke wrote:
> 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.

I find this a little surprising... since you just give me a R-b on a
patch that reformats spec quotations in this way. :)  It's also the
existing documented style.

Spec quotes are usually pretty short.  Is having less space really an
issue?  When we first started using this style (this patch originally
came from 2012, and the use predates even that), we were trying to mimic
MLA style for block quotes.  There were some intentional (and
unintentional) deviations, but that was the main motivator.  It's a
pretty established style, after all.

The main intentional deviation is that MLA only uses the block quote
format when the quotation is four or more lines in the document.
There's usually formatting that needs to be preserved in spec
quotations, so mashing things into fewer lines doesn't really make
sense.  Also... having two different rules to apply conditionally can
only lead to problems.

The unintentional deviation is that MLA block quotes don't have
quotation marks around them.  I literally never noticed that until I
looked up the style guide about 5 minutes ago.  I'm not married to
keeping the quotation marks.

> 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: 181 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20160518/fea30bbf/attachment.sig>