* Writing Plugins Compatible with V5, 6 & 7

[tatewise]

KB article Writing Plugins Compatible with Versions 5, 6 & 7 needs better advice under 'Gedcom Data Format Changes'.

BTW: The KB links for Titles with '&' need the & (as illustrated above) converting to just &

1) It says the changes are due to changing from Gedcom 5.5 to 5.1.1 but only some are:-

• The structure for Media objects has tag FILE (was _FILE) and the level for FORM & TITL tags has changed
• Custom attributes now use FACT tag although the API still uses _ATTR
• Changes to the GEDCOM tags for EMAIL (was _EMAIL), and WWW (was _WEB)
• New GEDCOM tags FAX, FONE, ROMN, etc

2) Other changes are due to new FH V7 features:

• The structure for Media objects for _KEYS, _AREA, _CAPT, _NOTA, _SEQ instead of _ASID, etc
• Rich text in Note (NOTE2) and Text From Source (TEXT) fields that have new data type 'richtext' and tags _FMT, _LINK_? & _LNK plus many new API functions
• Research Notes with new tag _RNOT that support rich text formats
• Templated source citation meta-fields that require shortcuts and new tag _SRCT
• Updates to some Plugin Code Snippets

[ColeValleyGirl]

BTW: The KB links for Titles with '&' need the & (as illustrated above) converting to just &

Where are you seeing this? I can't see it anywhere.

Other than that, I've incorporated your changes.

[tatewise]

The & happens in Writing Plugins Compatible with Versions 5, 6 & 7 and every other article with & in Title.
Use the chain-link icon to obtain a KB shortcut as below and the & is always present.

Copied Writing Plugins Compatible with Versions 5, 6 & 7

Thank you for the KB updates. The rich text is most likely to catch out many authors.

[Mark1834]

Thanks for this. One comment I would make though is that it seems to have been written by an advanced user for the benefit of advanced users. In particular the statement that "This code block is needed near the beginning of any plugin written originally in Lua 5.1 to enable it to run in Lua 5.3 with the minimum of changes" (my emphasis) is not correct, and may be misleading for the beginner or elementary coder who has written relatively simple plugins in FH6 to do a specific job and now wishes to port them to FH7.

So far, I haven't had to make any changes to my simple plugins (which don't use IUP) to make them compatible with FH7, and even new plugins with some basic IUP need minimal attention to cross-version compatibility.

IMO the KB piece needs a bit more on what is common, rather than just the differences.

[ColeValleyGirl]

Mark,

The article is addressing writing plugins for multiples version of FH, and so is aimed at more advanced users (hence it is tagged Advanced and Intermediate).

A separate article on the relatively simpler topic of migrating plugins from Lua 5.1 to Lua 5.3 (without regards to backward compatibility) might be useful, if it didn't duplicate the information on the same subject in the FH7 Plugin Help file...

[Mark1834]

OK, but there are only 3 authors who write store plugins for wider distribution, and a much larger community reviewing their own plugins for FH7 compatibility (or maintaining both FH6 and FH7 on different systems, as I do) who could be misled by incorrect statements. I read it as being addressed at that community, as you three probably know it all already!

If you are saying this page is not for the general plugin author, it has the same skill level classification as the “Getting Started” page...

[ColeValleyGirl]

Mark, there are actually about a dozen authors of plugins in the store, not just three...

Point taken about Getting Started Writing Plugins -- I've modified the classification to Intermediate, although, looking at the wider user base, all the Plugin topics probably ought to be Advanced. I've said it before, but it bears repeating: the vast majority of users never customise anything, and wouldn't dream of writing a plugin.

My point is: that article isn't aimed at authors migrating plugins, but at authors maintaining plugins for multiple environments/users.

The title is a big clue, as is the Introduction:

The change from Lua 5.1 to 5.3 in ƒh7, from Gedcom 5.5 to Gedcom 5.5.1, the introduction of new features in ƒh7 and the updating of many of the Lua libraries available for writing plugins poses some challenges to plugin authors who wish to write plugins for use across ƒh versions 5, 6 and 7.

The advice in it will work for a simple migration, but goes beyond what a simple migration requires. The simple migration scenario is addressed by the FH7 help file.

[Mark1834]

Last time I looked, there were 3 active authors (i.e. submitted a new store plugin in past 5 years). You’ve rightly pointed out yourself that most authors only write plugins for their own use.

We can agree to disagree on the target audience, but my main point was the factual error I pointed out, which is still there. I assume that will be corrected in due course (otherwise, what’s the point of the KB?).

[ColeValleyGirl]

Mark. If you're writing a NEW plugin and want it to be compatible with lua 5.1 and lua 5.3 ie you're in the target audience for that article, it is sensible to drop in code to facilitate backward compatibility before you start writing. You may not know if you need that code or not but you have eliminated the need to think about it again. So in this article it isn't an error. (as an aside it might be easier to use the compat53 library but that wasn't available when the article was written and not every likes to use black box libraries.

If you're migrating an existing plugin, you may or may not need that code block. You can drop it in just in case or you may know that you don't need it. So in the article you want to have been written, the advice would be as per the fh plugin help. The compat53 library is irrelevant for migration.

I don't have time to write the article you think is needed - I'll add it to my to do list but I've more urgent things to do.

[ColeValleyGirl]

PS I will amend the intro to that code block to remove the reference to 'originally written in lua 51.' It's a hangover from the exchange of emails that fed into that article.

[Mark1834]

Thanks - that’s all I asked for - correction of the factual error that the code block is needed for all Lua 5.1 code to run in Lua 5.3.

However, I fundamentally disagree with your programming style, and regard that type of “just in case” code as bloatware that gets in the way of readability and comprehension. I’d rather think about whether I need it or not.

But that’s the strength of a community wiki like the KB. It shouldn’t be just one person’s view of how to do things, no matter how convinced they are that it is the “right” way.

[ColeValleyGirl]

1. I make it a rule not to comment on people's programming style or skills in public -- we all work differently and there's little to be gained from such a discussion. (I do hope Shosh's articles on Writing Plugins for Beginners will address some of the basic hygiene issues, and the importance of writing readable and reusable code). Of course I have opinions which I might express in private, but I try not to form those based on a webpage that synthesizes input from 3 different people... not all of whom agree with every piece of the result, other than the fact that the advice given is workable (not perfect).

2. An extra 23 lines in a plugin that might be many hundreds or thousand of lines long does not meet my definition of bloatware; if it enables the author to focus on the things they really need to think about, which can't be dealt with by dropping some boilerplate code in, or speeds up the process of updating or writing a backwards compatible plugin, it's justified. It also meets my preference for readable and reusable code -- I'm a big fan of boilerplate... (Can I suggest that if you're worried about 'bloatware that gets in the way of readability and comprehension' you try using an editor with code-folding. All the boilerplate, hidden with a click, and you can focus on the plugin logic, not the plumbing and wiring).

3. "I’d rather think about whether I need it or not." It should go without saying (especially in an article aimed at authors experienced with Lua and FH plugins) that experienced programmers will do the same, and cut down the boilerplate if they wish, or do without it completely.

4. In an article aimed at less experienced programmers migrating their code from FH6 to FH7 (with no need to maintain backwards compatibility) the emphasis might be different. I've reviewed (again) the section on Converting Lua 5.1 Plugins to Lua 5.3 within the Family Historian Plugin Help; anything the KB would add to what's there would be minimal. Private plugins are likely (not certain) to be shorter and less complex, and an author will have fewer of them to deal with; the author will also almost certainly have some prior programming skills. Let me know what you think should be in the Migrating a Plugin Guide that isn't in the FH Plugin Help, because I'm struggling.

5. I've made some edits to the article in question. In particular:

• I've included a signpost to a yet-to-be written article for one way migration advice (should we come up with anything to include). Also pointed people doing one way migrations to the relevant Help.
• Taught grandmother to suck eggs by indicating the offending code block is only necessary if relevant.
• Separated the advice for legacy (5/6) Plugins and plugins written for the first time in V7
• Added a piece on character encoding (sorry, more boilerplate) (hat tip Mike)

Let me know if you think anything else is needed.

[Mark1834]

Helen,

Thanks for the detailed response, and I’ll reply in kind...

I think the changes are worthwhile, thank you. Originally, I had issues as the title suggests that the article could be equally relevant to any user writing plugins for multiple versions. This includes upgraders, those temporarily running different versions in parallel (which is really just a subset of the first group), and finally the relatively small group of people who contribute plugins via the store.

As written, the implication was all plugin code would be affected (“this must”, “all plugins”, etc), and that is clearly not the case. Yes, virtually all big full-fat plugins of the type you, Mike and Jane write would be affected, but there is a larger community (of unknown and unknowable size) where the impact will range from major to none at all, depending on the complexity of their coding.

That’s why I picked you up on the offending statement that escaped the proofreads. It probably makes perfect sense to routinely include the code block in complicated plugins that need it, but not in simple ones that don’t. That wasn’t what the author intended, but it’s what was written down.

What’s “good” and “bad” style for coding is a topic all of its own. Certainly there is no shortage of long-standing FHUG users who are not shy about expressing views on what is good and bad practice in family history researching and recording...

Some of it may arise from the unanswered question of how store plugins should be created. Should they be coded to be as elegant and efficient as possible, even if that means they may be rather opaque? Or should they be written to be as accessible as possible, so beginners can usefully crib and learn from them, and others can run with them in the future to develop and adapt? I suspect the tendency is more the former, given the admission that even among the 3 very experienced active store authors you can’t always follow each other’s logic at times. My training and work experience strongly drives me to the latter, where scripts would be frequently handed over to other people to maintain and develop over a period of many years.

Hopefully, if Shosh’s school comes to pass, that will fill a training gap.

For this KB, I don’t think we need to do much more. I would probably expand the introduction a little, along the lines of “many users will need to write plugins that work in multiple versions of FH. Depending on the complexity of the plugin, the impact will range from nonexistent to extensive. Basic guidance for upgrading or converting is provided in FH plugin help, but this article provides a more comprehensive overview and is aimed mainly at the authors of store plugins...”

[ColeValleyGirl]

Helen,
Some of it may arise from the unanswered question of how store plugins should be created. Should they be coded to be as elegant and efficient as possible, even if that means they may be rather opaque? Or should they be written to be as accessible as possible, so beginners can usefully crib and learn from them, and others can run with them in the future to develop and adapt? I suspect the tendency is more the former, given the admission that even among the 3 very experienced active store authors you can’t always follow each other’s logic at times. My training and work experience strongly drives me to the latter, where scripts would be frequently handed over to other people to maintain and develop over a period of many years.

My problem with other people's plugins is that frequently my brain doesn't work the way theirs do, and I end up squinting sideways at some perfectly well structured code and going 'where are the useful comments?' and 'why on earth has X done it that way?'

My preference is for accessible code, especially as we're writing open-source material. Performance/memory is rarely a problem these days, thank goodness (I remember the days when people wrote Assembler that overwrote itself as it ran to deal with memory limitations).

One of the benefits I see of plugins over something like AS is that the code is open-source, and if an author decides or is forced to give up maintaining a plugin, somebody else can step in and take over. Or indeed, they can fork the code and create an alternative version even if the original author is maintaining the original. (No offense to Nick, but if he ceases to support AS, I doubt anyone else could step in).

[Valkrider]

The & happens in Writing Plugins Compatible with Versions 5, 6 & 7 and every other article with & in Title.
Use the chain-link icon to obtain a KB shortcut as below and the & is always present.

Copied Writing Plugins Compatible with Versions 5, 6 & 7

@Mike I have fixed this issue, please check to confirm.

[tatewise]

Thank you Colin, they are all fixed.