Re: FAQ Proposed Updates Summary and Preview Diff
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 to place links around available wording;
> >> change for or 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
Re: FAQ Proposed Updates Summary and Preview Diff
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 to place links around available wording;
>> change for or 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.]
Re: FAQ Proposed Updates Summary and Preview Diff
Hi Brian,
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.
>
> 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.
> reword net release or distribution references;
Uhm... example? I'm not sure what you mean here.
> emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
> change see to place links around available wording;
> change for or 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.
> trim trailing spaces highlighted by git diff.
Thanks,
Corinna
--
Corinna Vinschen
Cygwin Maintainer
FAQ Proposed Updates Summary and Preview Diff
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.
Summary
General:
change setup references to use the Cygwin Setup program;
change Win32 references to Windows;
reword net release or distribution references;
emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
change see to place links around available wording;
change for or where appropriate;
change bash .{ext1,ext2} usage to .ext1/.ext2;
trim trailing spaces highlighted by git diff.
Files:
winsup/doc/faq-api.xml: add to timezone FAQ "Why isn't time zone set correctly?"
winsup/doc/faq-programming.xml
winsup/doc/faq-setup.xml: update setup-x86/_64 --help options for
"Does the Cygwin Setup program accept command-line arguments?";
update compressed setup file types;
remove install everything instructions and provide total size info, time
required, and 32-bit Cygwin address space limitations;
winsup/doc/faq-using.xml
winsup/doc/faq-what.xml
Preview diff attached.
--
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.]
diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml
index 313f15d37c..8b149cd76f 100644
--- a/winsup/doc/faq-api.xml
+++ b/winsup/doc/faq-api.xml
@@ -5,7 +5,7 @@
Cygwin API Questions
-
+
How does everything work?
@@ -18,7 +18,7 @@ Windows into the C library. Then your apps should (ideally)
run on POSIX
systems (Unix/Linux) and Windows with no changes at the source level.
The C library is in a DLL, which makes basic applications quite small.
-And it allows relatively easy upgrades to the Win32/POSIX translation
+And it allows relatively easy upgrades to the Windows/POSIX translation
layer, providing that DLL changes stay backward-compatible.
For a good overview of Cygwin, you may want to read the Cygwin
@@ -140,7 +140,7 @@ spawn family of calls if possible.
Here's how it works:
Parent initializes a space in the Cygwin process table for child.
-Parent creates child suspended using Win32 CreateProcess call, giving
+Parent creates child suspended using Windows CreateProcess call, giving
the same path it was invoked with itself. Parent calls setjmp to save
its own context and then sets a pointer to this in the Cygwin shared
memory area (shared among all Cygwin tasks). Parent fills in the child's
@@ -326,7 +326,7 @@ name under the API.
E.g., the POSIX select system call can wait on a standard file handles
and handles to sockets. The select call in Winsock can only wait on
sockets. Because of this, the Cygwin dll does a lot of nasty stuff behind
-the scenes, trying to persuade various Winsock/Win32 functions to do what
+the scenes, trying to persuade various Winsock/Windows functions to do what
a Unix select would do.
If you are porting an application which already uses Winsock, then
@@ -337,11 +337,11 @@ direct calls to Winsock functions. If you use Cygwin,
use the POSIX API.
-I don't want Unix sockets, how do I use normal Win32
winsock?
+I don't want Unix sockets, how do I use normal Windows
winsock?
You don't. Look for the Mingw-w64 project to port applications using
-native Win32/Winsock functions. Cross compilers packages to build Mingw-w64
+native Windows/Winsock functions. Cross compilers packages to build Mingw-w64
targets are available in the Cygwin distro.
@@ -385,13 +385,34 @@ Cygwin version number details, check out the
-Why isn't timezone set correctly?
+Why isn't time zone set correctly?
-(Please note: This section has not yet been
updated for the latest net release.)
-
-Did you explicitly call tzset() before checking the value of timezone?
+Did you explicitly call tzset() before checking the value of time zone?
If not, you must do so.
+Time zone settings are updated by changes to the tzdata package included in all
+Cygwin installations.
+Have you run the Cygwin Setup program recently to update at least the
+tzdata
+package to include the latest current daylight saving (summer time) rules
+for dates of changes, hour offsets from UTC of time zones, and the
+geographic regions to which those rules and offsets apply.
+
+These changes are decided on by politicians, and announced
+by government officials, sometimes with short or no notice, so
+tzdata
+package updates are released at least a few, and sometimes several,
+times a year.
+As details of changes are not known until they are announced publicly by
+officials, often in foreign languages, and those details then have to be
+noticed, possibly translated, passed to, and picked up by the official
+tzdata
+source package maintainers, subsequently released in an update to the
+tzdata
+source package, and then those changes have to be picked up on and applied
+to the Cygwin
+tzdata
+package, which
