Installing a module is easy: Create a subdirectory called modules in your DataDir directory, and put the Perl file in there. It will be loaded automatically.

Ordinary linking is simple: Just type the page name in double square brackets or use CamelCase. When a page does not exist, Oddmuse will append a question-mark to the page name which links to an edit page. When you enable near-links to some other site, then ordinary links to inexisting pages will automatically link to that other site, if the page exists on the other site.

The page MeatballWiki exists on Meatball, but not on Community Wiki. When you’re on Community Wiki and write “MeatballWiki” on a page, this will link to the MeatballWiki page on Meatball. Without near-linking there would have been a question-mark linking to the edit-page for MeatballWiki on Community Wiki.

This is closely related to URL Abbreviations. The page InterMap lists the existing URL abbreviations and how they should be expanded. Near links require a similar page called NearMap. It lists a subset of the URL abbreviations on the InterMap and how to fetch the list of all pages from that site.

You need to be an administrator to edit the InterMap and NearMap pages. See Passwords for how to set this up.

Updating the list of pages on the near-linked wikis

Whenever maintenance runs, Oddmuse will fetch the list of pages from every wiki on the NearMap and store these lists in a directory on the server.

This requires the LWP::UserAgent module. See Perl Modules for details.

Showing twin pages

In addition to that, Oddmuse will show at the bottom of each page if that page also exists on other wikis on the NearMap (so called “twin pages” on “sister sites”). If so, a logo will be used to indicate this. You should provide a logo for every site on your NearMap.

Screenshot

See Near Links Screenshot. On the screenshot, you can see a near-link to CommentPage (in green instead of blue). At the bottom you see the Meatball logo, which tells you that the page SandBox also exists on Meatball (and clicking on the logo will take you there). At the bottom you will also find the opportunity to create CommentPage locally. (Since following the link will take you to MeatBall:CommentPage, you need a little extra help to create the page locally.)

When you search for a term, Oddmuse will search page titles and page content. Since page titles from sites on the near map are also available locally, these will be searched as well. The page content from remote sites is not available, however, and therefore it cannot be searched directly. You can tell Oddmuse how to search the remote sites, however: On the NearMap, add a third column with the search URL. Use a %s for the search term.

Setup Examples

For Oddmuse wikis, you need to use the search parameter with the raw=1 parameter. You may want to use near=1 or near=0. Use near=1 if the remote wiki has itself wikis on the near map which you do not have on the near map. Use near=0 if the wiki has the same near map as your own. Here is an example for the community wiki. The three items have to be all on one line, with one leading space:

Community http://www.emacswiki.org/cgi-bin/community?action=index;raw=1 http://www.emacswiki.org/cgi-bin/community?search=%s;raw=1;near=0

Technically, Oddmuse requires a RSS 3.0 feed of the search from the remote site. See References for details about RSS 3.0. Some wiki engines such as UseMod don’t support that format. All they support is ordinary HTML. Here are some scripts to munge the output:

This has to be an URL where the logos can be downloaded. The expression %s in the URL will be replaced by the URL abbreviation.

Example:

If you store your logos in the server directory /org/emacswiki.org/html/pics/, and /org/emacswiki.org/html/ is your document root, then the pictures will be available for download from the outside using pics or http://example.com/pics/. Set $SisterSiteLogoUrl as follows, if the logos are .jpg files:

The name of the page where the NearMap is stored. There is usually no reason to change this value.

When this page is processed, only the pages starting with exactly one space are processed. Line is made up of the starting space, the URL abbreviation, another space, the URL to get the plain-text list of all pages, and optionally another space and the URL to search the wiki.

This second URL will replace %s with the URL-encoded search term; if there is no %s in the URL, the URL-encoded search term will simply be appended.

The search URL should return the search result in RSS 3.0 format. See References.

Oddmuse will store the pagelist for every wiki on the NearMap in this directory. For every URL abbreviation X, the logo X.png in this directory will be used for “twin pages”. There is usually no reason to change this value.