FAQ Proposed Updates Summary and Preview Diff

[Brian Inglis]

On 2020-07-17 05:17, Corinna Vinschen wrote:
> On Jul 16 21:35, Brian Inglis wrote:
>> Just want to get feedback on how these FAQ changes should be packaged as patches
>> (separate, series, single) and whether some of the changes should not be applied
>> at all.

What about how they should be committed - by file or all in one, and submitted -
separately by file, or as a FAQ patch series?

>> Summary
>>
>> General:
>>
>> change setup references to use the Cygwin Setup program;
>> change Win32 references to Windows;
> 
> Please, no.  At least not where Win32 refers to the API.  While this is
> called "Windows API" these days, the word Windows alone doesn't really
> cut it.  At leats use "Windows API" then, or IMHO even better, use the
> informal "WinAPI" abbreviation.

Good idea - will check and change depending on context.

>> reword net release or distribution references;
> 
> Uhm... example?  I'm not sure what you mean here.

They look like original wording from when there were Cygnus/Red Hat releases and
net releases: the distinction has been moot and the phrase not used in these
lists for years.

>> emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
>> change see <ulink/> to place links around available wording;
>> change <literal> for <filename> or <command> where appropriate;
>> change bash .{ext1,ext2} usage to .ext1/.ext2;
> 
> Using comma separated lists within curly braces is the offical
> shell way to express alternatives:
> 
>   $ echo a.{b,c}
>   a.b a.c
> 
> Please keep them as is.

These usages are in descriptions, not in shell command contexts, and not used in
most (POSIX) scripts, so many users will not recognize this convention, not even
those who do some scripts but are inexperienced.
My fingers are trained in their use, but would use them in text only to other
developers. ;^>

>> trim trailing spaces highlighted by git diff.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in IEC units and prefixes, physical quantities in SI.]