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

[Chad Versace]

On 12/19/2012 09:56 PM, Paul Berry wrote:
> On 19 December 2012 15:46, Ian Romanick <idr at freedesktop.org> wrote:
> 
>> From: Ian Romanick <ian.d.romanick at intel.com>
>>
>> Signed-off-by: Ian Romanick <ian.d.romanick at intel.com>
>> Cc: Paul Berry <stereotype441 at gmail.com>
>> Cc: Brian Paul <brianp at vmware.com>
>> ---
>>  docs/devinfo.html | 42 ++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 42 insertions(+)
>>
>> diff --git a/docs/devinfo.html b/docs/devinfo.html
>> index 8f4aeef..eb4c897 100644
>> --- a/docs/devinfo.html
>> +++ b/docs/devinfo.html
>> @@ -155,6 +155,48 @@ of <tt>bool</tt>, <tt>true</tt>, and
>>  src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
>>  </p>
>>
>> +<p>
>> +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, please use one of the following
>> +formats.
>> +</p>
>> +
>> +<p>
>> +Text quoted from the core OpenGL or OpenGL ES specifications:
>> +</p>
>> +
>> +<pre>
>> +   /* Page AA (page BB of the PDF) in section C.D.E of the OpenGL F.G
>> +    * specification says:
>> +    *
>> +    *     "Some quoted text from the specificiation"
>> +    */
>> +</pre>
>>
> 
> The OpenGL specs since version 3.2 come in four flavours:
> - glspecN.core.YYYYMMDD.pdf
> - glspecN.core.YYYYMMDD.withchanges.pdf
> - glspecN.compatibility.YYYYMMDD.pdf
> - glspecN.compatibility.YYYYMMDD.withchanges.pdf
> 
> Since these four documents don't in general have matching page numbers, I
> think we should make a recommendation as to which one to quote from.  My
> preference: glspecN.compatibility.YYYYMMDD.withchanges.pdf, since it
> contains information about the deltas both from core to compatibility and
> from one version to the next, so it's the most likely to tip us off to
> subtle API or version dependencies that we need to be careful about.

An alternative is to drop the reference to page numbers and only refer to
the section.

>> +
>> +<p>
>> +Text quoted from the GLSL or GLSL ES ES specifications:
>> +</p>
>> +
>> +<pre>
>> +   /* Page AA (page BB of the PDF) in section C.D.E of the GLSL F.G
>> +    * specification says:
>> +    *
>> +    *     "Some quoted text from the specificiation"
>> +    */
>> +</pre>
>> +
>> +<p>
>> +Text quoted from an extension specifications:
>> +</p>
>> +
>> +<pre>
>> +   /* Section C.D.E of the GL_EXT_foo_bar specification says:
>> +    *
>> +    *     "Some quoted text from the specificiation"
>> +    */
>> +</pre>
>>
> 
> My impression is that most extension specs aren't divided into numbered
> sections like this--instead the sections tend to be labeled things like
> "Overview", "Issues", or "Additions to Chapter N...".  Since extension
> specifications are text files, perhaps it would be better to quote by line
> number?

Young extension specs sometimes receive updates, which shuffles the line
numbers.

Since extension specs are small text files, I don't think it's necessary
to refer to a location in the spec. If someone needs to look up the
quoted text, then a simple text search will instantaneously find it.