diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index b3caa700f..571caf8e9 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,12 @@ +2009-04-07 Corinna Vinschen <corinna@vinschen.de> + + * setup2.sgml (setup-locale-console): New section to explain + console character set setting. + * faq: Throughout, change references to User's Guide to references + to 1.7 User's Guide temporarily. + * faq-setup.html (faq.using.unicode): Rephrase slightly. + (faq.using.weirdchars): New FAQ entry for console charset problems. + 2009-04-06 Corinna Vinschen <corinna@vinschen.de> * new-features.sgml (ov-new1.7-posix): Remove JIS from supported diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml index 948c59d52..75499aa2c 100644 --- a/winsup/doc/faq-programming.xml +++ b/winsup/doc/faq-programming.xml @@ -116,7 +116,7 @@ done </screen> <para> -See <ulink url="http://cygwin.com/cygwin-ug-net/using.html#mount-table" /> +See <ulink url="http://cygwin.com/1.7/cygwin-ug-net/using.html#mount-table" /> for more information on using mount. </para> @@ -129,7 +129,7 @@ error?</para></question> <para> Try running cygserver. Read -<ulink url="http://cygwin.com/cygwin-ug-net/using-cygserver.html" />. If you're +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using-cygserver.html" />. If you're trying to use PostgreSQL, also read <literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>. </para> @@ -492,7 +492,7 @@ incompatibilities. Please send us patches if you do this work! <answer> <para>If you need to change the maximum amount of memory available to Cygwin, see -<ulink url="http://cygwin.com/cygwin-ug-net/setup-maxmem.html">http://cygwin.com/cygwin-ug-net/setup-maxmem.html</ulink>. Otherwise, +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/setup-maxmem.html">http://cygwin.com/1.7/cygwin-ug-net/setup-maxmem.html</ulink>. Otherwise, just pass heap/stack linker arguments to gcc. To create foo.exe with a heap size of 200MB and a stack size of 8MB, you would invoke gcc as: @@ -518,7 +518,7 @@ recursively, provided the command is in your path. <answer> <para>There's documentation that explains the process in the Cygwin User's -Guide here: <ulink url="http://cygwin.com/cygwin-ug-net/dll.html">http://cygwin.com/cygwin-ug-net/dll.html</ulink> +Guide here: <ulink url="http://cygwin.com/1.7/cygwin-ug-net/dll.html">http://cygwin.com/1.7/cygwin-ug-net/dll.html</ulink> </para> </answer></qandaentry> diff --git a/winsup/doc/faq-resources.xml b/winsup/doc/faq-resources.xml index 9bf42f722..bcd096c1b 100644 --- a/winsup/doc/faq-resources.xml +++ b/winsup/doc/faq-resources.xml @@ -22,7 +22,7 @@ including this FAQ. Be sure to at least read any 'Release Notes' or 'Readme' or 'read this' links on the main web page, if there are any. </para> <para>There is a comprehensive Cygwin User's Guide at <ulink -url="http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html</ulink> +url="http://cygwin.com/1.7/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/1.7/cygwin-ug-net/cygwin-ug-net.html</ulink> and an API Reference at <ulink url="http://cygwin.com/cygwin-api/cygwin-api.html">http://cygwin.com/cygwin-api/cygwin-api.html</ulink>. </para> diff --git a/winsup/doc/faq-setup.xml b/winsup/doc/faq-setup.xml index 6e6f0fa55..6c687a1f6 100644 --- a/winsup/doc/faq-setup.xml +++ b/winsup/doc/faq-setup.xml @@ -8,7 +8,7 @@ installer ``Cygwin Setup''. It is flexible and easy to use. You can pick and choose the packages you wish to install, and update them individually. Full source code is available for all packages and tools. More information on using Cygwin Setup may be found at -<ulink url="http://cygwin.com/cygwin-ug-net/setup-net.html" />. +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/setup-net.html" />. </para> <para>If you do it any other way, you're on your own! That said, keep in mind that the GUI installer is a "work in progress", so there might be a few @@ -170,7 +170,7 @@ you will have to select it explicitly. See <ulink url="http://cygwin.com/packages/" /> for a searchable list of available packages, or use <literal>cygcheck -p </literal> as described in the Cygwin User's Guide at -<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#cygcheck" />. +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using-utils.html#cygcheck" />. </para> <para>If you want to build programs, of course you'll need <literal>gcc</literal>, <literal>binutils</literal>, <literal>make</literal> and probably other packages from the @@ -416,7 +416,7 @@ installed are <literal>sshd</literal>, <literal>cron</literal>, that might be running in the background. Exit the command prompt and ensure that no Cygwin processes remain. Note: If you want to save your mount points for a later reinstall, first save the output of <literal>mount -m</literal> as described at -<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount" />. +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using-utils.html#mount" />. </para> </listitem> <listitem><para>Delete the Cygwin root folder and all subfolders. If you get an error diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml index 64fee2a1a..054030f1b 100644 --- a/winsup/doc/faq-using.xml +++ b/winsup/doc/faq-using.xml @@ -53,7 +53,7 @@ long time (though it still might work). (sshd, inetd, etc), then it depends on the method used to switch to another user. This problem as well as its solution is described in detail in the Cygwin User's Guide, see -<ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html" />. +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/ntsec.html" />. </para> <para>Workarounds include using public network share that does not require authentication (for non-critical files), providing your password to a @@ -281,7 +281,7 @@ for memory cards or USB sticks to exchange pictures... <para>For other cases, understand that Cygwin attempts to show UNIX permissions based on the security features of Windows, so the Windows ACLs are likely the source of your problem. See the Cygwin User's -Guide at <ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html" /> +Guide at <ulink url="http://cygwin.com/1.7/cygwin-ug-net/ntsec.html" /> for more information on how Cygwin maps Windows permissions. </para> </answer></qandaentry> @@ -368,7 +368,9 @@ formfeed character to your file. <para>Internationalization is a complex issue. The short answer is that Cygwin relies on the setting of the setting of LANG/LC_xxx environment -variables.</para> +variables. The long answer can be found in the User's Guide in the +section <ulink url="http://cygwin.com/1.7/cygwin-ug-net/setup-locale.html">Internationalization</ulink> +</para> <para>To get UTF-8 support you must set the LANG, LC_ALL, or LC_CTYPE environment variables. To get UTF-8 support you can set, for instance, @@ -379,7 +381,8 @@ language-specific collation, monetary or date/time-related string handling. This is planned for a later release, though.</para> <para>To type international characters (£äö) in -<literal>bash</literal>, add the following lines to your +<literal>bash</literal>, check if the following settings are available in +your <literal>bash</literal>, and if not, add them to your <literal>~/.inputrc</literal> file and restart <literal>bash</literal>: </para> <screen> @@ -403,10 +406,27 @@ alias ls='/bin/ls -F --color=tty --show-control-chars' </para> </answer></qandaentry> +<qandaentry id="faq.using.weirdchars"> +<question><para>My application prints international characters but I only +see gray boxes</para></question> +<answer> +<para>Very likely you didn't set your Console character set to the preferred +character set before the first Cygwin application was started in the +console. To make sure the console is using the desired character set, +maile sure that one of the internationalization environment variables +LC_ALL, LC_CTYPE, or LANG is set before the first Cygwin process starts. +You can do that, for instance, by setting the variable in your +<literal>Cygwin.bat</literal> file from which you start your Cygwin shell. +</para> + +<para> +For a more detailed explanation see the section +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/setup-locale.html#setup-locale-console">The Windows Console character set</ulink> in the Cygwin User's Guide.</para> +</answer></qandaentry> + <qandaentry id="faq.using.multiple-copies"> <question><para>Is it OK to have multiple copies of the DLL?</para></question> <answer> - <para>You should only have one copy of the Cygwin DLL on your system. If you have multiple versions, they will conflict and cause problems. </para> @@ -591,7 +611,7 @@ of your current Cygwin session. </para> <para>You can change the default <literal>cygdrive</literal> prefix and whether it is binmode or textmode using the <filename>/etc/fstab</filename> file as well. See the Cygwin User's Guide at -<ulink url="http://cygwin.com/cygwin-ug-net/using.html#mount-table">http://cygwin.com/cygwin-ug-net/using.html#mount-table</ulink> +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using.html#mount-table">http://cygwin.com/1.7/cygwin-ug-net/using.html#mount-table</ulink> for more details. </para> </answer></qandaentry> @@ -674,7 +694,7 @@ configuration fails. <para>To help with this problem, Cygwin supports casesensitivity starting with Cygwin 1.7.0. For a detailed description how to use that feature see the Cygwin User's Guilde at -<ulink url="http://cygwin.com/cygwin-ug-net/using-specialnames.html">http://cygwin.com/cygwin-ug-net/using-specialnames.html</ulink>. +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using-specialnames.html">http://cygwin.com/1.7/cygwin-ug-net/using-specialnames.html</ulink>. </para> </answer></qandaentry> @@ -694,7 +714,7 @@ letters 'aux' in it will hang. <para>At least that's what happens when using native Windows tools. Cygwin 1.7.0 and later can deal with these filenames just fine. Again, see the User's Guide at -<ulink url="http://cygwin.com/cygwin-ug-net/using-specialnames.html">http://cygwin.com/cygwin-ug-net/using-specialnames.html</ulink> +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using-specialnames.html">http://cygwin.com/1.7/cygwin-ug-net/using-specialnames.html</ulink> for a detailed description of what's possible with filenames and what is not. </para> </answer></qandaentry> @@ -1003,7 +1023,7 @@ file: </para> <para>Alternatively, use Windows shortcuts as symlinks. See the CYGWIN environment variable option "winsymlinks" -<ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">http://cygwin.com/cygwin-ug-net/using-cygwinenv.html</ulink> +<ulink url="http://cygwin.com/1.7/cygwin-ug-net/using-cygwinenv.html">http://cygwin.com/1.7/cygwin-ug-net/using-cygwinenv.html</ulink> </para> </answer></qandaentry> diff --git a/winsup/doc/faq-what.xml b/winsup/doc/faq-what.xml index 571ff3a7a..a3d377f75 100644 --- a/winsup/doc/faq-what.xml +++ b/winsup/doc/faq-what.xml @@ -96,7 +96,7 @@ freedoms, so it is free software. <para>To find the version of the Cygwin DLL installed, you can use <filename>uname</filename> as on Linux or <filename>cygcheck</filename>. Refer to each command's -<literal>--help</literal> output and the <ulink url='http://cygwin.com/cygwin-ug-net/'>Cygwin User's Guide</ulink> for more information. +<literal>--help</literal> output and the <ulink url='http://cygwin.com/1.7/cygwin-ug-net/'>Cygwin User's Guide</ulink> for more information. </para> <para>If you are looking for the version number for the whole Cygwin release, there is none. Each package in the Cygwin release has its own @@ -109,7 +109,7 @@ download the Cygwin Setup program from <ulink url='http://cygwin.com/setup.exe'>http://cygwin.com/setup.exe</ulink>. This program will handle the task of updating the packages on your system to the latest version. For more information about using Cygwin's <filename>setup.exe</filename>, see -<ulink url='http://cygwin.com/cygwin-ug-net/setup-net.html'>Setting Up Cygwin</ulink> +<ulink url='http://cygwin.com/1.7/cygwin-ug-net/setup-net.html'>Setting Up Cygwin</ulink> in the Cygwin User's Guide. </para></answer></qandaentry> diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml index a1a821472..a1175939b 100644 --- a/winsup/doc/setup2.sgml +++ b/winsup/doc/setup2.sgml @@ -261,6 +261,43 @@ Unicode character.</para> </sect2> +<sect2 id="setup-locale-console"><title>The Windows Console character set</title> + +<para>Most of the time the Windows console is used to run Cygwin applications. +While terminal emulations like <command>xterm</command> or +<command>mintty</command> have a distinct way to set the character set +used for in- and output, the Windows console hasn't such a way, since it's +not an application in its own right.</para> + +<para>This problem is solved in Cygwin as follows. When the first Cygwin +process is started in a Windows console (either explicitely from cmd.exe, +or implicitly by, for instance, clicking on the Cygwin desktop icon, or +running the Cygwin.bat file), the Console character set is determined by the +setting of the aforementioned internationalization environment variables, +the same way as described in <xref linkend="setup-locale-how"></xref>. +</para> + +<para>However, in contrast to the application's character set, which is +determined by the <function>setlocale</function> call, the console +character set stays fixed for all subsequent Cygwin processes started +from this first Cygwin process in the console. So, for instance, if +<envar>LANG</envar> was set to "en_US.UTF-8" when the first Cygwin process +started, the console is a UTF-8 terminal for the entire Cygwin process +tree started from this first Cygwin process.</para> + +<para>You're asking "What is that good for? Why not switch the console +character set with the applications requirements? After all, the +application knows if it uses localization or not." That's true, but +what if the non-localized application calls a remote application which +itself is localized? This can happen with <command>ssh</command> or +<command>rlogin</command>. Both commands don't have and don't need +localization and they never call <function>setlocale</function>. This +would have the unfortunate effect, that the console would run with the +ASCII character set alone. Native characters printed from the remote +application would not show up correctly on your local console.</para> + +</sect2> + <sect2 id="setup-locale-problems"><title>Potential Problems when using Locales</title> <para>