Changes between Version 1 and Version 2 of AbbrMacro


Ignore:
Timestamp:
Jan 6, 2009 7:15:55 PM (6 years ago)
Author:
dwclifton
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AbbrMacro

    v1 v2  
    33== Description == 
    44 
    5 AbbrMacro returns an <abbr> or <acronym> element with a title attribute. 
     5AbbrMacro returns an <abbr> or <acronym> element with a title attribute. 
     6 
     7If you've used InlineMacro to create abbreviations or acronyms in your [WikiFormatting formatted] wiki 
     8pages, you probably quickly realized how tedious it can be. The !AbbrMacro package is designed to 
     9alleviate this issue. 
     10 
     11It accepts keyword syntax only: 
     12 
     13{{{ 
     14[[Abbr(key=XYZ,title=Xenon Yeti Zulu,<tag=abbr|acronym>)]] 
     15}}} 
     16 
     17Where `key` is the element content, `title` is required, and the `tag` keyword is optional. The element 
     18type (tag) will default to `acronym` if omitted. Why is acronym the default? For several reasons. First, 
     19most users are after acronyms (and as far as I know there are no plans for an `initialism` element). Second, 
     20Internet Explorer before version 7.0 does not support the `<abbr>` element. It won't do any harm to use them 
     21with IE 6 and below, but these browsers do not allow you to style the element with CSS and they don't display 
     22the title attribute as a tooltip. 
     23 
     24Many HTML authors mistakenly refer to elements as "tags." For a review of the syntax and nomenclature of WWW 
     25markup elements, visit the Wikipedia [http://en.wikipedia.org/wiki/HTML_element Element] article, or this 
     26quick synopsis will help. 
     27 
     28Syntactically, HTML elements are constructed with: 
     29 
     30 * A `start tag` marking the beginning of an element. 
     31 * Any number of valid `attributes` (and their associated values in quotes). 
     32 * Some amount of `content` (characters and other elements). 
     33 * An `end tag`. 
     34 
     35'''Notes''': 
     36 
     37 * In general, empty elements do not have an end tag nor do they contain content. 
     38 * HTML elements that include attributes do so in their start tags; they define additional properties and behavior. 
     39 * The end tag is required for most elements and optional for others. 
     40 * These rules vary depending on what [http://www.w3.org/QA/Tips/Doctype DOCTYPE] you are serving. 
     41 
     42There has been a long and sometimes heated discussion on the `<abbr>` and `<acronym>` elements around the 
     43Web. A good article at Juicy Studios was written by my friend Pamela Berman: 
     44[http://juicystudio.com/article/abbreviations-acronyms.php Abbreviations are a Breeze]. 
     45 
     46== Dictionary File == 
     47 
     48`AbbrMacro` is designed to be rolled out in phases. The first and simplest use case I've already described. 
     49But even that can become tedious, especially if you use the same acronyms over and over. The second phase 
     50introduces a user-defined plain text dictionary file of key=value (content=title) pairs, which permits the 
     51omission of the title keyword. Assuming, that is, there is a matching abbreviation in the dictionary file. 
     52You may also include the title attribute using the macro even if the element is defined in the dictionary 
     53file, the macro title keyword will take precedence. If you omit the title and the element is ''not'' defined 
     54in the dictionary, the macro will issue a error message and exit. 
     55 
     56To configure the location of the dictionary file, add the following  entry to your project `trac.ini`: 
     57 
     58{{{ 
     59[abbr] 
     60file = /path/to/your/abbreviations/file 
     61}}} 
     62 
     63The file must be readable (and eventually writable, see below) by your Web server in order for this feature 
     64to work. 
     65 
     66The format of the dictionary file couldn't be simpler: 
     67 
     68{{{ 
     69[acronym] 
     70PEP = Python Enhancement Proposal 
     71PHP = Hypertext Preprocesor 
     72RFC = Request For Comments 
     73... 
     74 
     75[abbr] 
     76... 
     77}}} 
     78 
     79Where leading and trailing whitespace are removed. Notice that there is a uncanny similarity between the dictionary file 
     80and trac.ini? This is no accident of course, each one has sections followed by name=value pairs. Sections other than 
     81`[abbr]` and `[acronym]` in the dictionary file are ignored, and there is no rule you must have both. I tend to only use 
     82acronyms for this sort of thing, and to help get you started here is an example [AbbrMacro/AbbrMap AbbrMap]. Like all 
     83Python/Trac files, strings beginning with a `#` (pound) character are treated as comments and are ignored. If you're 
     84going to use Unicode characters in your dictionary (typically in the title attribute), open the file, as always, with: 
     85 
     86{{{ 
     87# -*- coding: utf-8 -*- 
     88 
     89 
     90 
     91}}} 
     92 
     93{{{ 
     94#!html 
     95<div class="system-message"> 
     96<strong>Warning</strong>: Since abbreviations and acronyms kept in the dictionary file are stored in memory as unique 
     97key=value pairs, duplicates keys will cause a collision. If this happens, one will overwrite the other. However, since 
     98the keys are case-sensitive, in practice this should not be a issue&mdash;just something to keep in mind when you are 
     99editing your dictionary file. 
     100</div> 
     101}}} 
     102 
     103== !AbbrMapTxt == 
     104 
     105A third and final phase will allow the user to edit this file from within the wiki, similar to the InterMapTxt page 
     106for InterWiki links. 
     107 
     108== Installation == 
     109 
     110Download the [/raw-attachment/wiki/AbbrMacro/abbrmacro.zip zipfile], unzip the archive to a temporary 
     111location, visit the `0.11` folder and run: 
     112 
     113{{{ 
     114python setup.py bdist_egg 
     115cp dist/*.egg /trac/env/Project/plugins 
     116}}} 
     117 
     118== Configuration == 
     119 
     120Enable the macro in: 
     121 
     122/trac/env/Project/conf/trac.ini: 
     123 
     124{{{ 
     125[components] 
     126abbr.* = enabled 
     127}}} 
     128 
     129See [#DictionaryFile Dictionary File] above if you plan on using this feature. 
     130 
     131You may have to restart your Web server. 
     132 
     133== Style == 
     134 
     135No sense doing it without style, here's mine. 
     136 
     137{{{ 
     138#!css 
     139/* acronyms and abbrs */ 
     140 
     141abbr, 
     142acronym { 
     143  border-bottom: none; 
     144  cursor: default; 
     145  color: #309; 
     146} 
     147abbr:hover, 
     148acronym:hover { 
     149  border-bottom: 1px dotted #309; 
     150} 
     151}}} 
     152 
     153== Example == 
     154 
     155'''Macro''': 
     156{{{ 
     157[[Abbr(key=PEP,title=Python Enhancement Proposal)]] 
     158}}} 
     159 
     160'''Displays''': 
     161{{{ 
     162#!html 
     163<acronym title="Python Enhancement Proposal">PEP</acronym> 
     164}}} 
    6165 
    7166== Bugs/Feature Requests ==  
     
    10169[report:9?COMPONENT=AbbrMacro here]. 
    11170 
    12 If you have any issues, create a  
    13 [http://trac-hacks.org/newticket?component=AbbrMacro&owner=dwclifton new ticket]. 
    14  
    15 == Download == 
    16  
    17 Download the zipped source from [download:abbrmacro here]. 
     171If you have any issues, create a [http://trac-hacks.org/newticket?component=AbbrMacro&owner=dwclifton new ticket]. 
    18172 
    19173== Source == 
    20174 
    21 You can check out AbbrMacro from [http://trac-hacks.org/svn/abbrmacro here] using Subversion, or [source:abbrmacro browse the source] with Trac. 
    22  
    23 == Example == 
    24  
    25 [[Abbr(key=PEP,title=Python Enhancement Proposal)]] 
     175 * Browse the source at: [http://github.com/dwclifton/tracabbrmacro/tree/master GitHub]. 
     176 * Public clone URL: 
     177{{{ 
     178git clone git://github.com/dwclifton/tracabbrmacro.git 
     179}}} 
    26180 
    27181== Recent Changes == 
     
    31185== Author/Contributors == 
    32186 
    33 '''Author:''' [wiki:dwclifton] [[BR]] 
    34 '''Contributors:''' 
     187 * '''Author:''' [wiki:dwclifton] 
     188 * '''Contributors:''' The Trac and Python development community.