Based on 0003277: Patch for HACKING & 0003278: Translate load/unload …

…help

far/HACKING-EN

@@ -1,40 +1,48 @@
 RULES
 ~~~~~
 
+Sections below will help you get familiar with our development process.
+
+
 Submitting patches
 ~~~~~~~~~~~~~~~~~~
-First, please, read all the sections below to get familiar with our build
-system and rules.
 When you feel comfortable with the code and decide to make your contribution
 to the project, please follow those guidelines:
+
 1. One logical change per patch, the smaller the patch the easier it is for us
    to review and commit it.
 2. Try to keep inline with the overall style of the code.
 3. Provide detailed changelog for your patch.
-4. If your patch requires updating the documentation (help, Enc., etc.),
+4. If your patch requires updating the documentation (help, Encyclopedia, etc.)
    please provide the needed updates.
 5. Patches should be submitted as a collection of diff files, the best and
    easiest way to create a patch is:
    svn diff > file.diff
    Please create the patch against the latest code from the repository.
-6. Patches should be submitted through our bug tracker:
+6. Patches should be submitted to our bug tracker:
    http://bugs.farmanager.com
-7. If you plan on creating large patches or want to keep current with the
+   Development forum:
+   http://forum.farmanager.com/viewforum.php?f=54
+7. If you plan to create large patches or want to keep current with the
    development of Far Manager, subscribe to the Developers mailing list
    http://groups.google.com/group/fardeven (fardeven@googlegroups.com).
-8. Frequent patchers will be eligible for full SVN access, by our discretion.
-9. Be patient, we are new to Open Source :)
+8. Frequent patchers will be eligible for full repository access, by our discretion.
 
 
 Compilation
 ~~~~~~~~~~~
-1. To compile with VC you can either use the VS project file or makefile_vc.
-   For example, to build with the makefile run the following command:
-   nmake /f makefile_vc
+1. To compile with Visual Studio you can either use the IDE project or makefile.
+   Example for msbuild & vcxproj:
+     msbuild /property:Configuration=Release;platform=x64 far.vcxproj
+
+   Example for nmake & makefile:
+     nmake /f makefile_vc
 
-2. To compile with GCC you can use makefile_gcc.
-   For example, to build with Mingw run the following command:
-   mingw32-make -f makefile_gcc
+2. To compile with GCC you can use makefile.
+   Example for MinGW & makefile:
+     mingw32-make -f makefile_gcc
+
+Also see comments in makefile_* for additional build parameters.
 
 
 Changelog - "changelog" file
@@ -47,14 +55,14 @@ Changelog - "changelog" file
    warp 05.12.2006 01:39:38 +0300 - build 2149
 4. Changes not always require a build increase (i.e. cosmetic or non code
    related changes).
-5. Macro example:
+5. Sample macro to generate the header:
 Macro {
-  area="Editor"; key="Ctrl`"; flags="DisableOutput"; description="changelog"; action = function()
+  area="Editor"; key="Ctrl`"; action = function()
 Keys("CtrlHome End CtrlLeft")
 build=mf.int(mf.substr(Editor.Value,Editor.RealPos-1))+1;
 Keys("CtrlHome")
 print(mf.date("name %d.%m0.%Y %H:%M:%S %Z - build ")) print(build)
-for RCounter=4,1,-1 do Keys("Enter") end
+for RCounter=4,1,-1 do  Keys("Enter") end
 Keys("Up Up 1 . Space")
   end;
 }
@@ -63,36 +71,32 @@ Keys("Up Up 1 . Space")
 farversion.m4
 ~~~~~~~~~~~~~
 1. This file contains information used to generate Far version:
-   a. BUILDTYPE, a string that defines the build type, can be:
-      - `'      - empty string - release version
+   a. BUILDTYPE, a string that defines the build type:
+      - `'      - empty string (release version)
       - `alpha' - alpha version
       - `beta'  - beta version
       - `RC'    - release candidate
-      - `AnyThingElse' - intended for Far versions which code has not been
-        committed yet to the SVN so we and the users will not be confused.
+      - `AnythingElse' - intended for Far versions which code has not been
+        committed yet to the repository so we and the users will not be confused.
         Far version will look something like that:
-        FarVersion alpha AnyThingElse based on build BuildNumber
-   b. MAJOR - MAJOR Far version (i.e. 2).
-   c. MINOR - MINOR Far version (i.e. 0).
+        FarVersion alpha AnythingElse based on build BuildNumber
+   b. MAJOR - major Far version (i.e. 2).
+   c. MINOR - minor Far version (i.e. 0).
 
 
 vbuild.m4
 ~~~~~~~~~
 1. If the build number in "vbuild.m4"  was changed then after committing the
-   changes to the SVN you should call "svn_tag_build.bat".
+   changes to the repository you should call "svn_tag_build.bat".
 
 
 Adding new lines to language files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. If you've added a new line to language files, you need to add the "upd:"
-   prefix in farlang.templ.m4 to its variants that you did not translate.
-
-
-
-GCC - ensuring "successful" compilation with GCC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-1. Instead of postfixes i64 and ui64 use postfixes ll and ull.
+1. Lng files are generated automatically.
+   All changes must be made in farlang.templ.m4.
+   If you don't know how to translate your changes to other languages,
+   use the english version with the "upd:" prefix.
 
 
 x64 - ensuring "successful" compilation for x86 and x64

far/HACKING-RU

@@ -1,18 +1,21 @@
 ПРАВИЛА
 ~~~~~~~
 
+Прежде всего, ознакомьтесь, пожалуйста, с нашими правилами и системой
+компиляции и сборки Far'а.
+
+
 Предложение исправлений
 ~~~~~~~~~~~~~~~~~~~~~~~
-Прежде всего, ознакомьтесь, пожалуйста, с нашими правилами и системой
-компиляции и сборки Far'а. При внесении изменений в исходный код,
-пожалуйста, следуйте следующим правилам:
+При внесении изменений в исходный код, пожалуйста, следуйте следующим правилам:
+
 1. Каждое изменение должно быть логически завершенным и, по возможности,
    минимальным. Это позволит нам быстрее его проверить и внести в исходный код.
 2. Придерживайтесь единообразного стиля оформления кода.
-3. Детально опишите, что и зачем Ваш код исправляет.
-4. Если Ваше исправление требует обновления документации (справки,
+3. Детально опишите, что и зачем ваш код исправляет.
+4. Если ваше исправление требует обновления документации (справки,
    Энциклопедии и т.п.), не забудьте и ее обновить.
-5. Исправления принимаются в виде diff-файлов, наилучшим, а также самым простым
+5. Исправления принимаются в виде diff-файлов. Наилучшим, а также самым простым
    методом создания патча является:
    svn diff > file.diff
    Пожалуйста, формируйте diff-файлы на основе последних версий исходного кода.
@@ -21,78 +24,78 @@
 7. Если Вы планируете вносить большие исправления или просто желаете находиться
    в курсе последних событий в разработке Far'а, подпишитесь на нашу рассылку:
    http://groups.google.com/group/fardev (fardev@googlegroups.com).
+   Форум о разработке:
+   http://forum.farmanager.com/viewforum.php?f=54
 8. Если Вы будете присылать нам исправления часто и хорошего качества,
-   Вам будет предоставлен полный доступ к SVN, на наше усмотрение.
-9. Пожалуйста, будьте снисходительны - мы сами новички в Open Source :)
+   Вам будет предоставлен полный доступ к репозиторию, на наше усмотрение.
 
 
 Сборка
 ~~~~~~
-1. Для сборки с VC можно использовать проект для VS или мэйк файл, makefile_vc.
-   Для примера, чтоб собрать с помощью мэйк файла выполните следующую команду:
-   nmake /f makefile_vc
+1. Для сборки в Visual Studio можно использовать проект для IDE или makefile.
+   Пример для msbuild & vcxproj:
+     msbuild /property:Configuration=Release;platform=x64 far.vcxproj
 
-2. Для сборки с GCC можно использовать мэйк файл, makefile_gcc.
-   Для примера, чтоб собрать с Mingw выполните следующую команду:
-   mingw32-make -f makefile_gcc
+   Пример для nmake & makefile:
+     nmake /f makefile_vc
 
+2. Для сборки в GCC можно использовать makefile.
+   Пример для MinGW & makefile:
+     mingw32-make -f makefile_gcc
+
+Также см. комментарии в makefile_* для дополнительных параметров сборки.
 
 Описание изменений - файл "changelog"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 1. Все комментарии по внесенным изменениям пишутся в файл "changelog".
-   В сорцах имеет смысл оставлять комментарии только если участок с вашей
-   точки зрения будет непонятен для "будущих поколений".
-2. Дописываем изменения в начало файла.
+   В исходном коде имеет смысл оставлять комментарии только если участок
+   может быть непонятен для "будущих поколений".
+2. Изменения добавляются в начало файла.
 3. Каждая запись начинается с шапки вида:
    warp 05.12.2006 01:39:38 +0300 - build 2149
 4. Изменениям может не присваиваться билд, например, была косметика или
    изменения не в коде.
-5. Пример макроса:
+5. Пример макроса для создания шапки:
 Macro {
-  area="Editor"; key="Ctrl`"; flags="DisableOutput"; description="changelog"; action = function()
+  area="Editor"; key="Ctrl`"; action = function()
 Keys("CtrlHome End CtrlLeft")
 build=mf.int(mf.substr(Editor.Value,Editor.RealPos-1))+1;
 Keys("CtrlHome")
 print(mf.date("name %d.%m0.%Y %H:%M:%S %Z - build ")) print(build)
-for RCounter=4,1,-1 do Keys("Enter") end
+for RCounter=4,1,-1 do  Keys("Enter") end
 Keys("Up Up 1 . Space")
   end;
 }
 
 farversion.m4
 ~~~~~~~~~~~~~
-1. Этот файл содержит информацию для генерации версии фара:
-   a. BUILDTYPE, строка определяющая тип сборки, может быть:
-      - `'      - пустая строка обозначает релиз
+1. Этот файл содержит информацию для генерирования версии Far:
+   a. BUILDTYPE, строка, определяющая тип сборки:
+      - `'      - пустая строка (релиз)
       - `alpha' - альфа версия
       - `beta'  - бета версия
       - `RC'    - релиз кандидат
-      - `ЧтоЛибоДругое' - предназначено для выпуска версий фара,
-        код которых ещё не вошел в SVN, чтоб не путать людей и нас.
-        Вывод версии фара будет выглядеть следующим образом:
-        ВерсияФара alpha ЧтоЛибоДругое based on build НомерБилда
-   b. MAJOR - MAJOR версия фара (например 2).
-   c. MINOR - MINOR версия фара (например 0).
+      - `ЧтоЛибоДругое' - предназначено для выпуска версий Far, код которых
+        ещё не вошел в репозиторий, чтоб не путать людей и нас.
+        Вывод версии Far будет выглядеть следующим образом:
+        Версия alpha ЧтоЛибоДругое based on build НомерБилда
+   b. MAJOR - мажорная версия Far (например 3).
+   c. MINOR - минорная версия Far (например 0).
 
 
 vbuild.m4
 ~~~~~~~~~
 1. Если в файле "vbuild.m4" был изменен номер билда, то после коммита
-   изменений необходимо запустить "svn_tag_build.bat".
+   изменений в репозиторий необходимо запустить "svn_tag_build.bat".
 
 
 Добавление новых строк в языковые файлы
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Если в языковой файл была добавлена новая строчка, то в farlang.templ.m4
-   для непереведённых её вариантов на других языках, кроме русского и 
-   английского, нужно добавить префикс upd:
-
-
-
-GCC - обеспечение "удачной" компиляции под GCC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-+1. Вместо постфиксов i64 и ui64 используем постфиксы ll и ull.
+1. Lng-файлы ренерируются автоматически.
+   Добавлять изменения надо в farlang.templ.m4
+   Если вы не знаете, как перевести новые строки на какой-либо язык,
+   используйте английский вариант с префиксом "upd:".
 
 
 x64 - обеспечение "удачной" работы под x86 и x64
@@ -139,10 +142,3 @@ Macro. Добавление макрофункций (Draft)
 У объектов, основанных на классе ScreenObject, имеется виртуальный метод VMProcess.
 С его помощью можно "добраться" до приватных свойств и методов объекта.
 Пример, см. MCODE_F_BM_XXX
-
-api_test.c
-~~~~~~~~~~
-Цель: проверить, что результирующий файл Include/plugin.hpp соответствует C или C++
-В проект (Far.exe) этот файл не включается.
-Позволяет понять факт того, что заголовочный файл для плагинов в норме.
-

far/api_test.c

@@ -1,4 +1,37 @@
-#include "Include/plugin.hpp"
+/*
+api_test.c
+
+The purpose of this file is to validate that generated API headers
+are self-contained and valid from the C or C++ language perspective.
+*/
+/*
+Copyright © 2011 Far Group
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. The name of the authors may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+#include "Include/plugin.hpp"
 #include "Include/farcolor.hpp"
 #ifdef __cplusplus
 #include "Include/DlgBuilder.hpp"

plugins/farcmds/FARCmdsEng.hlf

@@ -38,32 +38,32 @@ in ~file associations~@:FileAssoc@, and in dialog ~Apply Command~@:ApplyCmd@ (#C
 
 @Load
 $ #The Load command#
-   Команда #load# позволяет загрузить плагин одним из 2-х способов:
+   The #load# command allows to load plugins manually.
 
-   1. Путь к плагину непосредственно в команде
+   - Plugin path can be provided as a command argument:
 
-      #load:имя_DLL_модуля#
+      #load:DLL_module_name#
 
-   2. Путь к плагину берётся из заданного файла "#имяфайла#"
+   - or picked from provided "#filename#":
 
-      #load: <имяфайла#
+      #load: <filename#
 
 
    See also: ~unload~@Unload@ | ~Notes~@Remark@ | ~Contents~@Contents@
 
 @Unload
 $ #The Unload command#
-   Команда #unload# позволяет выгрузить плагин одним из 2-х способов:
+   The #unload# command allows to unload plugins manually.
 
-   1. Путь к плагину непосредственно в команде
+   - Plugin path can be provided as a command argument:
 
       #unload:DLL_module_name#
 
-   2. Путь к плагину берётся из заданного файла "#filename#"
+   - or picked from provided "#filename#":
 
       #unload: <filename#
 
-   Вместо полного пути к DLL-модулю можно указать GUID плагина.
+   Plugin GUID can also be used instead of full DLL path.
 
 
    See also: ~load~@Load@ | ~Notes~@Remark@ | ~Contents~@Contents@

plugins/farcmds/FARCmdsRus.hlf

@@ -37,13 +37,13 @@ $ #FAR Commands#
 
 @Load
 $ #Команда Load#
-   Команда #load# позволяет загрузить плагин одним из 2-х способов:
+   Команда #load# позволяет загружать плагины вручную.
 
-   1. Путь к плагину непосредственно в команде
+   - Путь к плагину может быть передан как аргумент команды:
 
       #load:имя_DLL_модуля#
 
-   2. Путь к плагину берётся из заданного файла "#имяфайла#"
+   - или взят из заданного файла "#имяфайла#":
 
       #load: <имяфайла#
 
@@ -52,13 +52,13 @@ $ #Команда Load#
 
 @Unload
 $ #Команда Unload#
-   Команда #unload# позволяет выгрузить плагин одним из 2-х способов:
+   Команда #unload# позволяет выгружать плагины вручную.
 
-   1. Путь к плагину непосредственно в команде
+   - Путь к плагину может быть передан как аргумент команды:
 
       #unload:имя_DLL_модуля#
 
-   2. Путь к плагину берётся из заданного файла "#имяфайла#"
+   - или взят из заданного файла "#имяфайла#":
 
       #unload: <имяфайла#