On Jul 17 06:50, Brian Inglis wrote:
> 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?
By theme would be preferrable. I.e, one patch Win32 -> WinAPI, one
patch ulink changes, etc.
> >> 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.
Oh, all right. "Cygwin distro" is the new "net distro", I guess.
> >> 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. ;^>
Well, most of the descriptions are written for developers in the first
place. But, be it as it is, I don't see an advantage in using
slash-separated lists here. Whatever you use, it's a documentation
convention and there's always somebody puzzeling over them. Usually
you fix this by adding a "conventions in this document" chapter, but at
least the curly braces have a known meaning to devs, while something
with slashes in it typically means a path.
Corinna
--
Corinna Vinschen
Cygwin Maintainer
