User:Eisheeta/Sandbox/Manual:Huggle

Welcome to Huggle! This is the comprehensive manual for the installation and use of Huggle. Please browse to your heart's content.

What is Huggle?
Huggle is a fast diff browser application intended for dealing with vandalism or other unconstructive edits on Wikimedia projects, written in C++ using the Qt framework. It was originally developed in .NET Framework by Gurch, who is no longer active on this project. Anyone can download Huggle, but rollback permission is required to use it without restrictions on the English Wikipedia.

Huggle is able to load and review edits made to Wikipedia in real time, helps users identify unconstructive edits, and allows them to be reverted quickly. Various mechanisms are used to draw conclusions to whether an edit is constructive or not. It uses a semi-distributed model where edits are retrieved using a "provider" (this can be anything that is capable of distributing a stream of edit information, such as the Wikipedia API or IRC recent changes feed), pre-parsed and analyzed. This information is then shared with other anti-vandalism tools, such as ClueBot NG. Huggle also uses a number of self-learning mechanisms, including a global white-list (users that are considered trusted) and user-badness scores that are stored locally on the client's computer.

How does it work?
Huggle is connected to MediaWiki through a network API and retrieves a list of edits that are made to a wiki in real time. Huggle evaluates these edits and moves them to a queue from which user can open them. If an edit contains problems, the user can easily revert it, usually with a shortcut key such as Q (by default this reverts the edit and warns the user who made it).

What are the system requirements for using Huggle?
Huggle 3 works on macOS, Linux and Windows directly. Huggle 2 works only on Windows XP, Windows Vista, and Windows 7, but also conditionally via Wine on macOS and Linux (more information).

Quick Start
The following pages are quickstart pages, intended for new users of Huggle:

To begin Huggle, You need to log in. Either choose the Bot or Legacy log in. The legacy login requires your normal password. Once you have logged into Huggle You will see a box labeled "Queue" Leave the Queue on default and click on any title inside the box (Once you have done this you may then use the spacebar to go on to the next Queue).

Controls

 * As Listed above...


 * Clicking on the pencil that is green with the checkmark will flag the edit as a good edit.
 * Clicking on the yellow pencil with the "!" will revert the edit and warn the user
 * Clicking on the yellow pencil with nothing on it will revert the edit
 * Clicking on the ! will warn the user without reverting the edit
 * To welcome a user click on the green happy face (not listed above)
 * For more options click on the drop down menu, To Use it click the black down arrow ( Be careful when opening the drop down menu and make sure to click the down arrow and not the symbols, otherwise it WILL revert WITHOUT warning!!! [If you clicked the symbol and not the arrow by accident, quickly press the ESC key])

Keyboard Shortcuts/Controls

 * Spacebar - Move onto next Queue
 * Q   -  Revert edit and warn user (For Vandalism only)
 * Alt + X -  Add page to watchlist ( Not sure if this applies to all systems, It says to use L on the manual of shortcuts, though this control may vary from system to system)
 * Alt + C - Remove the page from watchlist  ( Not sure if this applies to all systems, It says to use L on the manual of shortcuts, though this control may vary from system to system)
 * ESC  - Cancels current action being performed
 * F5  -  Refreshes the  page

Tabs
You may wish to open a new tab by clicking the "+" icon on the tab. When You open a new tab, you can monitor the page you were editing, while looking for more vandalism in the new tab.

Log Out
To Log Out of Huggle Go to System then click on Exit.

Installation
Huggle is very easy to install.

That's it! Huggle should be fully operational.
 * Step 1: Go to the download page and download the latest stable version for your operating system.
 * Step 2: Follow the instructions on download page in order to install Huggle.

Windows
Huggle is distributed in 3 flavors for windows:


 * MSVC-32: Windows Vista and newer for 32-bit CPU
 * MSVC-64: Windows Vista and newer for 64-bit CPU
 * MinGW-32: All Windows versions for 32-bit CPU, may run slower than the MSVC versions.

If you are switching between MinGW and MSVC versions, you may need to purge your current Huggle (uninstall and delete all leftovers from Program Files) prior to re-installation of Huggle.

Mac OS
Download the .dmg file from download page, open it and copy huggle to your Applications folder. Huggle should appear in the Launchpad immediately.

Debian
In a terminal window with superuser privileges (su or sudo), copy and paste as a single line.

To start the Huggle application type:

Installation for Ubuntu and Linux distributions with snap
On all linux distributions with snap preinstalled (such as Ubuntu 16.04 and newer), Huggle can be installed as easily as this:

sudo snap install huggle

Uninstalling Huggle
To uninstall Huggle, follow these instructions. If you want to remove all of your configuration options, blank Special:Mypage/huggle3.css or Special:Mypage/huggle.css

Windows
There should be shortcut to "uninstall Huggle", using that will uninstall Huggle. On Windows, there may be some leftovers in your Program Files (under the folder Huggle) which can also be deleted. Your personal configuration is in AppData/Local/Wikimedia/Huggle and can be also deleted if you want.

Mac OS
Just delete Huggle from your Applications folder. You may also delete your personal configuration that can be found in ~/Library/Application Support/Wikimedia/Huggle.

Debian / Ubuntu
You can safely remove Huggle using Package Manager.

Compiled
When you ran the "make install", a file called install_manifest was generated in current folder. It contains the location of all files there were installed. By removing these files you will uninstall Huggle.

See http://www.cmake.org/Wiki/CMake_FAQ#Can_I_do_.22make_uninstall.22_with_CMake.3F for more information.

Installing Huggle on custom Wikimedia Installation
Huggle3 can be used with any mediawiki installation, however keep in mind that it was originally created for WMF wikis, which can be considered a large wiki farm. For this reason huggle is designed mostly for large wiki farms and in order to run it on single small wiki, you may need to slightly tweak it. This guide is covering installation to any wiki.

Huggle Home
There is a special folder in huggle which is called huggle home. This folder is displayed by huggle in logs when it starts, for example:

Wed Feb 11 10:01:47 2015  Home: /home/petanb/.local/share/data/Wikimedia/Huggle/

This folder contains all configuration files of huggle and we will refer to it as huggle home or $huggle_home in this manual. It is possible to have multiple homes in order to create a number of separate huggle installations that are running isolated from each other by passing argument --chroot. If you want to use huggle with WMF wikis and your own wiki farm, it is recommended to create 2 homes for it. If you only want to use huggle for 1 wiki farm, you can ignore this.

Global Wiki
Since huggle is designed to run on wiki farms, it requires 1 wiki that is called "global wiki" this wiki contains global configuration file that has the information about individual wikis. In case you have only 1 wiki, you will need to make it a global wiki as well, so that you will have both global and local configuration file there.

Configuration files
See 

Huggle is using 4 configuration files in following order:


 * $huggle_home/Configuration/huggle3.xml Local configuration on pc where it is installed - this file contains URL of global wiki
 * Huggle/Config Global configuration on global wiki which contains information about local wikis
 * Project:Huggle/Config Local configuration on wiki to which you login
 * User:$NAME/huggle3.css User configuration on local wiki

Step by step deployment on 3rd wiki farm
In this scenario we have a wiki farm with 4 wikis on domains:


 * meta.testfarm.wmflabs.org
 * wiki1.testfarm.wmflabs.org
 * wiki2.testfarm.wmflabs.org
 * wiki3.testfarm.wmflabs.org

On meta.testfarm.wmflabs.org/wiki/Huggle/Configuration we need to have following content:

enable-all:true

version:3.1.0 min-version:3.1.0

config:Project:Huggle/Config documentation:https://www.mediawiki.org/wiki/Manual:Huggle feedback:https://en.wikipedia.org/wiki/Wikipedia:Huggle/Feedback // Only if you have irc recent change stream for your wikis - this is optional // irc-server:irc.wikimedia.org // irc-server-name:irc.wikimedia.org

user-agent:Huggle/$1 http://en.wikipedia.org/wiki/Wikipedia:Huggle user-config:Special:Mypage/huggle.css user-config-hg3:Special:Mypage/huggle3.css

// URL of your whitelist server, if you don't have any, keep this commented out // whitelist-server:http://huggle.wmflabs.org/data/

In Project:Huggle/List put

Important xmlrcs_name is name of your wiki as seen by XmlRcs provider, if you don't have this provider, you can remove it from XML entry. Same applies for wl (whitelist id).

Now on each of these 3 wikis, you put this in Project:Huggle/Config.yaml

Now all you need is update the huggle local configuration, open $huggle_home/Configuration/huggle3.xml and change



to



Now you can start huggle and hit reload button. It should load a list of local wikis. Since now you should be able to use huggle on your wikis.

Note: If your wiki doesn't support HTTPS you must not check it on login form

Startup


When you first start Huggle, you should see a login screen.

At this login screen, you can select the project that you want to log on to from the drop down list. You can also select a language other than English for Huggle to use for text prompts and buttons.

Enter your project username and password.

Huggle will then log you in, check that your account has permission to use it, and read various data pages.

It is also possible to login to multiple projects within a single session.

You can do so by clicking on the Projects >> button, which would show a list of available projects.


 * Username — Your project username
 * Password — Your project password
 * Project — Drop down list that contains all of the projects that Huggle can work with
 * Language — The language that objects inside Huggle will be displayed in


 * Use HTTPS (requires OpenSSL)— Force Huggle to use a secure connection to connect to the project.

Interface
This is Huggle's interface.





Keyboard Shortcuts
Operating Huggle is quicker when you use keyboard shortcuts. Note that giving focus to the browser window prevents shortcuts working; click any button to take focus from the browser window. Keyboard shortcuts may be customized; go to System → Options... and select the Keyboard tab.

Main

 * Space – Show next diff
 * Q – Revert and warn
 * R – Revert
 * Y – Revert with custom edit summary
 * T – Post template message
 * W – Warn without reverting
 * Escape – Cancel current action being performed

Navigation

 * [ – Browse back
 * ] – Browse forward
 * Z – Previous revision
 * X – Next revision
 * C – Current revision
 * Ctrl + Z – Previous contribution
 * Ctrl + X – Next contribution
 * Ctrl + C – Latest contribution
 * D – Show diff to current revision
 * O – Open page in external browser, this as mentioned above will prevent further keyboard shortcuts from working.
 * + – New tab
 *  –  – Close tab
 * Tab – Next tab
 * Shift + Tab – Previous tab

Page

 * V – View page (this revision)
 * Ctrl + V – View page (latest revision)
 * E – Edit page
 * G – Tag page
 * S – Tag page for deletion
 * Ctrl + S – Nominate page for deletion
 * P – Prod tag page
 * Ctrl + P – Mark as patrolled
 * Ctrl + D – Delete page
 * L – Watch / Unwatch page

User

 * I – Ignore user
 * Ctrl + I – Unignore user
 * / (?) - Show user info
 * A – View user talk page
 * N – Message user
 * B – Report user / Block user

Other

 * H – Retrieve history for current page
 * U – Retrieve contributions for current user
 * K – Toggle "show new edits"
 * M – Show new messages
 * Ctrl + Space – Clear queue

Statistics View
The statistics form shows:
 * The length of time you have been in your current session
 * Number of edits, assisted edits, Huggle edits, reverts, warnings, reports, tags, notifications, blocks, deletions and protections



Closing Huggle
The closing window appears when Huggle is closing. This goes through the stages of updating the whitelist (if needed) and updating the user config (if needed).



Additional Help


If you need any more help, or have any questions about Huggle, please visit us in the  IRC2>Special:MyLanguage/MediaWiki on IRC|IRC channel and ask away.