Wrong translation of README selected by default

dan.j.allen

23 Mar, 2019 07:49 AM

The README for the asciidoctor gem is being displayed in Japanese instead of English. This is happening because the README-jp.adoc file is being used instead of README.adoc. Unfortunately, most visitors expect the README to be in English. Can you please tell me how I can fix this problem?

By default, YARD picks the first matching README file as part of the README* glob. You can override the README file by specifying a first extra file or using --readme README.adoc in your .yardopts file.

Argh. That means there's no way for me to fix it for any gem already released.

Is there any chance you'd be willing to change the glob to only match the basename README (keeping the wildcard only on the file extension)? Surely that's the behavior users expect. (That's also consistent with how other systems work, like npm and yarn).

Is there any chance you'd be willing to change the glob to only match the basename README (keeping the wildcard only on the file extension)? Surely that's the behavior users expect

I think this conversation would be better had as an issue YARD itself (https://github.com/lsegal/yard/issues). I think I'd be open to discussions about how globs are sorted so as to choose a more reliable default, but we couldn't exclude README-* files from the glob altogether, since that would be a breaking change, and likely not the expected behavior either. If you're interested, a PR to sort README and README.* ahead of other README files would be considered.

What's the use case for only having README files with a hyphenated suffix? Obviously, there may be additional files with a suffix for translations, but why would you ever want those to be selected anyway? The only case I can think of is someone adds the "-en" suffix to the English version instead of using the basename README. But that seems highly unlikely. Perhaps I'm just not aware of this practice.