discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Pathological behavior in glGetString(3)
@ 2014-04-30  8:13 Anthony J. Bentley
  2014-04-30 10:16 ` Kristaps Dzonsons
  0 siblings, 1 reply; 3+ messages in thread
From: Anthony J. Bentley @ 2014-04-30  8:13 UTC (permalink / raw)
  To: discuss

Hi,

Maybe this is already known, but I couldn't find it in TODO.

glGetString(3) has some really wonky spacing:

.SH PARAMETERS
.TP \w'\fIname\fP\ \ 'u
\f2name\fP
Specifies a symbolic constant, one of

becomes...

PARAMETERS
       name                                                                                                                                                                                                                                                                                                                                            Specifies
                                                                                                                                                                                                                                                                                                                                                       a
                                                                                                                                                                                                                                                                                                                                                       symbolic
                                                                                                                                                                                                                                                                                                                                                       constant,

...

-- 
Anthony J. Bentley

--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: Pathological behavior in glGetString(3)
  2014-04-30  8:13 Pathological behavior in glGetString(3) Anthony J. Bentley
@ 2014-04-30 10:16 ` Kristaps Dzonsons
  2014-04-30 16:56   ` Kristaps Dzonsons
  0 siblings, 1 reply; 3+ messages in thread
From: Kristaps Dzonsons @ 2014-04-30 10:16 UTC (permalink / raw)
  To: discuss

[-- 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/
\&.

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: Pathological behavior in glGetString(3)
  2014-04-30 10:16 ` Kristaps Dzonsons
@ 2014-04-30 16:56   ` Kristaps Dzonsons
  0 siblings, 0 replies; 3+ messages in thread
From: Kristaps Dzonsons @ 2014-04-30 16:56 UTC (permalink / raw)
  To: discuss

On second thought, I went ahead and finished the mentioned work as well 
(v0.0.9).  There are still a few missing bits from the OpenGL manuals in 
generic docbook that I can hit if you actually need this for, say, 
porting.  The bigger question is equations.  I can simply wipe out 
equations--or more specifically, I can wipe out anything not in the 
docbook namespace (i.e., <*:*>), but most OpenGL manuals don't specify 
an <alt> tag for a quick textual description.  So the manuals will be 
lossy.  Anybody up for writing a MathML -> eqn converter?
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2014-04-30 16:56 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-04-30  8:13 Pathological behavior in glGetString(3) Anthony J. Bentley
2014-04-30 10:16 ` Kristaps Dzonsons
2014-04-30 16:56   ` Kristaps Dzonsons

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).