Version 7 (modified by 14 years ago) (diff) | ,
---|
Abbr and Acronym Macro
Notice: This plugin is unmaintained and available for adoption.
Description
AbbrMacro returns an <abbr> or <acronym> element with a title attribute.
If you've used InlineMacro to create abbreviations or acronyms in your formatted wiki pages, you probably quickly realized how tedious it can be. The AbbrMacro package is designed to alleviate this issue.
It accepts keyword syntax only:
[[Abbr(key=XYZ,title=Xenon Yeti Zulu,<tag=abbr|acronym>)]]
Where key
is the element content, title
is required, and the tag
keyword is optional. The element
type (tag) will default to acronym
if omitted. Why is acronym the default? For several reasons. First,
most users are after acronyms (and as far as I know there are no plans for an initialism
element). Second,
Internet Explorer before version 7.0 does not support the <abbr>
element. It won't do any harm to use them
with IE 6 and below, but these browsers do not allow you to style the element with CSS and they don't display
the title attribute as a tooltip.
Many HTML authors mistakenly refer to elements as "tags." For a review of the syntax and nomenclature of WWW markup elements, visit the Wikipedia Element article, or this quick synopsis will help.
Syntactically, HTML elements are constructed with:
- A
start tag
marking the beginning of an element. - Any number of valid
attributes
(and their associated values in quotes). - Some amount of
content
(characters and other elements). - An
end tag
.
Notes:
- In general, empty elements do not have an end tag nor do they contain content.
- HTML elements that include attributes do so in their start tags; they define additional properties and behavior.
- The end tag is required for most elements and optional for others.
- These rules vary depending on what DOCTYPE you are serving.
There has been a long and sometimes heated discussion on the <abbr>
and <acronym>
elements around the
Web. A good article at Juicy Studios was written by my friend Pamela Berman:
Abbreviations are a Breeze.
Dictionary File
AbbrMacro
is designed to be rolled out in phases. The first and simplest use case I've already described.
But even that can become tedious, especially if you use the same acronyms over and over. The second phase
introduces a user-defined plain text dictionary file of key=value (content=title) pairs, which permits the
omission of the title keyword. Assuming, that is, there is a matching abbreviation in the dictionary file.
You may also include the title attribute using the macro even if the element is defined in the dictionary
file, the macro title keyword will take precedence. If you omit the title and the element is not defined
in the dictionary, the macro will issue a error message and exit.
To configure the location of the dictionary file, add the following entry to your project trac.ini
:
[abbr] file = /path/to/your/abbreviations/file
The file must be readable (and eventually writable, see below) by your Web server in order for this feature to work.
The format of the dictionary file couldn't be simpler:
[acronym] PEP = Python Enhancement Proposal PHP = Hypertext Preprocesor RFC = Request For Comments ... [abbr] ...
Where leading and trailing whitespace are removed. Notice that there is a uncanny similarity between the dictionary file
and trac.ini? This is no accident of course, each one has sections followed by name=value pairs. Sections other than
[abbr]
and [acronym]
in the dictionary file are ignored, and there is no rule you must have both. I tend to only use
acronyms for this sort of thing, and to help get you started here is an example AbbrMap. Like all
Python/Trac files, strings beginning with a #
(pound) character are treated as comments and are ignored. If you're
going to use Unicode characters in your dictionary (typically in the title attribute), open the file, as always, with:
# -*- coding: utf-8 -*-
AbbrMapTxt
A third and final phase will allow the user to edit this file from within the wiki, similar to the InterMapTxt page for InterWiki links.
Installation
Download the zipfile, unzip the archive to a temporary
location, visit the 0.11
folder and run:
python setup.py bdist_egg cp dist/*.egg /trac/env/Project/plugins
Configuration
Enable the macro in:
/trac/env/Project/conf/trac.ini:
[components] abbr.* = enabled
See Dictionary File above if you plan on using this feature.
You may have to restart your Web server.
Style
No sense doing it without style, here's mine.
/* acronyms and abbrs */ abbr, acronym { border-bottom: none; cursor: default; color: #309; } abbr:hover, acronym:hover { border-bottom: 1px dotted #309; }
Example
Macro:
[[Abbr(key=PEP,title=Python Enhancement Proposal)]]
Displays:
PEPSource
- Browse the source at: GitHub.
- Public clone URL:
git clone git://github.com/dwclifton/tracabbrmacro.git
Bugs/Feature Requests
Existing bugs and feature requests for AbbrMacro are here.
If you have any issues, create a new ticket.
Recent Changes
- 15264 by rjollos on 2016-02-11 04:22:34
-
Remove unnecessary svn:mime-type on py files
svn:mime-type was set to "plain" for many files.
- 8490 by rjollos on 2010-08-28 04:55:44
-
Adding AbbrMacro from project's wiki page.
- 5097 by dwclifton on 2009-01-06 17:58:56
-
New hack AbbrMacro, created by dwclifton
(more)