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