Change .yaml extension to .yml (.yaml still works)

[MarkDBlackwell]

As you may know, the conventional extension for YAML files is .yml (rather than .yaml).

.yaml remains supported, presumably because spf13/viper supports it (e.g. here and here).

Most changes are documentation, some are error messages.

(BTW, I found git diff --word-diff=color useful in showing these changes.)

See #2 and (for example) use of ".yml" in issue 162.

[bep]

As you know, the conventional extension for YAML files is .yml (rather than .yaml).

I didn't know that.

[MarkDBlackwell]

In 2014, the Stack Overflow question Is it .yaml or .yml? measured Google search counts for YAML and YML to be 15,400 and 49,100 respectively.

Now, those figures are 4,110,000 and 6,010,000. Furthermore, the "YAML" count is unfairly high because it includes instances of the language's name, in addition to instances of the extension.

Searching this repository's issues for yml results in 21 hits. Therefore a number of people are using ".yml" with the repository, despite its suggestion to use ".yaml".

The Wikipedia article on YML says ".yml" is "the file extension for the YAML file format". Its YAML article lists both extensions, without prejudice.

Of course, both of these extensions are abbreviations of a long, possible extension, ".yamlaintmarkuplanguage". But programmers (and users) don't want to scan (or type) all that! In fact, we want to scan or type as little as possible, and yet still be unambiguous and clear. How many characters accomplishes both of these goals?

Any suggestion that this (real life usage) preference was caused by a 8.3 character DOS-ish limitation IMO is a red herring (erroneous and misleading).

Instead, generally, few extensions start with "Y". On the other hand, many extensions start with "J" (for "Java") or "X" (for "cross", "extensible", "extreme", etc.). So starting with "Y" already conveys much information.

Perhaps this is why we see in practice that the "linguistic" pressure (in natural use) to lengthen the abbreviation in question to four (4) characters is weak, and the "linguistic" pressure to shorten this abbreviation to three (3) characters is strong.

Apparently, on balance, as a result, the abbreviated, three (3) character extension is the one actually predominantly in use for YAML, despite the inventors' preference. Well—they can't be right about everything. ;/

[bep]

I agree abut the 3 letter extension being good, so this looks good to me.

[MarkDBlackwell]

Some command (I think it was hugo new {{something}}) generated an extension .yaml file (I noticed).

So I added 'WIP' to the title. I plan to investigate further.

[MarkDBlackwell]

Now, these commands:

1. hugo new site --format yaml and
2. hugo import jekyll

generate config.yml (without extension .yaml: I added a test for this).

This PR adds two (2) tests overall.

[bep]

Could you remove the edits below docs/content/commands/ from the commit. Those are autogenerated (we do it from time to time, and always before a new release).

[MarkDBlackwell]

remove the edits below docs/content/commands/

Now I've removed those edits.

[whereisaaron]

Nice troll @MarkDBlackwell, I had to check my calendar :-)

You're claiming that users voted with their feet to move to a three-letter contraction of the acronym, not in any part from the decades of influence of the three-letter extension limitation of CP/M and DOS. Which is still the convention in Windows, the overwhelmingly dominant desktop OS. You claim that has no influence, a 'red herring' even (the link is to the definition BTW, not to any data or justification). And instead the dominant, overriding, heartfelt concern of users was to save that keystroke?

By your own Google data, the balance is shifting. It looks like by about 2018 you'll be able to come back here and use the exact same argument to recommend a change back to '.yaml'.

"YAML" count is unfairly high because it includes mention of the language by name

Woah, how confusing, a file extension that mentions the language by name :-P

@bep think how many keystrokes we could save if we change all our '.go' files to '.g'. I know that is not the inventors' preference or the standard. "Well—they can't be right about everything. ;/"

@MarkDBlackwell better get to work on your crusades for '.json' to '.jsn' and '.toml' to '.tml'. It's not the Internet if we don't drp the vwls :-)

I'd prefer a less populist argument.

[MarkDBlackwell]

@whereisaaron: Actually (as the PR's title states), extension ".yaml" would still work.

Hugo accepts both ".json" and ".js" for JSON; ".yaml" and ".yml" for YAML; and ".toml" and ".tml" for TOML.

Please be reassured that the changes in the PR wouldn't prevent anyone from using the extension ".yaml" for their YAML-formatted Hugo files, if they so choose.

Certainly, if any particular user would like to use either extension for their YAML-formatted files, that's fine with Hugo.

The PR doesn't advise people against using the ".yaml" extension. Does Hugo's documentation need more language stating that the extension ".yaml" is fine to use as well? I believe I've already noticed something, along these lines.

The purpose of the PR is to aid (in a small way) Hugo's evangelism by removing a needless, disconcerting discrepancy between (on the one hand):

1. Hugo's documentation and generated files; and (on the other hand)
2. The predominant practice IMO of developers who aren't yet familiar with Hugo.

It aids this evangelism by:

1. Changing Hugo's documentation, from recommending the extension ".yaml", to recommending ".yml"; and
2. Changing Hugo, from generating ".yaml", to generating ".yml" files.

Again, this is in line with the practice IMO predominant among developers, especially outside the world of Hugo.

The PR also would remove a possible perception that Hugo is simply unaware of which extension (for YAML files) is predominant in actual use. Unjustly, that perception might lessen Hugo's reputation slightly among potential adopters.

That perception might also slightly increase Hugo's initial difficulty of use.

BTW, Go is the C-related language IMO most attractive to developers who use dynamic languages, due to Go's modern language features.

For evangelistic purposes, Hugo IMO should match those developers' expectations, wherever doing so doesn't hurt us.

The PR is all about a comfort thing; it would remove a small hurdle for new Hugo developer-users IMO. As the saying goes, "Every little bit helps."

[whereisaaron]

I agree the PR is harmless and doesn't prevent people using either extension as they wish. If @bep is for it, then I respect his decision.

I personally think your arguments for the change are specious, and part of a long-standing personal campaign rather than based on any actual evidence that Hugo users are confused by the .yaml extension. I respect your opinion and personal preference, but disagree with your reasoning. Also, sorry for calling you a troll, I can see you genuinely believe what you say.

[bep]

This change is not important enough compared to the amount of changes needed.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.