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

[Kenneth Graunke]

On Wednesday, May 18, 2016 3:18:16 PM PDT Ian Romanick wrote:
> 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.romanick at 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.romanick at intel.com>
> >> Cc: Brian Paul <brianp at 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. :)

Sorry, that wasn't terribly clear - my intention was to give you a R-b on
the second patch only - the one with the code change.  I saw patch 1/2,
noted that you were changing the block quotes away from my preferred
style, and decided not to respond to that patch.  Not worth arguing.

But it did look like a series review; I should have said "This patch
is..." to be clear that 7c11589eb4326 was not covered by it.

> It's also the existing documented style.

True.

> Spec quotes are usually pretty short.  Is having less space really an
> issue?

None of this is a huge issue, I just prefer having the extra width.

I also wasn't clear how much to indent.  The documented style uses
4 spaces, which is arguably weird in a 3-space-indent project...

> 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.

I definitely prefer keeping them, as it helps clarify when a spec quote
stops and other commentary begins.  I suppose the indentation helps with
that as well.  The style I use is also a block quote.  It's just
formatted slightly differently.

Really,

   |                               vs.   |
   v                                     v

   "blah blah blah text and stuff        "blah blah blah text and stuff
   and some more text and stuff           and some more text and stuff
   and yet more text"                     and yet more text

not lining up just bothers my artistic and typographical OCD. :)

But again, none of this really matters that much, so whatever you like.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20160518/77fd0cbe/attachment.sig>