On 05/18/2016 02:21 PM, Kenneth Graunke wrote: > On Wednesday, May 18, 2016 1:12:29 PM PDT Ian Romanick wrote: >> From: Ian Romanick <ian.d.roman...@intel.com> >> >> v2: Remove extra "ES" from "GLSL ES ES". Noticed by Chris Forbes. >> >> v3: Many updates based on (very old) feedback from Paul Berry and (more >> recent) observation of what is most commonly done in the code base. >> >> Signed-off-by: Ian Romanick <ian.d.roman...@intel.com> >> Cc: Brian Paul <bri...@vmware.com> >> --- >> docs/devinfo.html | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ > +------ >> 1 file changed, 76 insertions(+), 8 deletions(-) >> >> diff --git a/docs/devinfo.html b/docs/devinfo.html >> index 8ebf80f..fc0001b 100644 >> --- a/docs/devinfo.html >> +++ b/docs/devinfo.html >> @@ -81,18 +81,86 @@ Multi-line comment: >> * never used before, allocate a buffer object now. >> */ >> </pre> >> -We try to quote the OpenGL specification where prudent: >> + >> +<p id="spec_quotes"> >> +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, use one of the following formats. >> +</p> >> + >> +<p> >> +Text quoted from the core OpenGL, OpenGL ES, GLSL, GLSL ES, GLX, or EGL >> +specifications should be formatted as: >> +</p> >> + >> +<pre> >> + /* Section ##.##.## (Section Name) of the OpenGL #.# spec says: >> + * >> + * "Some quoted text from the specificiation. More quoted text. > Yet >> + * more quoted text." >> + */ > > I've always done: > > /* ...something something OpenGL...: > * > * "Some quoted text from the specification. More quoted text. Yet > * more quoted text. Still more quoted text. Multiple lines of quoted > * text get indented so they line up with the text, not the open quote." > */ > > I don't care for the four space indent (it just gives you less space), > and I think it looks nicer if the opening quote is offset by 1 so that > the actual quoted text lines up. It's just something I've always done.
I find this a little surprising... since you just give me a R-b on a patch that reformats spec quotations in this way. :) It's also the existing documented style. Spec quotes are usually pretty short. Is having less space really an issue? When we first started using this style (this patch originally came from 2012, and the use predates even that), we were trying to mimic MLA style for block quotes. There were some intentional (and unintentional) deviations, but that was the main motivator. It's a pretty established style, after all. The main intentional deviation is that MLA only uses the block quote format when the quotation is four or more lines in the document. There's usually formatting that needs to be preserved in spec quotations, so mashing things into fewer lines doesn't really make sense. Also... having two different rules to apply conditionally can only lead to problems. The unintentional deviation is that MLA block quotes don't have quotation marks around them. I literally never noticed that until I looked up the style guide about 5 minutes ago. I'm not married to keeping the quotation marks. > Having more consistency on the first line seems like a good idea, > and I'm fine with what you proposed. > >> +</pre> >> + >> +<p> >> +Quotations from the GLSL or GLSL ES specifications should be attributed to >> +"GLSL" or "GLSL ES", respectively (i.e., <em>not</em> the full name "OpenGL >> +Shading Language" or "OpenGL ES Shading Language"). Note: There are a > total >> +of 5 spaces between the <tt>*</tt> and the <tt>"</tt> starting the > quotation. >> +</p> >> + >> +<p> >> +The practice used to be to include the page number in the quotation. This >> +posed several problems. First, the page number printed on the page and the >> +page number in the specification PDF never match. For this reason both > page >> +numbers were quoted, and it was very annoying. Second, from version to >> +version of the specification the page number could change quite >> +significantly. This made it difficult to detect when the specification had >> +changed. Differences between the Core Profile and Compatibility Profile >> +specifications made this issue even worse. >> +</p> >> + >> +<p> >> +Spec quotations from OpenGL 3.2 or later should also include the Profile > being >> +quoted. For example, a quote from the Core Profile spec would read: >> +</p> >> + >> +<pre> >> + /* Section ##.##.## (Section Name) of the OpenGL #.# (Core Profile) spec >> + * says: >> + * >> + * "Some quoted text from the specificiation. More quoted text. > Yet >> + * more quoted text." >> + */ >> +</pre> >> + >> +<p> >> +Text quoted from an extension specifications: >> +</p> >> + >> +<pre> >> + /* The EXT_foo_bar spec says: >> + * >> + * "Some quoted text from the specificiation" >> + */ >> +</pre> >> + >> +<p> >> +Since extension specifications are generally small, it is usually easy > enough >> +to find the quoted text without including a section number. One exception > to >> +that is the issues section. Even careful spec readers may miss things in > the >> +issues section, so it is helpful to draw attention to quotations from the >> +issues. >> +</p> >> + >> <pre> >> - /* Page 38 of the PDF of the OpenGL ES 3.0 spec says: >> + /* The EXT_foo_bar spec says: >> * >> - * "An INVALID_OPERATION error is generated for any of the following >> - * conditions: >> + * "Issues: >> * >> - * * <length> is zero." >> + * (#) Got an issue? >> * >> - * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec >> - * (30.10.2014) also says this, so it's no longer allowed for desktop > GL, >> - * either. >> + * RESOLVED: Have a tissue." >> */ >> </pre> >> Function comment example: >> > > Heh :) Nice. >
signature.asc
Description: OpenPGP digital signature
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
