Changes between Version 1 and Version 2 of AbbrMacro

Timestamp:

Jan 6, 2009, 6:15:55 PM (15 years ago)

Author:

Douglas Clifton

Comment:

--

AbbrMacro

@@ -3 +3 @@
 == Description ==
 
-AbbrMacro returns an <abbr> or <acronym> element with a title attribute.
+AbbrMacro returns an <abbr> or <acronym> element with a title attribute.
+
+If you've used InlineMacro to create abbreviations or acronyms in your [WikiFormatting 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 [http://en.wikipedia.org/wiki/HTML_element 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 [http://www.w3.org/QA/Tips/Doctype 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:
+[http://juicystudio.com/article/abbreviations-acronyms.php 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 [AbbrMacro/AbbrMap 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 -*-
+
+
+
+}}}
+
+{{{
+#!html
+<div class="system-message">
+<strong>Warning</strong>: Since abbreviations and acronyms kept in the dictionary file are stored in memory as unique
+key=value pairs, duplicates keys will cause a collision. If this happens, one will overwrite the other. However, since
+the keys are case-sensitive, in practice this should not be a issue&mdash;just something to keep in mind when you are
+editing your dictionary file.
+</div>
+}}}
+
+== !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 [/raw-attachment/wiki/AbbrMacro/abbrmacro.zip 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 [#DictionaryFile 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.
+
+{{{
+#!css
+/* 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''':
+{{{
+#!html
+<acronym title="Python Enhancement Proposal">PEP</acronym>
+}}}
 
 == Bugs/Feature Requests == 
@@ -10 +169 @@
 [report:9?COMPONENT=AbbrMacro here].
 
-If you have any issues, create a 
-[http://trac-hacks.org/newticket?component=AbbrMacro&owner=dwclifton new ticket].
-
-== Download ==
-
-Download the zipped source from [download:abbrmacro here].
+If you have any issues, create a [http://trac-hacks.org/newticket?component=AbbrMacro&owner=dwclifton new ticket].
 
 == Source ==
 
-You can check out AbbrMacro from [http://trac-hacks.org/svn/abbrmacro here] using Subversion, or [source:abbrmacro browse the source] with Trac.
-
-== Example ==
-
-[[Abbr(key=PEP,title=Python Enhancement Proposal)]]
+ * Browse the source at: [http://github.com/dwclifton/tracabbrmacro/tree/master GitHub].
+ * Public clone URL:
+{{{
+git clone git://github.com/dwclifton/tracabbrmacro.git
+}}}
 
 == Recent Changes ==
@@ -31 +185 @@
 == Author/Contributors ==
 
-'''Author:''' [wiki:dwclifton] [[BR]]
-'''Contributors:'''
+ * '''Author:''' [wiki:dwclifton]
+ * '''Contributors:''' The Trac and Python development community.