Several issues with Specifications v1.3

[avih]

Some non exhaustive issues with spec v1.3:

Terminology:

• You link to the terminology RFC, but use terms which are not specified there, like "MAY NOT". It's not obvious what it means (one could guess, but the capitalization suggests it should be specified and guessing should not be required). If you specify terminology, stick to it and to its explicit semantics.

Client program:

• The overall syntax of the client is not mentioned anywhere. I'm guessing it's possibly client [OPTIONS] CMD - which suggests that CMD is mandatory, but judging by other text at the page, that's not necessarily the case.

• While it's specified what some options should do, it's not mentioned anywhere what the client should do when no options are used (but CMD is). I'm assuming the main use case it to print or display some form of the page of CMD, but it's not mentioned anywhere.

• It's not mentioned how options may or may not be combined. For instance -u with CMD could be useful, but -l with CMD is probably not useful, while -v probably doesn't go with anything. Should it succeed without arguments at all?

Terminal output:

• You give a (good) example how commands should be listed, but the rest is vague. Specifically, when it comes to the main use case (which I assume is) client CMD it doesn't say if only colors should be stripped, or maybe also the formatting of markup-to-display - i.e. print a raw page file. This goes back to the main task of the client - which isn't specified.

Languages/locales:

I'm ignoring issues with the current directory structure, and assume #4120 is the way forward, at which case it's not obvious to me what the algorithm should be to map a locale string to directory name string, but I think it should be specified in absolute terms in order to be useful, because the example at #4120 doesn't show directories with coutry codes.

One simplistic and most probably bad algorithm could be:

• Strip the country and anything else beyond the language code, and search pages/<language>.
• If language is not en, then also search pages/en.

E.g. both en_US.UTF-8 and en_UK map to pages/en, zh_CN and zh_TW and zh all map to pages/zh, etc.

Another algorithm could be to seatch pages/lc_CC and then pages/lc and then (if lc is not en) also pages/en.

Now, I don't pretend to know much about locales and my ideas is probably complete junk. But you should define absolutely how a locale string maps to directory name string(s) which should be searched, because otherwise it's unlikely IMHO that clients will be able to get the directory name as you expect them to.

More specific locale issues:

• Should LC_ALL override other vars? (generally it does, but you don't mention it).
• This doesn't sound useful to me other than for development purposes: "If such a command-line option is specified, a client must strictly adhere to its value, and MUST NOT show pages in a different language", because it means it will not fall back to English if the page was not found in the specified language, which I don't think is what the user was hoping for. It also somewhat contradicts the earlier directive of "clients MUST always attempt to fallback to English if the page does not exist in the user preferred language". If the command line option overrides the fallback, then I think it should be mentioned. However, as far as expectations go, I think the user would like it to fall back to english.