https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/Filters-Overview.md (line 18). Please advise. Is this link supposed to point to something that has been renamed, to a file that doesn't exist yet, or ...?

It seems like this example should read

blocks:
    filter: color.rgb = vec3(1.0, .5, .5);

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/shaders.md#filter

• Data sources can append custom URL params tangrams/tangram#204
• JS color functions can return CSS colors

https://github.com/tangrams/tangram/releases/tag/v0.6.0

I can guess at how this works, but others might not ;)

Documentation states that color be specified as: [R, G, B] or #rrggbb or css style color.
But it should be legal to have a color with RGBA value.

For example refer:
https://github.com/tangrams/tangram-docs/blob/f93ae00113e4db842e014e9de0ede1b201039ea9/pages/materials.md#diffuse

Is it a thing? Can't seem to find/use it.

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/shaders.md#built-in-uniforms

According to https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/styles.md a style can "inherit" or "descend" from one of the built-in styles, in which case you use base, or from another named style, in which case you use mix.

Is there any other difference between base and mix? Do I recall that mix can take a list of styles?

cc @bcamper

As I understand it, filters of the form { name: true } will pass any feature which contains the property "name" (and not check that they have a value of true). This behavior should be documented in https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/Filters-Overview.md

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/textures.md#filtering

I'm guessing that texture filtering is linear if nothing is set. If that's the case we should document it so that the effect of leaving it unset is clear.

specify which styles can take the parameter and point to texture.md

include examples from tangrams/tangram#312

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/Scene-file.md#the-basics

Maybe we had syntax like this a long time ago? We need an updated minimum-viable-scene.

tangrams/tangram@18d7978

We top-level list common 3d things like camera and lights in the top-level doc README. We should also list (as a parenthetical or – after the topic headings) text, font, fill, and stroke since those are the most common styling directives.

Tangram JS supports an undocumented angle parameter when drawing point geometries, but ES currently doesn't – per tangrams/tangram-es#551, has the fate of this feature been decided, either de jure or de facto?

cc @blair1618

When describing restrictions on the custom names of objects, the "reserved keywords" are mentioned, in numerous places:

cameras.md#camera-names
lights.md#light-names
sources.md#source-names
styles.md#style-names
textures.md#texture-names
layers.md#layer-name
layers.md#sublayer-name
layers.md#properties

This was originally written with the understanding that there were globally-reserved keywords, and that none of them could be used as custom names in any of these circumstances. Is this true?

Or – is it that a custom name can be anything except one of the reserved keywords at that layer in the document – and if there aren't any at that layer, the name can be anything at all?

Eg a layer object can take data and filter parameters (in addition to any sublayers), so the sublayers can be named anything except "data" and "filter" – whereas the cameras object has only custom names as parameters, so those names can be anything?

cc @bcamper

• unified text/points style (tangrams/tangram#306)
• dashed lines (tangrams/tangram#312)
• line textures (tangrams/tangram#312)
• custom fonts (tangrams/tangram#326)
• introspection mode (tangrams/tangram#303)
• centroid labeling (tangrams/tangram#302)

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/Filters-Overview.md#lists-imply-any-objects-imply-all

We should probably refer to them as 'sequence' and 'mapping', as the spec does: http://yaml.org/spec/current.html#id2506659

See tangrams/tangram#222 for details, adds repeat_distance and repeat_group.

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/styles.md#style

In the absence of a url parameter, is

styles:
    toner:
        style: halftone

distinct from

styles:
    toner:
        mix: halftone

?

tangrams/tangram#223

The tangram-es Android SDK will be launching publicly in the next few weeks. The public tangram documentation (https://mapzen.com/documentation/tangram/) should cover both the browser-based and Android-based Tangram SDKs. I can see several major steps to completing this:

• Find and label parts of the docs specific to tangram-js (e.g. "Walkthrough" -> "JS Walkthrough")
• Re-word the "Home" page to include both the web and mobile versions of tangram
• Create a repository with a minimal tangram-es Android demo app
• Add an "Android Walkthrough" page
• Add Android API reference documentation (either javadoc or markdown generated from javadoc)

• Link to "Styling Rule" documentation, in the layers: draw parameters section documentation is broken and return a 404.
  -- https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/styling-rules.md

The links to "Javascript API", "built-in uniforms", and "varyings" in the uniforms section are 404

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/shaders.md#uniforms

As is the link to "UV maps" in the material parameters section

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/shaders.md#material-parameters

generate_label_centroids

This will go in https://mapzen.com/documentation/tangram/sources/

label_placement

Probably need a new section in https://mapzen.com/documentation/tangram/filters/#feature-properties - something like "pre-processed features", noting that this is something Tangram can add, linking to the sources section.

It looks like we have a page for scene import, but I don't see a link to it anywhere? We should add it to the nav (and possibly link elsewhere too).

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/import.md

According to

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/shaders.md#shaders

the "defines", "uniforms", and "blocks" elements are direct children of the "style" block; but here

https://github.com/tangrams/tangram/blob/master/demos/scene.yaml#L53

the shader elements are children of a block called "shaders".

• Global property substitution tangrams/tangram#263
• Uv y meters tangrams/tangram#275
• Scene imports tangrams/tangram#278
• Selection event handlers tangrams/tangram#279
• Raster tile sources w/"attachments" tangrams/tangram#282
• Remove 'properties' section from Layer page #74
• setDataSource()

https://github.com/tangrams/tangram-docs/tree/v0.7.0

PR: #77

Some draw rules are described as "required" and have "no default", but can also have functions assigned to them.

One such rule is color:
https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/draw.md#color

A function may return an invalid value for the rule like null or undefined. Is there a defined behavior for these cases?

Summary of conversation from today.

First, for reference:

• Repository for mkdocs pipeline: https://github.com/louh/tangram-mkdocs Moved to https://github.com/mapzen/mapzen-docs-generator
• Build files published to gh-pages: http://louh.github.io/tangram-mkdocs/

And some additional background:
The contents of https://github.com/tangrams/tangram-docs is pulled in as a git submodule (for now, submodules are super janky) and MkDocs is told to read contents from the pages directory (as opposed to the root of the repository, most of which contains demo files, instead of documentation).

Some of the issues which have arisen:

• MkDocs does not understand contents outside of the documentation directory you give it, so relative links that go up to the root and into another folder just result in broken links. This results in things like image files (which GitHub links to correctly) to break when rendered by MkDocs. A potential solution is to move image assets into the pages folder if it's not needed anywhere else, or we process documentation from the root directory of the repository instead.
• Similarly, the front page of the documentation is processed by making a copy of README.md and placing it in the pages folder as index.md (with paths corrected). (I originally said it was based off of pages/Home.md but I think I was wrong about that.) For some reason we had some linking issues arising from case sensitive filenames but as I'm digging into the root cause, I think it might actually be a workflow problem on my end, so I will try to address it on my side and see if it's still a problem. On a similar vein, though, would it make sense to just have lower-case file names so that URLs are cleaner?
• Organization of things into certain top level categories makes it easier to do things like concatenate smaller pieces of documentation into single pages (this makes sense in technical documentation, like API or language documentation, where developers are more likely to prefer to Ctrl-F to a term). (Examples: LESS, Leaflet) Some ways we discussed (each with their own tradeoffs):
  • Explicitly declare which file is categorized where in mkdocs configuration.
  • Sort files into subfolders that are intended to indicate how files are categorized.
  • Include a block of YAML metadata (like with Jekyll posts) that tell the pipeline what to do with it.

The top of the textures page states that "A texture requires, at the minimum, a url path and a mapping mode":

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/textures.md#textures

However the subsequent paragraph on the 'mapping' parameter calls it an "optional" string:

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/textures.md#mapping

It's also a bit confusing that the syntax for textures differs slightly between the top-level textures element and "inline" in a material, but I believe that's an actual quirk of the library and not a documentation problem.

config.textures and element: tangrams/tangram#226
scene.loadTextures();

https://github.com/tangrams/tangram-docs/blob/1de3818aeb8d5e50ebd418d65f83d9227601ea47/pages/draw.md#text-wrap

Following tangrams/tangram#205

http://www.citylab.com/design/2015/03/a-mesmerizing-futuristic-map-with-animated-traffic-and-glowing-buildings/388285/

links to

http://tangrams.github.io/tangram-docs-assets/?procedural/tronish.yaml#16/40.7053/-74.0098

which forwards to

http://tangrams.github.io/tangram-docs?procedural/tronish.yaml#16/40.7053/-74.0098

which is a 404.

The docs here seem a little confused about it: https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/styles.md

This would be a top-level page which would collect and foreground all of our otherwise uncollected demos (eg, https://github.com/tangrams/?utf8=%E2%9C%93&query=demo) – plus any other maps we've made which could be useful for learning the library.

In a demo stylesheet, lighting type for a style is explicitly set:

https://github.com/tangrams/tangram/blob/master/demos/scene.yaml#L69

This parameter isn't documented. Is this the only way that lighting type is set?

See here: https://github.com/tangrams/tangram-docs/blame/reorg/pages/Scene-file.md#L25

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/Filters-Overview.md#matching-collisions

These examples have sublayers with a field called 'style', is this legal or does there need to be a 'draw' wrapping it?

It seems like the size parameter isn't fully documented since it's possible to provide a [widhSize, heightSize] if the sprite isn't squared.

Re: e.g. setDataSource(_string_ name, _object_ config), from #77 (comment):

I think I actually took these data types out (string, etc.) awhile ago, because while they are useful to have somewhere, they were not being formatted correctly in the doc generation (where they show up in the left-hand nav), and are also not consistent throughout these pages. So we should find a standard that works.

Currently, the Tangram help at https://mapzen.com/documentation/tangram/ has only two top-level entries in the TOC because everything is nested under "concept overviews" and "technical reference". Most of the titles are repeated between these headings (Filters in the overview, and filters in the API section), so it's not as easy as removing the top-level nodes. It would also get really redundant to put a word like "overview" in the first batch of headings or "API/parameter" in the second batch to distinguish them.

We also need to do need to do some work with the H2s and H3s in these topics to reduce the TOC subentries.

Original issue: mapzen/documentation#50

In the generated docs, the link on this page https://mapzen.com/documentation/tangram/cameras/ (https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/cameras.md) to this page https://mapzen.com/documentation/tangram/cameras/Javascript-API.md (https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/Javascript-API.md) is broken.
I don't yet understand enough about this doc generation process to know why, but wanted to make a note so we can fix.

https://github.com/tangrams/tangram-docs/blob/gh-pages/pages/layers.md#sublayer-name

The sublayer name section says that the draw and filter definitions are inherited. Is the properties entry inherited as well? We may want to specify that in the docs, either way.

Keyword-properties, mention "$zoom" to be the value of "current zoom". Will it make sense to mention "tile zoom" instead of "current zoom".

I got confused and thought it to be the value of the view's zoom initially.

At present shader blocks documentation mentions 5 shader blocks namely global,position,color,normal,filter. (refer: here)

It seems width is also used as a shader block in the style sheets (including eraser map style sheet).