Deprecate the use of pre@source in datafiles

[skiadas]

See #2755

This PR:

• Adjusts the example that used dataset[pre@source] to use xi:include instead.
• Amends the guide to suggest this approach instead.
• Adds a deprecation warning.

[rbeezer]

OK, this whole #datafile dance makes my head hurt. It feels like we should seriously re-evaluate the whole thing, but I don't have any good suggestions at the moment.

We have three directories of non-XML stuff. Generically: generated, external, data. But you can name them whatever you want, like the sample article has "media/" for the external directory. The publisher file has the translation.

Why? You could have a B&W version of a book and a color version. And you make two external directories, one with grayscale photographs, the other with color photographs (identical names, but for the root directory). Switching publisher files, lets you easily make two different books.

Now, the stack-overflow example here has a path that leads with "./ext", which really threw me off. I thought to myself, that file will end up in the renamed "./external" in a temporary build directory. Well, no, it survives. Why? The xi:include always happens very early in the processing, before any XSL gets applied.

So, this file is really source material. (Maybe why we had a @source attribute?) It is just like the author typed a bunch of text inside the #pre, inside the source. So it could live as a peer of rune.xml, say. Or better, inside some directory a step lower.

Comments?

Also, I like to fix deprecations in the pre-processor. Not sure if we want to do this automatically here or not? Pick up @source and write it in an xi:include?

A fall-back option is to warn that in a year or so, the @source version will be neutered to just display a message saying a datafile belongs here. Ands then we can remove stale code, which we always try to not leave around in any case.

Comments?

If something needs to be on the pretext-dev thread, we could move there - I've not reviewed it just now.