Re: Pathological behavior in glGetString(3)

[Kristaps Dzonsons <kristaps@bsd.lv>]

[-- Attachment #1: Type: text/plain, Size: 950 bytes --]

On 30/04/2014 10:13, Anthony J. Bentley wrote:
> Hi,
>
> Maybe this is already known, but I couldn't find it in TODO.
>
> glGetString(3) has some really wonky spacing:

Anthony,

Hm...

The OpenGL manuals are in DocBook.  I've just updated docbook2mdoc to 
catch this particular manual--it needed a few additions--and so that it 
wouldn't crash on the remaining OpenGL ones.  (This doesn't solve the 
man(7) problem, but presents a way to cleanly avoid it.)

Their manuals:

https://www.opengl.org/discussion_boards/showthread.php/165536-Man-pages-source-available-in-Khronos-Subversion

Enclosed is glGetString as mdoc(7).  As you can see, there's still work 
to be done.  Beyond the missing inlineequation that's found in other 
manuals, the element-punctuation case needs to be handled.

That is, "<element>foo</element>, " needs to be properly rendered as 
".XX element ," instead of having a trailing newline.  I'll work on it.

Best,

Kristaps

[-- Attachment #2: glGetString.3g --]
[-- Type: text/plain, Size: 2828 bytes --]

.Dd $Mdocdate$
.Dt GLGETSTRING 3G
.Os
.Sh NAME
.Nm glGetString
.Nd return a string describing the current GL connection
.Sh SYNOPSIS
.Ft const GLubyte*
.Fo glGetString
.Fa "GLenum  name"
.Fc
.Ft const GLubyte*
.Fo glGetStringi
.Fa "GLenum  name"
.Fa "GLuint  index"
.Fc
.Sh PARAMETERS
.Bl -tag -width Ds
.It Fa "name"
Specifies a symbolic constant, one of
.Dv GL_VENDOR
,
.Dv GL_RENDERER
,
.Dv GL_VERSION
, or
.Dv GL_SHADING_LANGUAGE_VERSION
\&.
Additionally,
.Fn glGetStringi
accepts the
.Dv GL_EXTENSIONS
token.
.It Fa "index"
For
.Fn glGetStringi
, specifies the index of the string to return.
.El
.Sh DESCRIPTION
.Pp
.Fn glGetString
returns a pointer to a static string
describing some aspect of the current GL connection.
.Fa "name"
can be one of the following:
.Bl -tag -width Ds
.It Dv GL_VENDOR
Returns the company responsible for this GL implementation.
This name does not change from release to release.
.It Dv GL_RENDERER
Returns the name of the renderer.
This name is typically specific to a particular configuration of a hardware
platform.
It does not change from release to release.
.It Dv GL_VERSION
Returns a version or release number.
.It Dv GL_SHADING_LANGUAGE_VERSION
Returns a version or release number for the shading language.
.El
.Pp
.Fn glGetStringi
returns a pointer to a static string
indexed by
.Fa "index"
\&.
.Fa "name"
can be one of the following:
.Bl -tag -width Ds
.It Dv GL_EXTENSIONS
For
.Fn glGetStringi
only, returns the extension string
supported by the implementation at
.Fa "index"
\&.
.El
.Pp
Strings
.Dv GL_VENDOR
and
.Dv GL_RENDERER
together uniquely specify
a platform. They do not change from release to release and should be used
by platform-recognition algorithms.
.Pp
The
.Dv GL_VERSION
and
.Dv GL_SHADING_LANGUAGE_VERSION
strings begin with a version number.
The version number uses one
of these forms:
.Pp
.Em major_number.minor_number
.Em major_number.minor_number.release_number
.Pp
Vendor-specific information may follow the version
number. Its format depends on the implementation, but
a space always separates the version number and
the vendor-specific information.
.Pp
All strings are null-terminated.
.Sh NOTES
.Pp
If an error is generated,
.Fn glGetString
returns 0.
.Pp
The client and server may support different versions.
.Fn glGetString
always returns a compatible version number.
The release number always describes the server.
.Sh ERRORS
.Pp
.Dv GL_INVALID_ENUM
is generated if
.Fa "name"
is not an accepted value.
.Pp
.Dv GL_INVALID_VALUE
is generated by
.Fn glGetStringi
if
.Fa "index"
is outside the valid range for indexed state
.Fa "name"
\&.
.Sh COPYRIGHT
.Pp
Copyright
1991-2006 Silicon Graphics, Inc.
Copyright
2010-2013 Khronos Group.
This document is licensed under the SGI
Free Software B License. For details, see
http://oss.sgi.com/projects/FreeB/
\&.