On 19 December 2012 15:46, Ian Romanick <i...@freedesktop.org> wrote:
> From: Ian Romanick <ian.d.roman...@intel.com> > > Signed-off-by: Ian Romanick <ian.d.roman...@intel.com> > Cc: Paul Berry <stereotype...@gmail.com> > Cc: Brian Paul <bri...@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 > >
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/mesa-dev
