On 12/19/2012 09:56 PM, Paul Berry wrote: > 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.
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. _______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/mesa-dev
