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

[Paul Berry]

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.


> +
> +<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?


>
>  <h2>Marking a commit as a candidate for a stable branch</h2>
>
> --
> 1.7.11.7
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/mesa-dev/attachments/20121219/1eef2284/attachment.html>