=== Side Matter ===
Contributors: setzer
Tags: academic, annotation, annotations, bibliography, bibliographic, citation, citations, cite, commentary, endnote, endnotes, footnote, footnotes, margin, matter, note, notes, ref, reference, references, scholar, scholarship, shortcode, side, sidebar, sidenote, sidenotes, widget
Requires at least: 3.0
Tested up to: 3.5.2
Stable tag: 1.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Turns your footnotes into sidenotes, magically positioning each note in the sidebar next to its corresponding reference in the text.

== Description ==

Side Matter turns your footnotes into sidenotes, magically aligning each note in the sidebar next to its corresponding reference in the text. Easily incorporate citations, digressions, and editorial remarks into the sidebar of a page or post with a simple-to-use shortcode and widget. Scholars, editors, and writers of all kinds will find particular benefit in the plugin.

Sidenotes have a centuries-long history of use in printed texts, from the Geneva Bible to the works of Edward Tufte. They function equally well on the Web: unlike hyperlinked footnotes, sidenotes don't require the user to click away from a page's main content to follow up on a reference. Instead, they perch humbly and accessibly alongside the lines to which they refer.

Side Matter includes an options menu for toggling settings, as well as a set of built-in classes for [styling sidenotes and references with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/). The plugin works well with many popular base themes, including Twenty Twelve, Twenty Ten, Responsive, and Toolbox.

To use, place the Side Matter widget in your sidebar, then enclose sidenote text in a page or post using the `[ref]` shortcode, like so:

> Here's the text to annotate.`[ref]`Note text goes here.`[/ref]`

== Installation ==

1. Upload the directory `side-matter` to `wp-content/plugins`.
2. Activate Side Matter using the Plugins menu.
3. Using the Widgets menu, place the Side Matter widget in your sidebar.
4. You may now use the `[ref]` shortcode to generate sidenotes in posts and pages, like so:

> Here's the text to annotate.`[ref]`Note text goes here.`[/ref]`

To modify the plugin's default settings, use the options menu located on your Reading Settings screen.

If you'd like to customize the appearance of Side Matter notes and references using CSS, consult [Styling Side Matter with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/).

== Frequently Asked Questions ==

= Where is Side Matter's options menu? =

You can find the options menu on your Reading Settings screen.

= Does Side Matter work with responsive layouts? =

Yes. The plugin includes an option, turned off by default, to responsively re-position sidenotes upon window resize or zoom. Enable this function using the Responsive Positioning control in Side Matter's options menu.

= My notes just sit at the top of the sidebar. =

Your theme may not be linking `side-matter.js`, the script that aligns sidenotes. Check the page source to see if `side-matter.js` has been linked.

= My notes appear at a regular vertical offset from their proper position. =

Some themes idiosyncratically display notes at an offset from their corresponding references in the text. As a workaround for this problem, Side Matter's options menu includes a field for arbitrarily adjusting your notes' vertical offset.

= Why doesn't the plugin work with some themes? =

Not all themes are built to neatly absorb a layout addition like Side Matter. The plugin works well with most base themes that incorporate a conventional sidebar, but it isn't guaranteed to display notes perfectly within all themes. Tinkering with note offset or CSS will fix most problems; in other cases, it's best to consult the theme author.

= Can sidenotes be displayed without using the widget? =

Yes. Use the custom action `side_matter_list_notes` in your sidebar template, as seen below:

    <?php
    do_action( 'side_matter_list_notes' );
    ?>

= Some numeral formats don't display properly in my browser. =

Browser support for the CSS `armenian`, `georgian`, `hebrew`, and `lower-greek` list styles varies. (See [Web Platform Docs](http://docs.webplatform.org/wiki/css/properties/list-style-type) for compatibility specifics.) Decimal, Latin, and Roman numerals enjoy wide support and can serve as reliable fallbacks.

== Screenshots ==

1. Side Matter captures footnote text using the [ref] shortcode, then magically positions each footnote alongside its corresponding reference in the text.

2. Modify default settings using Side Matter's options menu on the Reading Settings screen.

== Changelog ==

= 1.0 =
* Added support for Armenian, Georgian, Greek, and Hebrew numeral formats, as well as the option to hide numeral figures entirely.
* Fixed two IE-specific bugs related to proper display of `title` attributes and list numerals.
* Made various minor adjustments and fixes for appearance and performance.
* Numbered classes have been removed.
* Plugin is now localization-ready.

= 0.9 =
* Added a preview field to the options menu.
* Added an option to display reference figures in Latin alphabet and Roman numeral formats.
* Added an option to set inline colors for Side Matter elements.
* Reference numeral `a` tags have been given a `title` attribute for accessibility.
* Removed deprecated element classes `side-matter-ol` and `side-matter-li`. Numbered classes, e.g. `side-matter-sup-6`, are now deprecated.
* Responsive positioning and fade effects are now turned off by default to spare inexperienced users the script load.
* Side Matter's options menu is now linked from its entry on the Installed Plugins screen.

= 0.8 =
* Added an option to display sidenotes on selected page types.
* Plugin documentation now includes a guide to [styling Side Matter elements with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/).
* Reduced specificity for CSS defaults in `side-matter.css`, allowing them to be more easily superseded by user CSS.
* Removed the `a` anchor elements within sidenotes to correct a stubborn layout issue. Reference numerals now link to sidenotes via `li id`.
* Side Matter now erases its options field from the database upon deletion.
* Widget admin panel now links to plugin options menu on the Reading Settings screen.

= 0.7 =
* Added an options menu to the Reading Settings screen.
* Made various tweaks for security, performance, and cross-browser compatibility.
* Paragraphs within sidenotes are now properly wrapped in `p` tags by WordPress.
* Replaced sidenote `span` tags with `div` tags to correct a display problem in some browsers.
* Sidenotes now employ jQuery fade effects for smoother transitions upon window load, resize, and zoom.

= 0.6 =
* Expanded plugin documentation.
* Rewrote `side-matter.php`, simplifying and consolidating code for future development.
* Sidenote numerals can now be styled separately from sidenote text.
* Streamlined CSS classes and jQuery selectors.
* Widget markup now better follows WordPress convention.

= 0.5 =
* Fixed a class instantiation error that was preventing plugin activation for some users.

= 0.4 =
* Initial release.

== Upgrade Notice ==

= 1.0 =
This update fixes a few IE-specific bugs and adds several features, including new numeral formats and localization support.

= 0.9 =
This update adds a number of features, including alternate numeral formats and a color picker for Side Matter elements. Users who have modified `side-matter.css` are advised to make a backup copy before updating.

= 0.8 =
This update includes several fixes and additions, including the option to select which page types display sidenotes. Users who have modified `side-matter.css` are advised to make a backup copy before updating.

= 0.7 =
This update adds several features, including an options menu and transition-smoothing effects. Users who have modified their copy of `side-matter.css` are advised to make a backup copy before updating.

= 0.6 =
This update includes a number of tweaks and fixes, including improved classes for CSS and separate styling for sidenote numerals. Users who have customized their copy of `side-matter.css` are advised to make a backup copy before downloading.

= 0.5 =
This update fixes an error that was preventing plugin activation for some users. Recommended.

== Styling Side Matter with CSS ==

Side Matter's options menu allows you to render notes and figures in custom colors by way of the Iris color picker. Changing other aspects of Side Matter elements' appearance, such as typeface, indentation, or spacing, requires some tinkering with Cascading Style Sheets (CSS). This guide assumes some familiarity with CSS; if you're a beginner, start with a [tutorial](http://www.htmldog.com/guides/css/beginner/).

 The simplest way to add custom styles to your site is to employ a plugin that houses your custom CSS in the WordPress database, thus preserving it even if Side Matter (or your theme) is updated. [Jetpack Custom CSS](http://wordpress.org/extend/plugins/jetpack/) is a good example.

(Note that inline color styles set in the Side Matter options menu will generally override any custom styles you set elsewhere. If you're planning to use a custom stylesheet as described here, be sure to disable custom colors in the options menu.)

Side Matter comes with a set of built-in classes that make it easy to customize the appearance of sidenote and reference elements using [class selectors](http://www.htmldog.com/guides/css/intermediate/classid/). For example, all Side Matter elements can be styled at once using the class `side-matter`. The following rule will render all Side Matter content (reference numerals, sidenote numerals, and sidenote text) in blue 12-pixel serif type:

    .side-matter {
        color: blue;
        font-family: serif;
        font-size: 12px;
    }

Notes and references may be styled with greater precision using element-specific class selectors. The following rules will render reference and list numerals in red while leaving sidenote text black (see [Screenshots](http://wordpress.org/extend/plugins/side-matter/screenshots/) for a similar example):

    a.side-matter-ref, ol.side-matter-list {
        color: red;
    }
    
    div.side-matter-text {
        color: black;
    }

In some cases, your custom CSS may fail to take effect because the theme CSS carries greater [specificity](http://www.htmldog.com/guides/css/intermediate/specificity/). There are ways around this. For example, if you can't modify the color of superscript reference links because your theme's rules have greater specificity, try overriding the theme stylesheet's specificity with nesting or an ID selector:

    .entry-content > p > a.side-matter.side-matter-ref {
        color: red;
    }

    a[id^='ref-'].side-matter-ref {
        color: red;
    }

The `!important` declaration should be used only in rare cases, but may resolve a stubborn CSS conflict where other efforts have failed:

    a.side-matter-ref {
        color: red !important;
    }

= List of Class Selectors =
Here is a complete list of Side Matter element class selectors and their uses:

* `a.side-matter-ref` selects the `a` link tags that enclose in-text reference numerals. Use this class to modify the links' colors, underline, etc. Target a specific reference link using its ID selector (e.g. `#ref-5`).
* `sup.side-matter-sup` selects the `sup` (superscript) tags that enclose in-text reference numerals. Use this class to modify the numerals' typographic properties, such as size, offset, and font.
* `div.side-matter-widget` selects the `div` element that encloses the Side Matter widget.
* `ol.side-matter-list` selects the `ol` (ordered list) element that encloses notes in the sidebar, including note numeral figures.
* `li.side-matter-note` selects individual sidenote `li` (list item) elements. Target a specific note using the note's ID selector (e.g. `#note-6`).
* `div.side-matter-text` selects the `div` elements that enclose sidenote text, but not sidenote list numerals. Use this to style sidenote text separately from sidenote numerals.
* WordPress further wraps each note paragraph in a `p` tag. Because they are generated outside Side Matter, these `p` elements cannot be selected directly using the `side-matter` class. Instead, target them indirectly with a [child selector](http://www.htmldog.com/guides/css/advanced/selectors/), e.g. `div.side-matter-text > p`.

= Default CSS =
Side Matter sets a few default rules in the included stylesheet `css/side-matter.css`. Their low-specificity selectors allow these rules to be easily superseded by your theme stylesheet or custom CSS.

The first rule removes underlines from reference numeral links:

    a.side-matter-ref:link,
    a.side-matter-ref:visited,
    a.side-matter-ref:hover,
    a.side-matter-ref:active {
        text-decoration: none;
    }

The second rule specifies a consistent cross-theme appearance for superscript figures:
    
    sup.side-matter-sup {
        position: relative;
        top: -0.5em;
        vertical-align: baseline;
        font-size: 0.75em;
        line-height: 0;
    }