# Options/Popups

From XOWA: the free, open-source, offline wiki application
options link

This page provides options for Popups.

- You can test your changes by reloading this page and hovering over this link: XOWA Main Page.
- For more infomation, visit the Popups help page
- Note that changes will apply automatically to new tabs and new pages. However, any currently loaded pages must be reloaded to pick up the new changes.

## General

Enabled

Controls popup functionality

- checked to show popups when hovering over links
- unchecked to not show popups when hovering over links

## Content (basic)

Number of words to show at start

Number of words to show in popup

- For slower machines, decrease the number of words to 32. Note that the number must be greater than 0.
- For faster machines, increase the number of words as per your liking.

Number of words to show for "more"

Number of additional words to show when "show more" is clicked

- For slower machines, decrease the number of words to 32. Note that the number must be greater than 0.
- For faster machines, increase the number of words as per your liking.

## Content (advanced)

Automatically show "all" if page is less than

Automatically show the entire article if article is less than these number of bytes
This feature is intended for small articles whose entire text...

- Will always be parsed quickly
- Will generally show in one window without a horizontal scroll bar.

It allows a complete preview of small articles without having to click "more" or "all"
To deactivate this feature, set the number to -1

Read forward til header

Number of extra words to read forward to look for a header
This option tries to stop the popup text right before a header.

- the advantage is that the popup will not stop a few words short of the header
- the disadvantage is that the size of the popup is irregular. i.e.: sometimes it returns 128 words, sometimes 140, sometimes 150, etc

To deactivate this option, set it to -1.
Technical details follow.

The approach works in the following manner:

- Reads forward an additional # of words
- If a header is found within the # of words, it extends the popup text to the last word before the header
- If a header is not found, it returns the original # of words

For example:

- An article contains `01 02 03 04 05 06 07 ==08== 09`
- Show-init is set to 5
- Read-fwd is set to 4
- The initial number of words is read and collects 5 words: `01 02 03 04 05`
- The parser then reads forward 4 more words: `06 07 ==08== 09`
- It finds a header at `==08==`
- It then extends the selction to the word just before the header: `01 02 03 04 05 06 07`
- Note that if `==08==` was just `08`, then it would just have returned the original: `01 02 03 04 05`

Read backward til header

Number of words to read backward to remove header at end
This option tries to stop a header from appearing at the end of the popup text.

- the advantage is that a popup will not end at a header with just a few words after it.
- the disadvantage is that sometimes the number of words returned will be less originally requested. i.e.: 128 was requested, but only 112 is returned

To deactivate this option, set it to -1
Technical details follow.

The approach works in the following manner:

- Reads backwards a # of words from the end of the popup
- If a header is found within the # of words, it truncates the output to the text before the header
- If a header is not found, it returns the original # of words

For example:

- An article contains `01 02 03 04 05 06 07 ==08== 09`
- Show-init is set to 9
- Read-bwd is set to 4
- The initial number of words is read and collects 9 words: `01 02 03 04 05 06 07 ==08== 09`
- The parser then reads backwards 4 words: `06 07 ==08== 09`
- It finds a header at `==08==`
- It then truncates the popup to the word just before the header: `01 02 03 04 05 06 07`
- Note that if `==08==` was just `08`, then it would just have returned the original: `01 02 03 04 05 06 07 08 09`

Stop if header is found after

Stops reading if a header is found after # of words
This option will stop reading if a header is found after the # of words. It is useful for increasing the probability that a popup will end at a header.

- the advantage is that a popup can be made to stop at a header. If you never want the popup to show a header, set the value to 1.
- the disadvantage is that sometimes the number of words returned will be less originally requested. i.e.: 128 was requested, but only 96 is returned

To deactivate this option, set it to -1. This will always show as much content as possible
Technical details follow.

The following is a simplified example:

- An article contains `01 02 03 04 05 ==06== 07 08 09 ==10== 11 12 13 14 15 16`
- Show-init is set to 16
- Stop-hdr is set to 8
- The parser starts reading words
- Once it finds a header, it checks if it is greater than stop-hdr
  - `==06==` is found, but it is less than 8. The parser continues.
  - `==10==` is found, and it is greater than 8. The parser stops there and returns `01 02 03 04 05 ==06== 07 08 09`

Note the following variations:

- If stop-hdr was set to 1, then it would have stopped at `==06==` and returned `01 02 03 04 05`
- If stop-hdr was set to 14, then it would have returned the entire text: `01 02 03 04 05 ==06== 07 08 09 ==10== 11 12 13 14 15 16`

Note that the the read-bwd setting is still applied after the stop-hdr setting.

## Window

Number of milliseconds before showing popup

Number of milliseconds to wait before showing popup

- A higher number prevents accidental hovers over links while moving the mouse / scrolling the page
- A lower number allows faster popup display

Note that popup data will only be retrieved after the popup starts showing. For example:

- If the show delay is set to 2 seconds
- and a popup takes 1 second to retrieve the html
- then the total time till the popup is visible is 3 seconds, not 2 (2 seconds to wait before showing + 1 second to retrieve data)

Number of milliseconds before hiding popup

Number of milliseconds to wait before hiding popup

- A higher number allows the popup to linger longer on the screen before disappearing.
- A lower number hides the popup faster

Maximum width of window

Maximum width of popup in pixels

- -1 indicates no maximum width

Maximum height of window

Maximum height of popup in pixels

- -1 indicates no maximum height

Maximum width of window when "show all"

Maximum width of popup in pixels when show all is clicked
This option was added because:

- The normal popup window is generally smaller (500 pixels)
- Show all often returns a lot of article text which looks constrained within a 500 pixel window
- A "Show all" maxiumum width allows for automatic switching to a wider window for the larger article content

Note that -1 indicates no maximum width, which defaults to about 500 pixels

Show popup when link is focused

Shows popup when link receives focus (tabbed into)
This option allows keyboard users to use popups whenever a link is focused. Specifically:

- A link can be focused by pressing tab on the keyboard until a dotted focus box surrounds the desired link.
- A link can be focused by finding and then selecting:
  - Find a word on the page. For example, press Ctrl + F and type "r i b". This will highlight the Scribunto link
  - Press Ctrl + G and then Ctrl + G again. This will focus the Scribunto link and show the popup for it.

## Performance

Template token max

Maximum length of template token (in bytes) to evaluate
This option allows faster popups, but at the cost of accuracy:

- Fast but sometimes inaccurate: For slow machines or wikis that use templates heavily, decrease the number. Note that setting the number to 0 means "never evaluate templates". If popups are slow, try setting the number to 0, and see if the results are satisfactory.
- Slow but always accurate: For fast machines or wikis that do not use templates heavily, increase the number. Note that setting the number to 2,147,483,647 means "always evaluate templates". You can also use "-1" as a shortcut for "2,147,483,647". If popups have garbled text or are missing words, try setting the number to -1.

A more detailed explanation follows:

Templates are wikitext of the form `{{Name|Arg_1|Arg_2|...}}`. They are used throughout a wiki to perform functions ranging from unit conversion (like converting kilometers to miles), or generating large pieces of HTML (like rendering entire InfoBoxes). However, these templates are the "slowest" pieces of wikitext to parse, particularly if they call other templates or Scribunto

Ideally, popups should skip templates that produce structural html (like infoboxes), while still trying to render templates that do smaller functions (like converting units). This option attempts a heuristic that says "if the template is long, assume it's an infobox and should be skipped". It counts the total number of bytes in a template, and skips it if it's greater than the max. For example, `{{Name|Arg_1}}` has a length of 10, and will be skipped if the max length is set to 8. If the max length is set to 16, then the template won't be skipped.

This option is imperfect, but should work well enough on most cases. Note that Navigation Popups does something similar by skipping template text, but without any configuration. (always set to 0).

Template keeplist
en.wikipedia.org|formatnum;age;age_in_days;age_in_years_and_days*;nts;number_table_sorting*;as_of;oldstyledatedy;gregorian_serial_date;currentminute;currentsecond;dmca;spaced_ndash;trim;month*;convert*;worldpop*;ipa*;lang*;nowrap*;h:*;mvar;math;vgy;audio;iso_639_name;transl;translate;linktext;zh;nihongo*;japanese_name;ko-hhrm;mp|

Specifies templates to be shown in popup
This is a performance optimization for English Wikipedia. It only evaluates listed templates.
The format is as follows

- Each rule is in a separate line
- Each rule has three parts
  - Wiki domain: Wiki which will be affected by rule
  - Keep-names: Names of templates which will be shown in popup. Note that these names:
    - Are semi-colon separated (`;`)
    - Match any case of the title. For example, "NAme", matches "NAME", "name", "naME", etc.
    - Match space or underscore. For example, "two_words" matches "two_words" and "two words"
    - Have one of the following three match patterns
      - Exact name: For example, "name" matches only "name", and all lowercase/uppercase variants
      - Name at start: For example, "name*" will match anything starting with "name" such as "Names"
      - Name at end: For example, "*name" will match anything ending with "name" such as "Fullname"
  - Unless-names: Names of templates which should not be included, even if the keep-name is matched. For example, `en.wikipedia.org|name*|name_to_always_skip` will match any template that starts with "name" unless the template is named "name_to_always_skip". Note that unless-names have the same rules as keep-names (semi-colon separator; wildcards)

To disable this option, replaces the keep-names with a *. For example: `en.wikipedia.org|*|`

Default option

    en.wikipedia.org|formatnum;age_in_days;as_of;gregorian_serial_date;currentminute;currentsecond;dmca;spaced_ndash;trim;month*;convert*;worldpop*;ipa*;lang*;nowrap*;h:*;vgy;iso_639_name;transl;translate;linktext;zh;nihongo;japanese_name;ko-hhrm;|

## Advanced

Allowed namespaces

Restrict popups to certain namespaces
This option allows popups to be suppressed for namespaces that would ordinarily generate no content. For example, Portal pages are often contained in a table / div, whereas Module pages are code.
Note the following:

- Only namespace names are valid. See the table below for examples of valid names
- Multiple names must be separated with the pipe character (`|`). For example, `(Main)|Help`
- Namespaces names are the canonical English names of the namespace, except for "(Main)"
- Non-English names will work, but are not supported. For example, `Aide` would only allow the Help namespace in French wikis, wheras `Help` will allow the Help namespace across all wikis.
- Invalid names are ignored
- Deactivate this feature by blanking the field

Title
(Main)
User
Project
File
MediaWiki
Template
Help
Category
Special

Ignore HTML elements with the following ids

Ignore html elements that have the following ids
This feature is intended for English Wikipedia which has a `{{Coordinates}}` tag at the top of most geographical articles (for example, North Pole)
Without this option, a Coordinates span would be visible in the top right of the popup, which....

- Counts against the popup's number of words
- Does not provide significant summary information for the article

Usage notes:

- Any HTML element with a listed id will not be shown in the popup. For example, `<span id='coordinates'>0 N 90 E</span>` will not show b/c the html element (`span`) has a listed id (`coordinates`)
- To add multiple ids, separate ids with the `|` character. For example, `coordinates|some_other_id`.
- Listed ids are case-insensitive if ASCII, but case-sensitive otherwise. There is no difference between `coordinates` and `Coordinates`. There is a difference between `é` and `É`
- To deactivate this feature, set the value to `` (empty)

Number of bytes to read each pass

Number of bytes to read for each pass
This number represents the number of bytes the popup parser reads at a time. For example, it will read the first 1024 bytes of the article, and if it doesn't find 64 words, it continues to read sections of 1024 bytes until it does.

- Lower numbers may be better for slower machines. Note that the number must be greater than 0.
- Higher numbers may be better for faster machines. Experiment as necessary.

Maximum number of bytes to read

Maximum number of bytes to read

This number represents the maximum number of bytes the popup parser reads before it gives up. Note that if the parser gives up, then no text will be returned for the preview.

This setting should only apply to badly formatted articles. For example consider a page that has a comment with 100,000 5 letter words (`<!-- 100,000 5 letter words -->`). This page will be considered to have 0 words, even though it has a page length of 500,000. Rather than read the entire 500,000 bytes, the popup parser will stop after 32,768.

- Lower numbers may be better for slower machines, but it would have a higher chance of returning empty popups. Note that the number must be greater than 0.
- Higher numbers may be better for faster machines. To force the popup parser to read the entire page until it finds the minimum number of words, set the value to a high number like 2,147,483,647

### XOWA

- Main page
- Screenshots
- Video
- Download XOWA
- Download wikis

### Getting started

- Requirements
- Installation
- Simple Wikipedia
- English Wikipedia
- Other Wikipedias

### Android

- Setup
- Video

### Help

- About
- Contents
- Media
- Feedback

### Blog

- Current

### Links

- Wikimedia dumps
- XOWA @ archive.org
- English Wikipedia

### Donate

- archive.org
- Wikipedia
- XOWA