FAQ Proposed Updates Summary and Preview Diff

Corinna Vinschen corinna-cygwin@cygwin.com
Fri Jul 17 15:34:49 GMT 2020


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


More information about the Cygwin-patches mailing list