fakedata: add page

[nicokosi]

• The page (if new), does not already exist in the repo.
• The page is in the correct platform directory (common/, linux/, etc.)
• The page has 8 or fewer examples.
• The PR title conforms to the recommended templates.
• The page follows the content guidelines.
• The page description includes a link to documentation or a homepage (if applicable).

[tldr-bot]

The build for this PR failed with the following error(s):

pages/common/fakedata.md:24 MD047/single-trailing-newline Files should end with a single newline character
pages/common/fakedata.md:1: TLDR009 Page should contain a newline at end of file

Please fix the error(s) and push again.

[nicokosi]

The build for this PR failed with the following error(s):

pages/common/fakedata.md:24 MD047/single-trailing-newline Files should end with a single newline character
pages/common/fakedata.md:1: TLDR009 Page should contain a newline at end of file

Please fix the error(s) and push again.

Error seems outdated. 😇

[nicokosi]

Thank you @bl-ue for the typos and the reword suggestions. 😎

[marchersimon]

LGTM, however it really confused me that data is the plural of datum and I fear it may confuse others too.

[bl-ue]

Let's see what others have to say about that then. @sbrl

[navarroaxel]

Suggested change

	`echo "value: {{Generator}}" | fakedata`
	`echo "value: {{generator}}" | fakedata`

[nicokosi]

I used "Pascal case" on purpose because:

If the generator name is a single word, then it's available as a function with the same name capitalized (example: int becomes Int). If the generator name is composed by multiple words joined by dots, then the function name is again capitalized by the first letter of the word and joined together (example: product.name becomes Product.Name).

See https://github.com/lucapette/fakedata#generators-1

What do you think of this "intentional violation"? 😇

[navarroaxel]

🤔 all the custom format is the custom argument option in this example, so the valid highlight is the following:

Suggested change

	`echo "value: {{Generator}}" | fakedata`
	`echo "{{value: Generator}}" | fakedata`

[bl-ue]

I prefer the original capitalized Generator to generator. It's required anyway. @navarroaxel see the example description itself; it mentions this oddity.

[bl-ue]

@nicokosi maybe it would be better to change the parenthetic message to the first letter of generator names must be capitalized, that sounds a bit clearer.

[nicokosi]

@nicokosi maybe it would be better to change the parenthetic message to the first letter of generator names must be capitalized, that sounds a bit clearer.

Done in commit 7373486.

[bl-ue]

@nicokosi I believe @navarroaxel is right about the extents of the token syntax; "value: " is your own custom text and there fore should be highlighted as needed. https://github.com/tldr-pages/tldr/pull/5675/files#r606702953

[bl-ue]

Actually, I see that there's an issue here. fakedata has a special syntax for their templates where you enclose the capitalized template name in {{ and }}. Both the capitalization and the braces are required because fakedata uses the Go template library. The issue with that is that we at tldr-pages use that very syntax for a different purpose: that of highlighting user-entered values.

Instead of the original text here and @navarroaxel's suggestion, the appropriate would be this:

echo "{{value: {{Generator}}}}" | fakedata`

However, many clients do a blind replace of {{ and }} with HTML/ANSI escape codes that highlight the text, so we might need some sort of escaping, e.g.

echo "{{value: \{\{Generator\}\}}}" | fakedata`

But I'm just not sure. @sbrl what should we do here?

[nicokosi]

Actually, I see that there's an issue here. fakedata has a special syntax for their templates where you enclose the capitalized template name in {{ and }}. Both the capitalization and the braces are required because fakedata uses the Go template library. The issue with that is that we at tldr-pages use that very syntax for a different purpose: that of highlighting user-entered values.

Instead of the original text here and @navarroaxel's suggestion, the appropriate would be this:

echo "{{value: {{Generator}}}}" | fakedata`

However, many clients do a blind replace of {{ and }} with HTML/ANSI escape codes that highlight the text, so we might need some sort of escaping, e.g.

echo "{{value: \{\{Generator\}\}}}" | fakedata`

Done in 8ce9022.

[sbrl]

Left a comment here @bl-ue: #5675 (comment)

[nicokosi]

Left a comment here @bl-ue: #5675 (comment)

Done in 1c0bcc0.

[bl-ue]

Thank you @nicokosi. I left a new comment here: #5675 (comment)

[bl-ue]

Looks good to me. I want to know what @sbrl has to say regarding the syntax in the last example. Ping @sbrl

[nicokosi]

Seems OK for me. @sbrl, still any blockers on your side?

[sbrl]

Oh wow, this is a very awkward situation here. We don't actually define any standard way to escape this in the client spec. This is the only thing we mention:

Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard CommonMark, which the exception of the non-standard {{ and }} syntax, which surrounds values in an example that users may edit. Clients MUST NOT break if the page format is changed within the CommonMark specification.

So the escaping with the backward slashes won't be handled correctly here. What happens if you remove the backwards slashes? How do clients handle that? I would assume that since the syntax can't be nested they would display it?

I think a client spec update is in order to properly define our non-standard token syntax.

Sorry to drag the review process out!

[bl-ue]

Also @sbrl some clients just blindly replace {{ and }} with ANSI codes/HTML to highlight, e.g. hidroh/tldroid (though that client it no longer maintained and we're going to remove it soon I think, #4044)

[bl-ue]

@navarroaxel I'm not sure this was supposed to be merged actually, see our conversation above.