== RELEASE NOTES ==
v4.6.5.1911 features the following:
* (PC) Fix multiple parser errors related to Wikibase and LuaJ
* (PC) Fix HTML dump images not showing
* (PC) Fix Pagebanner issues

For more details about this release, please see:
* http://xowa.org/home/wiki/Change_log.html

See the CHANGE LOG below for a complete list of items specific to this release.

== CONTACT ==
XOWA's website is at http://xowa.org . All files are at https://github.com/gnosygnu/xowa/releases/

If you encounter issues, please post to https://github.com/gnosygnu/xowa/issues

== LICENSE ==
XOWA is licensed under the terms of the General Public License (GPL) Version 3,
or alternatively under the terms of the Apache License Version 2.0.

See /xowa/bin/any/xowa/LICENSE.txt for more information. On a Windows system  where XOWA is unzipped to C:\xowa,
the full fill path would be C:\xowa\bin\any\xowa\LICENSE.txt

== INSTALL ==
=== FILES ===
The xowa_app_*** archives have all the files necessary for xowa to run, including the main jars, XULRunner, languages, etc..

The paths below are recommendations. Please feel free to choose any other.

Finally, note that "/xowa/" refers to the XOWA root directory. For example, if you're on a Windows system and unzipped XOWA to "C:\xowa", then "/xowa/wiki/en.wikipedia.org" means "C:\xowa\wiki\en.wikipedia.org"

=== REQUIREMENTS ===
* Java 1.7+
: If you do not have Java 1.7 installed, then please install the latest Java from http://www.java.com/en/download/manual.jsp
: On Ubuntu Linux, you can use OpenJDK by running 'sudo apt-get install openjdk-7-jre'.
* Compression/Decompression program ("unzip")
: The XOWA files will be compressed. If your Operating System does not natively support decompressing, please install 7-Zip from http://7-zip.org.
* 512 MB RAM
: XOWA can run on lower memory machines, but 512 MB is needed for importing the larger wikis (EX: en.wikipedia.org; commons.wikimedia.org)

=== OPERATING SYSTEMS ===
===== Windows 64-bit =====
* Download 'xowa_app_windows_64_v*.*.*.*.zip'
* Unzip to 'C:\xowa'. When you are done you should have a file called 'C:\xowa\xowa_64.exe' as well as many others
* Double-click 'xowa_64.exe'
* If "xowa_64.exe" fails, you may have a 32-bit Java installation. Try the "Windows 32-bit" installation below

===== Windows 32-bit =====
[NOTE: This is the same as Windows 64-bit, except the non-"_64" files are used]
* Download 'xowa_app_windows_v*.*.*.*.zip'
* Unzip to 'C:\xowa'. When you are done you should have a file called 'C:\xowa\xowa.exe' as well as many others
* Double-click 'xowa.exe'

==== Linux 64-bit ====
* Download 'xowa_app_linux_64_v*.*.*.*.zip'
* Unzip to '/home/your_user_name/xowa/'. When you are done you should have a file called '/home/your_user_name/xowa/xowa_linux_64.jar' as well as many others
* Open a terminal and run "sh /home/your_user_name/xowa/xowa_linux_64.sh"
* If "xowa_linux_64.sh" doesn't work, run "java -Xmx256m -jar /home/your_user_name/xowa/xowa_linux_64.jar"

==== Linux ====
[NOTE: This is the same as Linux 64-bit, except the non-"_64" files are used]
* Download 'xowa_app_linux_v*.*.*.*.zip'
* Unzip to '/home/your_user_name/xowa/'. When you are done you should have a file called '/home/your_user_name/xowa/xowa_linux.jar' as well as many others
* Open a terminal and run "sh /home/your_user_name/xowa/xowa_linux.sh"
* If "xowa_linux.sh" doesn't work, run "java -Xmx256m -jar /home/your_user_name/xowa/xowa_linux.jar"

==== Mac OS X 64-bit ====
* Download 'xowa_app_macosx_64_v*.*.*.*.zip'
* Unzip to '/Users/your_user_name/xowa/'. When you are done you should have a file called '/Users/your_user_name/xowa/xowa_macosx_64.jar' as well as many others
* Open a terminal by doing Finder -> Applications -> Utilities -> Terminal
* Run "sh /Users/your_user_name/xowa/xowa_macosx_64"
* If "xowa_macosx.sh" doesn't work, run "java -Xmx256m -d32 -XstartOnFirstThread -jar /Users/your_user_name/xowa/xowa_macosx_64.jar"

==== Mac OS X 32-bit ====
[NOTE: This is the same as Mac OS X 64-bit, except the non-"_64" files are used]
* Download 'xowa_app_macosx_v*.*.*.*.zip'
* Unzip to '/Users/your_user_name/xowa/'. When you are done you should have a file called '/Users/your_user_name/xowa/xowa_macosx.jar' as well as many others
* Open a terminal by doing Finder -> Applications -> Utilities -> Terminal
* Run "sh /Users/your_user_name/xowa/xowa_macosx"
* If "xowa_macosx.sh" doesn't work, run "java -Xmx256m -d32 -XstartOnFirstThread -jar /Users/your_user_name/xowa/xowa_macosx.jar"


== USAGE ==
=== Setting up Simple Wikipedia ===
* Once XOWA loads, you will see the Main Page
* Go to the "New users" section and click the link for "Set up Simple Wikipedia". Wait about 3 minutes for the wiki to download and install. When it is finished, it will open Simple Wikipedia
* Browse Simple Wikipedia. When you are done, click on the Main Page link under XOWA in the left hand navigation bar.

Here are some example pages to visit (you can copy and paste these into the address bar):
* http://simple.wikipedia.org/wiki/Gothic_architecture
* http://simple.wikipedia.org/wiki/Saturn_(planet)
* http://simple.wikipedia.org/wiki/Chess
* http://simple.wikipedia.org/wiki/World_History

=== Setting up other wikis ===
* If you want to load English Wikipedia or any other wiki, do any of the following:
** Click on "Import Online" on the XOWA Main Page
** Enter "Help:Import/List" in the address bar near the top of the screen
** Using the Menu, do "Tools" -> "Import online"

=== Downloading offline thumbs ===
* If you want to download a complete set of images for your wiki, see the following links:
** For instructions, see: http://gnosygnu.github.io/xowa/setup_simplewiki.html and http://gnosygnu.github.io/xowa/setup_enwiki.html
** For a list of image databases see http://gnosygnu.github.io/xowa/image_dbs.html or https://archive.org/search.php?query=xowa


== TROUBLESHOOTING ==
=== Windows ===
==== Administrator privileges ====
If you're on Windows Vista, 7, 8, or 10, try running the program with administrator privileges. You can do so by right-clicking on the exe and choosing "Run as administrator"

==== XULRunner ====
Try double-clicking the xulrunner.exe.
* Go to C:\xowa\bin\windows_64\xulrunner_v24 (or on 32-bit machines, C:\xowa\bin\windows\xulrunner_v24)
* Double-click xulrunner.exe
* You should get a message box that starts off with "Mozilla XUL Runner "
* If it fails with "Can't start because MSVCR100.dll is missing...try reinstalling to fix...", then you will need to install the Visual C++ redistributable. See http://sourceforge.net/p/xowa/discussion/general/thread/cc7d867d/?limit=25&page=1#8d38 or http://answers.microsoft.com/en-us/windows/forum/windows_7-windows_programs/trying-to-open-computer-management-the-program/5c9d301a-2191-4edb-916e-5e4958558090?auth=1

==== Run by command-line ====
If the .exe fails, you can try running the jar by the command-line.
* Click on Start and go to Run
* Enter "cmd". A console shows up.
* Enter "java -Xmx256m -jar C:\xowa\xowa_windows_64.jar"

==== Run using a specific JRE ====
* Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html
* Click the "Download" button under "JRE"
**  Choose the Windows x86 version
::  As of the time of this writing, "Windows x86 Offline" links to http://download.oracle.com/otn-pub/java/jdk/7u40-b43/jre-7u40-windows-i586.exe
**  Choose an installation folder. For example, "C:\Program Files (x86)\Java\jre7_x86"
**  After installing, run the following in the command-line: "C:\Program Files (x86)\Java\jre7_x86\bin\java" -Xmx256m -jar C:\xowa\xowa_windows.jar

==== Java installation ====
Check that your Java installation is installed correctly
* Run the following in the command-line: "java -version"
* It should report "java version "1.7****" or higher

==== Arabic characters in path ====
XOWA cannot run in a folder with Arabic characters due to a limitation in one of its sub-components (SWT). For example, C:\موسوعات\XOWA will not work. On the other hand, C:\encyclopedia\XOWA will work. For more info, see https://bugs.eclipse.org/bugs/show_bug.cgi?id=443044

=== Mac OS X ===
==== Missing Java ====
If you get a "No Java runtime present" you will need to set up Java on your machine. There are two options:
* Update to the latest Java 6 by going to http://support.apple.com/kb/DL1572?viewlocale=en_US
: This will be simpler. However, note that Java 6 is an older obsolete version.
* Download Java by going to java.com
: This will be the most up-to-date Java version. However it requires additional steps.

To install Java, do the following:
* Find your Java runtime: Run "/Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java -version" in the terminal to verify the path
* Assuming your java is at the above location, run XOWA by doing either of the following
: (1) Run the following from the terminal:
:     /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java -Xmx256m -XstartOnFirstThread -Xdock:name=XOWA /Users/your_user_name/xowa/xowa_macosx_64.jar
: (2) Change your official java to the plugin version and then run xowa_macosx_64.sh
:     sudo ln -fs /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java /usr/bin/java

=== Linux ===
==== Symbolic links sometimes fails ====
XOWA sometimes fails to import large wikis when symbolic links are in the directory. See: https://github.com/gnosygnu/xowa/issues/16#issuecomment-127458416

==== Downloads fail with "ssl peer shut down incorrectly" ====
On some systems, XOWA fails to download any files with the message "ssl peer shut down incorrectly". The underlying cause is currently unknown, and any insight is appreciated here. It may be related to old Java versions or atypical network setups (VPN?).

The fix was to specify https.protocols=TLSv1 in the startup. For example:
* On Windows: "java -Dhttps.protocols=TLSv1 -Xmx256m -jar xowa_windows_64.jar"
* On Linux: "export SWT_GTK3=0 && java -Dhttps.protocols=TLSv1 -Xmx256m -jar xowa_linux_64.jar"
* On Mac OS X: "java -Dhttps.protocols=TLSv1 -Xmx256m -jar xowa_macosx_64.jar"

=== OpenSUSE and "java.lang.InternalError at sun.security.ec.SunEC.initialize" ===
Recent versions of OpenSuse and Java 1.8 may throw an error like the following:

    Exception in thread "wiki.import" java.lang.InternalError
    at sun.security.ec.SunEC.initialize(Native Method)

To workaround this issue, try the following:

* Open up the following file in text editor:
: /xowa/user/anonymous/app/cfg/os.lnx_64.gfs
* Change line 17 as per the following:
: old: browser_type = 'mozilla'; // 'mozilla' or 'webkit'
: new: browser_type = 'webkit'; // 'mozilla' or 'webkit'

For more info, see https://github.com/gnosygnu/xowa/issues/151

=== Minimal XFCE desktop may fail with org.eclipse.swt.SWTError: No more handles === 
Running on a minimal XFCE desktop may throw an error like the following

    Error: org.eclipse.swt.SWTError: No more handles
    Stack: org.eclipse.swt.SWT.error(Unknown Source)
    org.eclipse.swt.SWT.error(Unknown Source)

To workaround this issue, install the following libraries:
* libjavascriptcoregtk-1_0-0
* libwebkitgtk-1_0-0
* libwebkitgtk2-lang

For more info, see https://github.com/gnosygnu/xowa/issues/151

=== Raspberry PI: rror: java.lang.UnsatisfiedLinkError: Could not load SWT library. Reasons: no swt-pi-gtk-3833 in java.library.path ===
This error occurs because the swt.jar at /xowa/bin/arm/swt/swt.jar is included from a Raspberry PI B installation and it has libraries for 3833.

This swt.jar (3.8.1) will not run on Raspberry PI 3 or Raspberry PI 4 devices. In addition, these devices will need to install the requisite swt libraries.

To fix the issue, run the following script

<pre>
# install swt gtk-3 libs and, most importantly, swt-gtk-3.8.jar
sudo apt-get install libswt-gtk-3-jni libswt-gtk-3-java libswt-webkit-gtk-3-jni libwebkitgtk-1.0-0

# overwrite xowa's swt jar with the swt-gtk-3.8.jar
cp /usr/share/java/swt-gtk-3.8.jar /home/pi/xowa/bin/arm/swt/swt.jar

# install swt cairo jni (else XOWA will fail citing these libs)
sudo apt-get install libswt-cairo-gtk-3-jni

# launch xowa
java -jar xowa_arm.jar
</pre>

For more information, see https://github.com/gnosygnu/xowa/issues/535


=== Setting up HTTP Server for Linux ===
* Change xowa_linux_64.sh to something like the following: "java -Dhttp.proxyHost=YOUR_PROXY_HOST -Dhttp.proxyPort=YOUR_PROXY_PORT"
* Install "java-1_8_0-openjdk-headless and libcap-progs"
* (Optional: To listen on port 80) Run "setcap CAP_NET_BIND_SERVICE=+eip /usr/lib64/jvm/jre-1.8.0-openjdk/bin/java"

== CHANGE LOG ==
== v4.6.5.1911 (2019-11-25) ==
'''major'''
* Category: Fix 'A table in the database is locked' when importing en.d. {detected by anonymous}
: Issue: https://github.com/gnosygnu/xowa/issues/543

* Wikibase: Fix 'Module:Infobox/Cycliste:218 attempt to call nil' on many fr.w pages. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/551

'''significant'''
* Wikibase: Fix 'Module:Cycling race:4290 attempt to concatenate nil and string' on some dozen fr.w pages. {detected by desb42}
: Resolved by: Return label and language, not just label.
: Links: https://fr.wikipedia.org/wiki/Boels_Ladies_Tour_2016
: Issue: https://github.com/gnosygnu/xowa/issues/407

* Wikibase: Fix 'Module:Location map:414 No value was provided for longitude' on several dozen en.w pages. {contributed by desb42}
: Resolved by: Show 'unknown value' / 'no value' instead of 'somevalue' / 'no value'.
: Links: https://en.wikipedia.org/wiki/Wild_Goose_Pass_Tree
: Issue: https://github.com/gnosygnu/xowa/issues/529

* Wikibase: Fix 'method not implemented' when calling mw.wikibase.getSetting. {detected by desb42}
: Resolved by: Add namespacing to Scribunto libraries.
: Issue: https://github.com/gnosygnu/xowa/issues/551

* Wikibase: Fix missing references on many fr.w pages. {detected by desb42}
: Resolved by: Serialize 'references'.
: Links: https://fr.wikipedia.org/wiki/VLC_media_player
: Issue: https://github.com/gnosygnu/xowa/issues/587

* Wikibase: Work-around 'Module:PropertyLink:167 attempt to call nil' on many he.w pages. {detected by desb42}
: Resolved by: Redirect formatValue and formatValues to renderSnak and renderSnakValues.
: Links: https://he.wikipedia.org/wiki/יובל_נאמן
: Issue: https://github.com/gnosygnu/xowa/issues/593

* Luaj: Fix Script error '=Module:ru-noun:1254 Too many arguments for argument set' on several dozen en.d Russian pages. {detected by desb42}
: Resolved by: Do not treat '_' as a SPACE character.
: Links: https://en.wiktionary.org/wiki/бабье_лето
: Issue: https://github.com/gnosygnu/xowa/issues/582

* Luaj: Fix '=Module:Fallback/sandbox:108 bad argument: string expected, got nil' on several dozen common pages. {detected by desb42}
: Resolved by: Return NIL not remove for table.remove and empty table.
: Links: https://commons.wikimedia.org/wiki/United_Kingdom
: Issue: https://github.com/gnosygnu/xowa/issues/604

* Luaj: Fix 'Module:Historical populations:60 attempt to perform arithmetic __sub on nil and number' on several dozen en.w pages. {detected by desb42}
: Resolved by: Do not treat superscript 1 as a DIGIT character.
: Issue: https://github.com/gnosygnu/xowa/issues/617

* Scribunto: Fix non-translated pages in en.d. {detected by desb42}
: Resolved by: Make table accessible from datawrapper in mw.lua.
: Links: https://en.wiktionary.org/wiki/Wiktionary:Japanese_transliteration
: Issue: https://github.com/gnosygnu/xowa/issues/586

* Scribunto: Fix 'Erreur de script: =Module:String:737 attempt to call nil' on many fr.s Author pages. {detected by desb42}
: Resolved by: Synchronize latest ustring.lua.
: Links: https://fr.wikisource.org/wiki/Auteur:Victor_Hugo
: Issue: https://github.com/gnosygnu/xowa/issues/609

* Scribunto: Improve load-time of Chinese pages on en.d. {detected by desb42}
: Resolved by: Cache results of title.exists.
: Issue: https://github.com/gnosygnu/xowa/issues/597

* Scribunto: Fix 'Module:Wd:162 attempt to call nil' on many en.w pages. {detected by desb42}
: Resolved by: Synchronize latest mw.wikibase.entity.lua.
: Issue: https://github.com/gnosygnu/xowa/issues/614

* Scribunto: Add HashLibrary. {contributed by desb42}
: Links: https://de.wikipedia.org/wiki/NetBSD
: Issue: https://github.com/gnosygnu/xowa/issues/589

* ParserFunctions: Fix '=Module:Pg:51 attempt to index ?' on several commonswiki pages. {detected by desb42}
: Resolved by: Add ParserFunction for PageLanguage.
: Links: https://commons.wikimedia.org/wiki/Commons:Structured_data
: Issue: https://github.com/gnosygnu/xowa/issues/595

* Html_dump: Fix redlinks on many pages. {contributed by desb42}
: Resolved by: Include namespace+title in redlink ttl, not just title.
: Issue: https://github.com/gnosygnu/xowa/issues/568

* Html_dump: Show images for files with url-encoded characters (space, symbols, non-ascii).
: Issue: https://github.com/gnosygnu/xowa/issues/547

* Pagebanner: Do not repeat table of contents on wikivoyage pages.
: Resolved by: Disable toc if pagebanner html exists; also, sync PageBanner css.
: Issue: https://github.com/gnosygnu/xowa/issues/610

* Pagebanner: Fix showing only enlarged top-right corner for some en.v pagebanners.
: Resolved by: Add extra space after hasPosition or some pageBanners will omit wpb-banner-image.
: Issue: https://github.com/gnosygnu/xowa/issues/618

* Template_styles: Fix single-word paragraphs at the start of many en.v pages.
: Resolved by: Close block opened by template-styles.
: Issue: https://github.com/gnosygnu/xowa/issues/616

* Category: Fix failed 2019-10 hewiki import.
: Resolved by: Add basic enums for 'numeric' and 'identity'.
: Issue: https://github.com/gnosygnu/xowa/issues/597

* Search: Fix no search results for en.d. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/606

* References: Fix duplicated text on many en.s Page pages. {detected by desb42}
: Resolved by: Ignore follow items when writing primary reference.
: Links: https://en.wikisource.org/wiki/Page:Writings_of_Saint_Patrick,_Apostle_of_Ireland.djvu/154
: Issue: https://github.com/gnosygnu/xowa/issues/555

* Setup.PI: Add instructions for fixing 'Could not load SWT library. Reasons: no swt-pi-gtk-3833 in java.library.path' on Raspberry PI 3+ devices to readme.txt. {detected by anonymous}
: Links: readme.txt
: Issue: https://github.com/gnosygnu/xowa/issues/535

'''minor'''
* Html_dump: Add missing file for showing configuration to show WIKITEXT / HTML indicators in top-right. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/525

* Parser: Fix repeated header on a few en.w pages. {detected by desb42}
: Resolved by: Do not reuse byte array when trimming bfr.
: Links: https://en.wikipedia.org/wiki/Towson_University_buildings_and_structures
: Issue: https://github.com/gnosygnu/xowa/issues/562

* Parser: Fix 'bad argument: table expected, got nil' on some it.w pages. {contributed by desb42}
: Resolved by: Trim url-encoded space from the end of a title.
: Example: A&#32;.
: Links: https://it.wikipedia.org/wiki/Italo_Toni
: Issue: https://github.com/gnosygnu/xowa/issues/567

* Parser: Do not reset attributes when tag has more than 16 attributes. {contributed by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/579

* Parser: Show missing references on a few en.d pages. {detected by desb42}
: Resolved by: Auto-inline dangling references tag.
: Links: https://en.wiktionary.org/wiki/tepilli
: Issue: https://github.com/gnosygnu/xowa/issues/583

* Parser: Fix failed jawiki import and error 'mid failed: bgn=19 end=13'. {contributed by desb42}
: Resolved by: Do not assume that Name_ui_w_colon matches Name.
: Links: https://ja.wikipedia.org/wiki/Template:Stub
: Issue: https://github.com/gnosygnu/xowa/issues/594

* Wikibase: Combine same references from Wikidata. {contributed by desb42}
: Links: https://fr.wikipedia.org/wiki/VLC_media_player
: Issue: https://github.com/gnosygnu/xowa/issues/596

* Luaj: Fix 'ArrayIndexOutOfBoundsException' on some en.w pages. {detected by desb42}
: Resolved by: Handle % at end of replacement string.
: Issue: https://github.com/gnosygnu/xowa/issues/571

* Xtn.Dpl: Limit number of pages shown to 200 instead of total number of pages in category. {contributed by desb42}
: Resolved by: Change dynamicPageList to always get categories from cache.
: Links: https://en.wiktionary.org/wiki/Category:English_conjunctions
: Issue: https://github.com/gnosygnu/xowa/issues/556

* Xtn.Dpl: Improve performance of Dpl for large categories. {detected by desb42}
: Links: https://en.wiktionary.org/wiki/Category:English_lemmas
: Issue: https://github.com/gnosygnu/xowa/issues/556

* Search: Do not fail with error when searching in wikidata / commons. {suggested by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/539

* Category: Show table of contents on many en.d Category pages. {contributed by desb42}
: Resolved by: Replace spaces with underscores in category name.
: Issue: https://github.com/gnosygnu/xowa/issues/557

* Html: Add 'lang=page_lang' to html and div tag. {contributed by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/576

* Score: Fix NullPointerException on a few dozen en.w Portal pages. {contributed by desb42}
: Resolved by: Check for missing src for score generated images.
: Issue: https://github.com/gnosygnu/xowa/issues/577

* HTTP Server: Generalize file:///root logic even more. {contributed by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/524

* HTTP Server: Redirect xwiki urls to different wikis. {detected by desb42}
: Links: https://en.wikipedia.org/wiki/it:Roma
: Issue: https://github.com/gnosygnu/xowa/issues/600

* HTTP Server: Show error page when navigating to wikis which are not installed. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/613

* Performance: Improve performance of Bry_fmtr. {contributed by desb42}
: Resolved by: Disable dirty flag after formatter is compiled.
: Issue: https://github.com/gnosygnu/xowa/issues/575

'''trivial'''
* Gui: Fix NPE when reloading a MISSING_PAGE at start-up. {detected by desb42}
: Issue: https://github.com/gnosygnu/xowa/issues/608

* Html_dump: Fix 'gplx.Err: counts do not match' during fr.w build. {contributed by desb42}
: Resolved by: Synchronize Xol_name_mgr.
: Issue: https://github.com/gnosygnu/xowa/issues/549

* Html_dump: Try to reduce memory pressure from Xow_defn_cache. {suggested by desb42}
: Resolved by: Count 0 byte entries as 1 byte.
: Issue: https://github.com/gnosygnu/xowa/issues/561

* Mac OS X: Add homebrew instructions for installing ImageMagick / Inkscape. {contributed by anonymous}
: Issue: https://github.com/gnosygnu/xowa/issues/574

