<div dir="ltr">On 4 January 2013 16:09, Ian Romanick <span dir="ltr"><<a href="mailto:idr@freedesktop.org" target="_blank">idr@freedesktop.org</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> <div class="im">On 12/19/2012 09:56 PM, Paul Berry wrote:<br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im"> On 19 December 2012 15:46, Ian Romanick <<a href="mailto:idr@freedesktop.org" target="_blank">idr@freedesktop.org</a><br></div><div class="im"> <mailto:<a href="mailto:idr@freedesktop.org" target="_blank">idr@freedesktop.org</a>>> wrote:<br> <br> From: Ian Romanick <<a href="mailto:ian.d.romanick@intel.com" target="_blank">ian.d.romanick@intel.com</a><br></div> <mailto:<a href="mailto:ian.d.romanick@intel.com" target="_blank">ian.d.romanick@intel.<u></u>com</a>>><br> <br> Signed-off-by: Ian Romanick <<a href="mailto:ian.d.romanick@intel.com" target="_blank">ian.d.romanick@intel.com</a><br> <mailto:<a href="mailto:ian.d.romanick@intel.com" target="_blank">ian.d.romanick@intel.<u></u>com</a>>><br> Cc: Paul Berry <<a href="mailto:stereotype441@gmail.com" target="_blank">stereotype441@gmail.com</a><br> <mailto:<a href="mailto:stereotype441@gmail.com" target="_blank">stereotype441@gmail.<u></u>com</a>>><br> Cc: Brian Paul <<a href="mailto:brianp@vmware.com" target="_blank">brianp@vmware.com</a> <mailto:<a href="mailto:brianp@vmware.com" target="_blank">brianp@vmware.com</a>>><div><div class="h5"><br> ---<br> docs/devinfo.html | 42 ++++++++++++++++++++++++++++++<u></u>++++++++++++<br> 1 file changed, 42 insertions(+)<br> <br> diff --git a/docs/devinfo.html b/docs/devinfo.html<br> index 8f4aeef..eb4c897 100644<br> --- a/docs/devinfo.html<br> +++ b/docs/devinfo.html<br> @@ -155,6 +155,48 @@ of <tt>bool</tt>, <tt>true</tt>, and<br> src/mesa/state_tracker/st_<u></u>glsl_to_tgsi.cpp can serve as examples.<br> </p><br> <br> +<p><br> +It is often useful to quote sections from relevant specifications near<br> +code that implements part of the spec. In order to make it easier to<br> +find such quotations in the code (via grep and friends) and to find the<br> +quoted text in the specifications, please use one of the following<br> +formats.<br> +</p><br> +<br> +<p><br> +Text quoted from the core OpenGL or OpenGL ES specifications:<br> +</p><br> +<br> +<pre><br> + /* Page AA (page BB of the PDF) in section C.D.E of the OpenGL F.G<br> + * specification says:<br> + *<br> + * "Some quoted text from the specificiation"<br> + */<br> +</pre><br> <br> <br> The OpenGL specs since version 3.2 come in four flavours:<br> - glspecN.core.YYYYMMDD.pdf<br> - glspecN.core.YYYYMMDD.<u></u>withchanges.pdf<br> - glspecN.compatibility.<u></u>YYYYMMDD.pdf<br> - glspecN.compatibility.<u></u>YYYYMMDD.withchanges.pdf<br> <br> Since these four documents don't in general have matching page numbers,<br> I think we should make a recommendation as to which one to quote from.<br> My preference: glspecN.compatibility.<u></u>YYYYMMDD.withchanges.pdf, since it<br> contains information about the deltas both from core to compatibility<br> and from one version to the next, so it's the most likely to tip us off<br> to subtle API or version dependencies that we need to be careful about.<br> </div></div></blockquote> <br> Except that we don't implement compatibility profiles. :)</blockquote><div><br></div><div>True, we don't, but we do implement legacy features in 3.0 and earlier contexts. I've found the compatibility doc to be a more useful reference, since it mentions the legacy features.<br> </div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> I agree that in cases where a profile may be involved, the reference should call it out. You're thinking it should look like:<div class="im"> <br> <br> /* Page AA (page BB of the PDF) in section C.D.E of<br></div> * glspecN.compatibility.<u></u>YYYYMMDD.withchanges.pdf says:<br> *<div class="im"><br> * "Some quoted text from the specificiation"<br></div> */<br> <br> That's very specific, but it's also kind of ugly to look at. Hmm...<div><div class="h5"><br> <br> <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> +<br> +<p><br> +Text quoted from the GLSL or GLSL ES ES specifications:<br> +</p><br> +<br> +<pre><br> + /* Page AA (page BB of the PDF) in section C.D.E of the GLSL F.G<br> + * specification says:<br> + *<br> + * "Some quoted text from the specificiation"<br> + */<br> +</pre><br> +<br> +<p><br> +Text quoted from an extension specifications:<br> +</p><br> +<br> +<pre><br> + /* Section C.D.E of the GL_EXT_foo_bar specification says:<br> + *<br> + * "Some quoted text from the specificiation"<br> + */<br> +</pre><br> <br> <br> My impression is that most extension specs aren't divided into numbered<br> sections like this--instead the sections tend to be labeled things like<br> "Overview", "Issues", or "Additions to Chapter N...". Since extension<br> </blockquote> <br></div></div> This may be a case of under-specifying what I meant. In this context, by "Section C.D.E" I meant the section of the core spec that the extension text modifies. I may have to think about the right way to say this one a bit more...<br> <br> Right now there is a comment in invalidate_framebuffer_storage (fboject.c) that says:<br> <br> /* The GL_ARB_invalidate_subdata spec says:<br> *<br> * "If an attachment is specified that does not exist in the<br> * framebuffer bound to <target>, it is ignored."<br> *<br> * It also says:<br> *<br> * "If <attachments> contains COLOR_ATTACHMENTm and m is greater than<br> * or equal to the value of MAX_COLOR_ATTACHMENTS, then the error<br> * INVALID_OPERATION is generated."<br> *<br> * No mention is made of GL_AUXi being out of range. Therefore, we allow<br> * any enum that can be allowed by the API (OpenGL ES 3.0 has a different<br> * set of retrictions).<br> */<br> <br> I'm proposing that this should instead say:<br> <br> /* Section 4.5 of the GL_ARB_invalidate_subdata spec says:<br> *<br> * "If an attachment is specified that does not exist in the<br> * framebuffer bound to <target>, it is ignored."<br> *<br> * It also says:<br> *<br> * "If <attachments> contains COLOR_ATTACHMENTm and m is greater than<br> * or equal to the value of MAX_COLOR_ATTACHMENTS, then the error<br> * INVALID_OPERATION is generated."<br> *<br> * No mention is made of GL_AUXi being out of range. Therefore, we allow<br> * any enum that can be allowed by the API (OpenGL ES 3.0 has a different<br> * set of retrictions).<br> */<br> <br> Though, after looking at this case and a few other cases, I'm not sure there's much value in mentioning the section. Many of the extension specs that I checked only modify a single section in a substantive manner.<div class="im"> <br> <br> <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> specifications are text files, perhaps it would be better to quote by<br> line number?<br> </blockquote> <br></div> Quoting by line number seems like it would be annoying. The extension specs are (usually) small enough that searching in the document for the text should be good enough to fine-tune the location.<div class="HOEnZb"><div class="h5"> <br> <br> <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> <h2>Marking a commit as a candidate for a stable branch</h2><br> <br> --<br> 1.7.11.7<br> </blockquote> <br> </div></div></blockquote></div><br></div></div>