A partial archive of meta.discourse.org as of Tuesday July 18, 2017.

# Abbreviations and acronyms plugin

BlackSheep

I participate in a community where there are enthusiasts with lots of knowledge and newbies with not that much knowledge. It has become a habit that experts use lots of acronyms and abbreviations to refer to common terms, or famous webpages or to name known brands in their field of expertise, sometimes they use only initials when referring to famous people in the field, etc. This is not a problem for the oldest participants in the community, but some new people are having a hard time reading some posts, so the admins have been asked to create a plugin that automatically creates a tooltip for the most common acronyms.

This plugin does so. It automatically surrounds some (configurable) words with an <abbr>...</abbr> tag so a tooltip appears when hovering the mouse over the word.

This way IMMO becomes IMMO, YMMV becomes YMMV, R&B becomes R&B, etc

It is a very simple plugin, you can add more abbreviations through the admin panel.

Here is the code:

Any advice to improve the plugin will be welcome

downey

I installed this and added a couple acronyms. I wrote a test post that had several of the listed acronyms. In the editor preview, all 3 showed up with tooltips, but in the final post itself, only the last acronym of 3 showed up with the tooltip.

BlackSheep

That is weird, it is working for me.
All of the 3 acronyms have the same tooltip? or the first 2 have no tooltip at all?

i am sure this is not the problem, but did you add the new acronyms through the admin panel, or editing the settings.yml file?

downey

First two have nothing at all ...

BlackSheep

OK, I understand what is going on. The server side only reads the new settings on its startup, not dynamically. If you restart discourse it will work (please confirm).

I am going to investigate a new way to load the settings so it is more dynamic. Thanks for telling me, I reboot my development server all the time, and in the production server we probably never changed our initial list of acronyms so I never noticed.

tgxworld

@BlackSheep I submitted a PR to use a dialect preprocessor instead such that it calls a preprocessing function which will pull in the latest site settings each time it has to process a post.

BlackSheep

That is awesome @tgxworld. Thanks a lot! With your changes the plugin picks the new settings on the run, so you don't need to restart the application if you want to apply new abbreviations.

I am going to mention @downey to be sure he reads this.

psbrandt

Thanks for the great plugin @BlackSheep!

I'm seeing an issue where if an abbreviation/acronym is in a URL, the plugin (I think) inhibits the ability to make a link to that URL. So, if we had IMMO configured, then the following would be rendered as markdown source instead of as a link:

[link](http://www.domain.com/immo?maybe=something-else)
BlackSheep

Maybe i should force to detect a whitespace character (space, tab, new line, etc) on either side of the acronym before i do the substitution. What do you think?

Mittineague

Yes, currently the regex is looking for a word boundary after the token as a match.

slashes, question marks. etc. are word boundaries.

Testing for pre and post whitespace will work for the link use case.

But it will break if the acronym is written in parenthesis eg. (YMMV) would fail to match.
(I can't say how often that might be the case, but you just know someone will bring it up)

BlackSheep

Good point. But I don't want the plugin to break the link use case (or any other already existing syntax). Also since discourse has a preview as you type, that would make it very intuitive to see that you need to add the space, so any user could see that has to write ( YMMV) instead of (YMMV) to make it work. It is the same (although not for the same reasons) with the existing emojis:
this doesn't work:slight_smile:
this works

It is a matter of making it clear in the documentation. I think is the way to go

marcospreviato

I was looking for something like this, like a tooltip:

BlackSheep

OK, I changed it, so a whitespace character (space, tab, new line, etc) is needed before or after the acronym. Thanks for noticing

psbrandt

@BlackSheep thanks for the quick response!

meglio

Can the plugin be installed without touching settings.yml file as by your README at github? Also, if no plugin restart is required anymore after adding more acronyms, you should update the README file, it currently says:

You can keep adding more acronyms through the admin panel later on, but restarting Discourse is still required.

BlackSheep

Done! Thank you.

And yes, you don't really need to touch settings.yml at all. Although it comes with 3 acronyms as example so you probably want to change them in the admin panel after the installation

meglio

So, this is now entirely configurable in administration panel, is it?

BlackSheep

Yes, it is a very simple plugin. You can only enable / disable it, and add / delete new acronyms. Both things can be done though the admin panel.

meglio

Are the acronyms added on the fly, or require rebuilding the HTML of the posts? Will the acronyms go away as soon as we turn the plugin off?

BlackSheep

Messages posted (cooked) while the plugin is active will keep the acronyms. If you want older posts to have the acronyms you will need to rebuild them. If you want the acronyms to go away when you turn the plugin off you will need to rebuild older messages.