[RAPPS]

- Update README.ENG. Patch by Ismael Ferreras Morezuelas, with review by Jared Smudde
CORE-9060

svn path=/trunk/; revision=67028

reactos/base/applications/rapps/README.ENG

@@ -1,44 +1,78 @@
-For more information for RAPPS, see: https://www.reactos.org/wiki/RAPPS
+For more information about RAPPS, take a look at <https://reactos.org/wiki/RAPPS>
 
-ADDING DOWNLOADABLE PROGRAMMS
+ADDING DOWNLOADABLE PROGRAMS TO THE RAPPS DATABASE
+--------------------------------------------------
 
-For an each programm would be creacted an INI alike syntax.
-Also an each field is language inhdepended and individual, an URL's to a source programm is
-also maybe different or even nonexisting for anothers languages.
-For instance a programm 1C which is mostly interested only for russian users and have no
-reason for peoples living in another countries.
+Each program entry consists of a text file formatted with an INI-like syntax.
 
-The File Overview:
+They must be encoded in UTF-16 LE (Little Endian) or characters out of the ANSI range
+will display broken mojibake, some editors like Notepad++ call this format UCS-2 Little Endian.
 
-[Section]
-Name = program name
-RegName = Name in registry
-Version = 1.1.1
-License = GPL
-Description = Description
-Size = 10 mb
-Category = 5
-URLSite = http://www.site.com/
-URLDownload = http://ftp.site.com/pub/installer.exe
-CDPath = ; Ïîêà íå èñïîëüçóåòñÿ
+If you plan on including your program entry in the ReactOS source code versioning keep in mind
+that entries are stored in UTF-8 without BOM (Byte Order Mask) for VCS friendliness.
 
-[Section.0419] ; 0419 - for Russian language
-Description = Description in Russian language
+They get automatically converted to UTF-16 when creating the compressed rappmgr.cab package,
+which is how clients obtain their program lists every time a Database upgrade is triggered.
+
+Also, each [Section] is language-independent and individual, you can override the URL to a source
+program or any other field by adding a language-specific [Section.], followed by the language code.
+
+NOTE: You can find a complete listing of LCIDs and language names here, includes neutral codes:
+     <https://msdn.microsoft.com/en-us/library/windows/desktop/dd318693%28v=vs.85%29.aspx>
+
+Now RAPPS also accepts neutral language codes, meaning that you can do things like this:
+
+  ; Default English fallback, used if everything else fails.
+  [Section]
+  Name = Name in English
+
+  ; Neutral Spanish, used if the specific variant of Spanish does not match.
+  [Section.0a]
+  Name = Name in Generic Spanish
+
+  ; Spanish from Spain, used if the system is configured for it.
+  [Section.0c0a]
+  Name = Name in Castilian Spanish
 
 
-Obligatory fields are: Name, Category, URLDownload
-Other fields to fill not necessarily.
+You can also define an entry without English fallback to make it visible to certain users only.
+For instance; software from 1C, which is mostly for Russian speakers and unusable for anyone else.
 
-Categories list:
-1 - Audio
-2 - Video
-3 - Graphics
-4 - Games
-5 - Internet
-6 - Office
-7 - Development
-8 - Edutainment
-9 - Engineering
+File format overview:
+
+  ; This is a INI-style comment, useful for adding additional information.
+  ; Lines starting with a ; character are skipped by the parser.
+
+  [Section]
+  Name = My fun stuff-o-matic
+  RegName = Name in Registry
+  Version = 1.1.1
+  License = GPL
+  Description = Shortish description giving some additional background information about what it does.
+  Size = 10 MB
+  Category = 5
+  URLSite = https://example.org/
+  URLDownload = https://ftp.example.org/pub/installer.exe
+  CDPath = ; Path in the local filesystem
+
+  [Section.0419] ; 0419 - for Russian language
+  Description = Description in Russian language
+  ...
+
+
+The mandatory fields are: Name, Category and URLDownload
+All other fields are completely optional and can be skipped.
+
+List of valid categories:
+ 1 - Audio
+ 2 - Video
+ 3 - Graphics
+ 4 - Games
+ 5 - Internet
+ 6 - Office
+ 7 - Development
+ 8 - Edutainment
+ 9 - Engineering
 10 - Finance
 11 - Science
 12 - Tools
@@ -46,11 +80,21 @@ Categories list:
 14 - Libraries
 15 - Other
 
-The list downloadable programms is keeping on a server and updating from a server
-automatically at first time thes programm is running!
-For generating a list of a programm (usually a CAB archive), could be used a batch file CreateCabFile.bat
-After downloading (at first time the programm runs around), this file is placing
-in the same folder where downloaded programm located to future usage them.
-If in some cases an unpacked file is moved, deleted or not exist, then the procedure
-to create a new one would be repeated.
-If the CAB file is moved, deleted or not exist, then it would be downloaded again.
+The official list of downloadable programs is kept on a public ReactOS server
+and synced every time RAPPS is launched for the first time.
+
+NOTE: You can find the most current URL in rapps.h, defined as APPLICATION_DATABASE_URL.
+
+To generate a RAPPS database (usually a rappmgr.cab archive), use the included scripts:
+
+For Windows & other NT-derived: CreateCabFile.bat
+For Linux & other UNIX flavors: CreateCabFile.sh
+
+
+Once the rappmgr.cab is downloaded to %appdata%\rapps, RAPPS extracts it using cabinet.dll
+inside %appdata%\rapps\rapps, after that, it will parse all the *.txt files contained therein.
+
+Every subsequent time the program tries to access the local .txt files
+until a database update is manually triggered by the user.
+
+If the rappmgr.cab file is moved or just missing, RAPPS will download it again.