Family Historian User Group

I had thought of posting this in Maintaining the KnowledgeBase but decided it needed some discussion.
It is related to fhSQL library not compatible with ANSI encoding (20060) and Plugin Warning - Unicode Ahead! (17926) and similar discussions.

Knowledge Base Code Snippets

Some FH v7 fhUtils, fhFileUtils and Plugin API functions make several of the KB Code Snippets redundant, unless coding for FH v5 or FH v6. Also, most KB Code Snippets for File and Folder Management use lfs that does not support Unicode file-paths.

So should those redundant KB Code Snippets simply be deleted?

Alternatively, many could be replaced by functions from fhUtils and fhFileUtils that use File System Objects instead of lfs, but apart from me who will use them?

Another option is to publish fhUtils and fhFileUtils in a form compatible with FH v5 and FH v6.
I have experimented with that and it only needs trivial changes to produce working modules that could be added to the KB Code Snippets &/or included in the Install Library Modules plugin.

Directory Tree Code Snippet

There is nothing in any of the library modules that provide this Directory Tree functionality.
This Code Snippet uses lfs so does not support Unicode file-paths, but I've written a variant using File System Objects to support Unicode paths because I need it.
The attribute table returned is different but mostly better than the lfs version and easily adapted for most purposes.

The biggest change is the file Date-Time stamps are strings such as dd/mm/yyyy hh:mm:ss instead of an integer number of seconds since 1 Jan 1970 that is used by lfs and Lua os.time(), etc.
It is easy to convert the strings to integer form except for a Daylight Saving Time (BST) snag that can give a 1-hour discrepancy.
That Date-Time string to integer conversion can be added as Code Snippet.

Should I simply replace the existing Directory Tree Code Snippet with my new code or keep both versions?

Load/Save Text File

fhFileUtils functions fileGetContents & filePutContents do not support Unicode file-paths and readTextFile has limitations.
The FH v7 API has new fhLoadTextFile and fhSaveTextFile functions that have none of the above issues.
However, fileGetContents does load binary files as well as text files.
Should the FH v7 API functions be mentioned somewhere in the fhFleUtils description?

Mike, I will take this into account in the work I will be doing in the New Year about encoding and/or file access (including addressing some of the issues you have already reported with fhFileUtils). Please don't submit any changes to the KB before then, as you'll be aiming at a moving target.

However, one basic question is: do we expect any new plugins to be written for FH5/6? I think it very unlikely. You have a backwards compatibility problem that most of us don't suffer from, so may continue to need the relevant snippets (or an updated version) but most new developers will not.

I understand the fhXXX libraries will not be made available via loadrequire for FH5/6. They're also not exactly snippets, but if developers are only aiming at FH7, they're not needed in the KB anyway.

Re the directory tree function, fhFileUtils (getFolderContents) provides similar functionality -- does it not offer everything you need?

"Do we expect any new plugins to be written for FH5/6?"
How long is a piece of string?
Any FH5/6 users may wish to write plugins for their own use and may need to use Unicode file-paths.
The current Code Snippets won't help them much but if the fhFileUtils script was available it would help.
Even a reference to the github source would be useful.
I'm not talking about loadrequire, just visibility of the script, which as I said only needs some tiny changes to work as a download to the Plugins folder that would support require("fhFileUtils") and the KB documentation would apply.
Deleting the obsolete Code Snippets and adding the fhFileUitils.lua file would be a simple exercise for me.

Alternatively, if the Code Snippets are only meant to help FH v7 developers then many snippets can now be deleted.

getFolderContents is quite different from the directory tree function, which yields one file at a time in an iteration loop.
If a tree structure needs to be searched, then getFolderContents with subfolder recursion returns a very large table of tables, which must be iteratively searched. If the target of the search is found early on then the process is inefficient.
For me, that also means rewriting and retesting existing plugins, whereas my FSO directory tree variant is a direct replacement in most cases.

My thoughts…

I regard FH5 as obsolete. I don’t think I’ve ever seen that version on a profile, and the idea that there is a population of FH5 users who haven’t upgraded for many years suddenly wanting to learn how to write plugins is fanciful in the extreme.

As a relatively new author, I don’t go out of my way to break FH6 compatibility, but neither do I make things more complex by supporting it. Judging by profiles again, FH7 probably has about 80% uptake now, so FH6 is a dwindling population.

I’ve said it before, but it’s worth repeating. FH has relatively infrequent major upgrades, and is not expensive. Say £10-20 per year for FH, versus £100-150 pa for a major subscription website, £200-600 pa for broadband, £100-200 pa for your PC, etc. Existing plugins don’t stop working because there is a new FH version available. All of that says to me that a year after launch, the firm focus should be FH7, FH6 is “best endeavours”, and FH5 is dead.

It will be interesting to see how many contributions there will be in this thread. My gut feeling is that it will be the handful of usual suspects discussing among themselves. The invitation to readers of the plugin KB is there - do you actually exist, and if you do, what do you want?

That is why I asked for opinions. I agree from the Profiles that FH v6 is dwindling.
It sounds like the deletion of Code Snippets that are only relevant to FH v5/v6 is perhaps the way to go?
That is certainly the simplest and cleanest strategy.
However, the rest of the KB still caters for FH v5/v6 users.

What I do to maintain my plugin backward compatibility with FH v7/v6/v5 is my concern.

Throwing in my 2 cents... I agree with Mark.

As a general strategy, I think that makes sense. I'm willing to be proven wrong by subsequent postings, but my feeling is that the overwhelming majority of potential readers of this material (and without readers, there's no point in producing it) will be FH7 users, and the handful of authors who need to maintain compatibility with earlier versions generally know what they are doing already.

As in all teaching material, we need to be clear in our minds who the target audience are, and what the learning objectives are. IMO, the KB is a primer to get people started. As they get more experienced, they can look at more advanced material from elsewhere and start to put it in context. But that's not the main focus of the KB - it's driven by what the readers need to know, not what the authors know.

With that in mind, one thing I would like to see in the snippets is some sort of grading system to indicate the level. Some are key features that are used all the time that everybody needs to learn, while others are much more specialised and esoteric and can come much later in the learning process.

Regarding your last point, Code Snippets are one of the few types of KB article that have no Skill Level assessment.
However, since all Plugins are probably considered Advanced, the grading of Code Snippets may need another scale.