User:Dnessett/Template/Bref/Installation Notes

Installation Notes

Installing the Bref Template

To install Bref on a MediaWiki installation, load the Bref subtree (the Bref Template, plus all subsidiary children pages) onto the appropriate grafting point in the target installation (e.g., you may wish to put it into the Template namespace, where it normally belongs. Alternatively, you can put it into user space, where it currently exists on Wikibooks).

The recommended way to install Bref is to obtain an XML file created by Special:Export on an installation with Bref already installed. To generate this file, access Special:Allpages on a Mediawiki installation with Bref installed. Get a list all of the Bref pages in the installation. This is quite simple. First, choose the namespace (e.g., User, if Bref is installed in a user namespace, such as User:Dnessett or Template, if Bref is installed in the Template namespace). List all of the pages in that namespace and copy the list. Paste the copied text into a new file (you can do this by creating a new file with a text editor and pasting the copied text into it). Remove any formating from the text by saving it as plaintext. The result should be a list of all of the pages in the namespace, one page per line. (The list must contain one pagename per line, since this is required by Special:Export.) The namespace identifier will not appear in each entry.

Delete all pagenames in the list that do not begin with the Bref pagename prefix for the existing installation. For example, if Bref is installed at User:Dnessett/Template/Bref, delete all pagenames that do not begin with Dnessett/Template/Bref. Now add the namespace identifier to each pagename. Simply globally replace the prefix with <namespace identifier>:<prefix>. For example, if the pagename prefix is Dnessett/Template/Bref and Bref is installed in the User namespace, globally replace Dnessett/Template/Bref with User:Dnessett/Template/Bref.

The resulting pagname list is now ready for use by Special:Export. Paste the list into the box immediately below the one labeled "Add pages from category". Make sure the checkboxes "Include only the current version, not the full history", and "Save as File" are checked. There is no need to check the "Include templates" check box. Finally, click the button labeled "Export". The file is saved to your system. If you have trouble with these exporting instructions, you can read the material at Help:Export.

The file created by Special:Export must be modifed to indicate the grafting point on the target installation. Open the XML file with a text editor (making sure it remains plain text) and globally replace the pagename prefix (the one including the namespace identifier) with the target installation grafting point. For example if the pagename prefix is User:Dnessett/Template/Bref and Bref will be grafted into the target installation at Template:Bref, globally replace User:Dnessett/Template/Bref with Template:Bref. Don't forget to include the namespace identifier in the grafting point prefix.

Once you have modified the XML file so it uses the grafting point prefix for the target installation, access Special:Import on the target installation, click the button labled "Choose File". and provide the name of the XML file. You can provide a comment if you wish. Then click the button "Upload file". The import may take a while (up to a few minutes). When it finishes, Import will report what happened. If it reports something like, "The action you have requested is limited to users in one of the groups: Administrator, Importers, Transwiki importers", you do not have import privileges on the target installation. You must contact an administrator, provide the XML file and ask that it be uploaded.

Once you have successfully installed Bref, you can discard the file containing the list of pagenames on the origin mediawiki installation and the XML file generated by Special:Export. Alternatively, you can retain the XML file for installing Bref on other mediawiki installations. (If you do this, don't forget to modify the grafting point prefix in the XML file to reflect the proper location on the new target installation).

After loading Bref onto its grafting point, resolve the following issues:

Each helper template calls Bref using substitution (i.e., using the "subst:" keyword). Do not change this. If you rewrite the helper templates to call Bref dynamically, template loop errors will occur for some Bref OP parameter values. Furthermore, the call by substitution is more efficient, since Bref is not going to change between helper template calls. If you do change the Bref template (e.g., to install a bug fix), you have to go back to each helper template and reinstall them using the steps described below.

There is a MediaWiki bug (18965) fixed in r50537. This bug affects the use of the Bref helper script (see the Bref document for details about this script). If your installation version precedes this version (to find your installation's version number, access the Special:Version page), then putting the importScript call into User:<username>/per_book/<bookname> will not work. Until the installation revision equals or exceeds r50537 (or until the bug is fixed locally) the only way to clean up the useless back links in citation data renders is to put the importScript call into the appropriate skin script (e.g., for Monobooks, monobook.js). This is inefficient, as described in the Bref document. So, it is preferable to get the bug fixed in the installation as soon as possible and move the importScript call to User:<username>/per_book/<bookname>. This bug should not affect the global per-book gadget (although, as of 5/29/2009 using the helper script with the global per-book gadget is untested).

There was a bug in the personal per-book gadget script MediaWiki:Gadget-Personalper.js that prevented the Bref helper script from working. This is now fixed. However, if your installation has an old copy of that script, it needs to be updated. Go to Wikibooks and reference the MediaWiki:Gadget-Personalper.js page (e.g., paste MediaWiki:Gadget-Personalper.js after /wiki/ in the URL showing in the browser and navigate to the page). Compare the script on that page with the page on your installation. If they are different, update (or get a sysop to update) the installation's page to the text on the Wikibooks page.

After loading the XML file into its grafting point on the new installation, the Bref template and the helper templates will have extraneous line breaks between their lines. This causes problems with their use. Consequently, after Importing the XML file, some cleanup is required, specifically that given in the next two bullets.

The line breaks between switch statement lines and any line breaks at the end of the Bref template code must be eliminated. This can be done manually. Alternatively, the following code can be copied and pasted into the Bref template page:

<includeonly>{{#switch: {{{OP}}}
| nop
| #default = <sup><font color="blueviolet">Bref_Place_Holder</font></sup>
| scl = <div style="display:none;">
| sbp = <div style="display:none;">{{ {{#if: {{{CLP|}}} | {{{CLP}}} | {{#titleparts: {{FULLPAGENAME}} | -1 }}/Citations_List}} }}</div>
| aclp = <div style="display:none;">{{ {{#if: {{{CLP|}}} | {{{CLP}}} | {{#titleparts: {{FULLPAGENAME}} | -1 }}/Citations_List}} }}</div>
| ecl = </div>
| ebp = <div style="display: none"><references /></div>
| rcd = {{#if: {{{GROUP|}}} | {{#tag:references || group={{{GROUP}}} }} | <references />}}
| cite = {{#if: {{{NAME|}}} | {{#tag:ref | {{#if: {{{TEXT|}}} | {{{TEXT}}} |}} | name= {{{NAME}}} | group={{#if: {{{GROUP|}}} | {{{GROUP|}}} | }} }}<br> | <span style="color:blueviolet">A citation must provide either a NAME or GROUP parameter</span>}}
| ref = {{#if: {{{NAME|}}} | {{#tag:ref | | name= {{{NAME}}} }} | <span style="color:blueviolet">A reference must provide a NAME parameter</span>}}
| note = {{#if: {{{GROUP|}}} | {{#tag:ref | | group= {{{GROUP}}} | name={{#if: {{{NAME|}}} | {{{NAME}}} | }} }} | <span style="color:blueviolet">A footnote must provide a GROUP parameter</span>}}
}}</includeonly>

Don't put the {{#switch keyword on the line below <includeonly> and don't put the </includeonly> on the line below the }} closing template braces. For some reason, (perhaps related to Mozilla bugs 1878, 12974 and 18994) doing so causes the template expansion code to add line breaks in inappropriate places, which breaks the Bref template calls.

The helper templates are themselves template calls. They must be reinstalled from the text shown below. For example, the Bref Add Citations List Page is located at Bref/Add Citations List Page, where Bref represents the Bref grafting prefix, e.g., Template:Bref. To clean it up edit the helper template page, delete all existing text on the page, copy the text given below (including the HTML comment) under the title Bref Add Citations List Page (obviously, don't copy the title), paste it into the helper template edit area and then save the page. Keeping the HTML comment on the helper template page allows it to be refreshed (in case the Bref template changes, e.g., for a bug fix) without referencing these installation notes. To do this, edit the helper template page, delete everything but the HTML comment, copy the text within the comment delimiters, paste it immediately after the comment (not on the next line) and save the page.

Bref Add Citations List Page

{{subst:User:Dnessett/Template/Bref |OP=aclp | CLP={{{CLP|}}} }}

Bref Citation Definition

<noinclude><div style="display: none"></noinclude>{{subst:User:Dnessett/Template/Bref | OP=cite | NAME={{{NAME|}}} | TEXT={{{TEXT|}}} | GROUP={{{GROUP|}}} }}<noinclude></div></noinclude>

Bref Citation Reference

{{subst:User:Dnessett/Template/Bref | OP=ref | NAME={{{NAME|}}} | GROUP={{{GROUP|}}} }}

Bref Footnote Reference

{{subst:User:Dnessett/Template/Bref | OP=note | NAME={{{NAME|}}} | GROUP={{{GROUP|}}} }}

Bref End Book Page

<noinclude><div style="display: none"></noinclude>{{subst:User:Dnessett/Template/Bref | OP=ebp }}<noinclude></div></noinclude>

Bref End Citation List

<noinclude><div style="display: none"></noinclude>{{subst:User:Dnessett/Template/Bref | OP=ecl}}<noinclude></div></noinclude>

Bref Place Holder

{{subst:User:Dnessett/Template/Bref | OP=nop }}

Bref Render Citation Data

<noinclude><div style="display: none"></noinclude>{{subst:User:Dnessett/Template/Bref | OP=rcd | GROUP= {{{GROUP|}}} }}<noinclude></div></noinclude>

Bref Start Book Page

<noinclude><div style="display: none"></noinclude>{{subst:User:Dnessett/Template/Bref | OP=sbp | CLP={{{CLP|}}} }}<noinclude></div></noinclude>

Bref Start Citation List

<noinclude><div style="display: none"></noinclude>{{subst:User:Dnessett/Template/Bref | OP=scl}}<noinclude></div></noinclude>

Installing the Bref Examples

Installing the Bref Examples follows the same general procedure as installing the Bref template. Load the Bref_Examples subtree onto the appropriate grafting point at the install site. When using Special:Export to accomplish this, the prefix User:Dnessett should be changed in the XML file to the grafting point prefix on install site.

Like other documents that use Bref, a clean representation of citation and footnote rendering sections requires the use of the Bref helper script. The recommended way to enable the helper script (see the Cleaning Up Meaningless Back Links (Bref Helper Script) section in the main Bref document) is through the use of the per book or personal per book gadgets. Due to the way per book and personal per book gadgets work, the grafting prefix must be either a user name (i.e., User:<some name>) or the main name space. So, the name of the Bref_Examples portal page will be either User:<some name>/Bref_Examples or simply Bref_Examples. All of the examples pages are prefixed by the portal page name (NB: prefixes may have subsidiary organization, e.g., the first markup page in chapter 1 of Example 2 is <portal page prefix>/Example2/Chapter1/Markup Page 1).