[gdal-dev] Proposed updates to the GDAL feature style spec

[Alan Thomas]

Hello all,

In updating the PDF vector feature writer, it became apparent that
there are some deficiencies in the GDAL feature style specification
document (http://www.gdal.org/ogr_feature_style.html). I thought this
would be a good opportunity to update the document in other ways as
well.

See the diff of the proposed changes:
https://github.com/ThinkSpatial/gdal/commit/dc212edfa9872779c94d4534bdfeecb4cfbf3aff#diff-8bfbe5b06a25ed97077e344069647884

I've made a large number of editorial and non-substantive changes to
make the spec easier to read. The proposed substantive changes are:

--

1. Remove the "DRAFT" notice at the top.

Rationale: The spec has seen few updates in the last 10 years, so it
seems unnecessary to call it a draft.

2. Remove some unnecessary prognostications about things that may be
added in future versions of the specification, like predefined color
names, more brush patterns, or the "gp" parameter for pens.

Rationale: The document is no longer a discussion paper but an
actively used specification. The string "gp" does not appear anywhere
in GDAL code.

3. Remove information that contradicts reality, such as "A dataset can
have a default style that applies to all features" (there is no such
capability) and the statement that OGRFeature::GetStyleString()
handles style table lookups (it does not).

4. Replace the wording "An empty style string means that the feature
directly inherits its style
from the layer it is in" with "An empty style string means that the
feature's style is unspecified".

Rationale: OGR layers do not have a style. Even if they did, the spec
doesn't say what would happen if the layer also lacked a style.

5. Clarify the usage of BRUSH fc and bc; change the definition of
ogr-brush-1 to mean a solid fill in the selected background color;
change the suggested default for BRUSH bc to transparent (#FFFFFF00).

Rationale: The spec is not explicit on how fc and bc are meant to
work. A true null brush seems unnecessary, as the BRUSH() style tool
can simply be omitted. If a null brush really is required, ogr-brush-1
will continue to act as a null brush by default, assuming software
uses a fully transparent color as a default for bc.

6. Explain more clearly what was intended by the SYMBOL o (outline
color) parameter.

7. Provide notes explaining the subtleties of font size and text anchor values.

Rationale: See <https://trac.osgeo.org/gdal/ticket/7185#comment:2>.
This is option 1, "Admit defeat", but leaving the door open to dealing
with the problem properly at a later date if necessary.

8. Clarify that backslash characters must be escaped in text values.

Rationale: Without this, it is impossible to indicate a text string
that ends with a backslash.

9. Clarify that a 0 or 1 value is expected after Boolean parameters
(bo, it, un, st).

Rationale: Contradictory usage in existing drivers (MITAB) vs
OGRStyleTool class.

10. Fix incorrect text stretch example (a stretch of 150 is 150% of
the usual width, not 150% wider).

11. Update sections 2.7 and 3 to match reality.

--

Please speak up if you have concerns about these changes, or if you
have suggestions for additional changes that could be made at the same
time.

Alan

-- 
Alan Thomas
Software Developer
ThinkSpatial
http://www.thinkspatial.com.au