added tip regarding colons in curl commands

[csobier]

For docs issue#592

@michellechandra , can you confirm this Tip will help clarify with users? @iriberri , can you perhaps sign-off on this since Michelle is out for a few days?

[iriberri]

I'm not sure I like this approach. If we have to add the same note more than once in the same text perhaps it means there's something that we could be doing better there.

If you think the placeholders are not understandable, why don't convert them in anything that can be understood? (by itself).

[csobier]

I was just trying to add clarity since it caused some end-user misunderstanding. If you have a suggestion for better code examples, by all means, let me know!

[pnorman]

If it's intended to signify something the user is supposed to replace with their own string, I'd suggest either or $TEMPLATE_NAME.

[csobier]

This is also in the docs (in the same MAPS API doc), @template_name. I also found other variations. This is opening up a bigger can of worms, since a lot of the doc is inconsistent in how we present these placeholders in examples.

Whether we suggest:
:template_name
or
<template_name>
or
$TEMPLATE_NAME

Note that many users will copy the code format literally, so whatever we show them must not cause errors. Ideally, the response would return an error if an incorrect symbol was used in the request, and display the reason. For example, "A placeholder : indicates that a user input value is required, please enter the actual value for the variable" @rochoa , could this be a possible feature enhancement?

[pnorman]

In the URLs above the comments, there's at least two placeholders

https://documentation.cartodb.com/api/v1/map/named/:template_name/jsonp?auth_token=AUTH_TOKEN&callback=callback&config=template_params_json

Reading the text above, it looks like there are four placeholders: :template_name, AUTH_TOKEN, the second callback, and template_params_json.

 - **auth_token** optional, but required when `"method"` is set to `"token"`
 - **config** Encoded JSON with the params for creating named maps (the variables defined in the template)
 - **lmza** This attribute contains the same as config but LZMA compressed. It cannot be used at the same time than `config`.
 - **callback:** JSON callback name

[rochoa]

So ... either:

1. We create real examples for the documentation, so they can be copy-pasted.
2. Or we define a proper way of defining placeholders across all documentation.

[michellechandra]

In the example API call, is "documentation" also technically a placeholder since the user would need to replace "documentation" with their username?

https://documentation.cartodb.com/api/v1/map/named/:template_name/jsonp?auth_token=AUTH_TOKEN&callback=callback&config=template_params_json

[csobier]

@rochoa , as per the Support team, most users copy and paste code. So if we are unable to generate errors indicating a placeholder value is undefined, we'll need real examples. *I'll need developer resources to step through each example with me and confirm.

Additionally, defining placeholders across all the API doc should be consistent as well. I'll just need the API repo owners to decide collaboratively what direction they want to go, so that we can kick-off a larger effort of cleaning up all the API code across all repos.

[csobier]

Closing issue, replaced with new PR#403.