The simplest possible build command should be `build main.src`, which should do something predictable and useful. By addressing this want, we're presented with an opportunity to solve another nagging problem. This is the origin of the the "default build profile" and the new `publish` command.
First the related problem: acute concern that people are unlikely to respect our exhortation to respect the triple script invariants and not impinge/torpedo the triple script file format.
exhortation: https://triplescripts.org/format/
So we introduce the "default build profile". When building a program with trplkt, the default profile does not output a file that conforms to the triple script file format. Instead, it (a) uses double slash delimiters, and (b) includes a "byline". Both serve to interfere with dissemination of non-triple scripts masquerading as valid triple scripts triple slash delimiter. The byline is repeated, appearing as the first line in the file and then again as the last line. Double slash script delimiters are used as a hedge against the removal of the first byline. Any file which includes a byline (whether one or both) is to be considered an invalid triple script (regardless of whether triple slash delimiters are used).
In the default (aka prerelease) build profile, triple slash directives otherwise still used. Significant, because they're actually part of the dialect--with `/// import`, for example, being one possible representation of the "same" import token (same-ish as `import`, just different forms; they actually vary by 1 bit of information) XXX on second thought, triple slash directives (excluding byline?) should be changed to use prefix of `// @` or `// !` or `// ?` or something. NB: this affects tokenization even for normal triple scripts (otherwise you get collisions)
The byline acts as a strong signal that this is *not* a triple script.
Byline is the `$sum$` attribute followed by fixed with hex encoding of a checksum (CRC-32?), hex encoding of the time of the build (measured in seconds since New Years Day, 2000), and then the text of the build command-line arguments (the "build" is implied)
Example/candidate outputs:
/// $sum$: 0x12471248, 0x269B4EE0, `./src/TripleKit.js -m ./src/main.js`
/// $sum$: 0x12471248, 0x269B4EE0 // ./src/TripleKit.js -m ./src/main.js
/// $sum$: 0x64771248, 0x269B4EE0 // ./src/main.src
XXX Byline should/could also encode the version used to build it (but this can wait for the last release before 1.0?)
To publish a proper triple script, trplkt will include a new `publish` command, which shall take a build using the default profile and emit a proper triple script instead.
Triple script authors will be encouraged to always test their work with a simple `build main.src` during development (and include instructions in the README for the same, for most contributor-friendly approach) Then project maintainers can run it through the `publish` command when they are ready to disseminate it to others. This makes the creation of a file carrying the correct triple script file magic a deliberate act, but a natural enough one that make sense in its place in the workflow.
We expect this will be an attractive enough workflow to dicourage folks from torpedoing attempts to allow the triple script file format actually signify something and we expect this to provide a good jumping-off point for people to further explore the concatenated t-block format (read: using d-blocks).
Changes to current conventions:
Program authors are encouraged to make the top-level module aka the "heart" of the program the first import in main.src.
Need to encourage people setting out to write triple scripts by hand to not use triple slash delimiters, and ideally include something that might be dissimilar to the format of the byline, but still serves a similar purpose of disrupting accidental dissemination of scripts that appear (by formatting) to be full-fledged triple scripts even when they really aren't.
It could be as simple as:
/// $profile$: "handcrafted"
or:
/// Bumblefudge, a Lisp pretty printer by Mavis Turpin
... and we can even encourage people to omit imports/exports on their first draft, and we'll provide tooling (a helper to "publish") to suss out the correct annotations. (We could call this the "handcrafted" build profile?) XXX requires deep (total) total parsing, rather than our current naive partial parsing strategy...
Other notes:
If the byline is missing, `publish` will scan the file to make sure it passes basic sniff tests and provide verbose output about the exact decomposition it came up with, for user review. Since the byline would include the full command-line arguments, we can also check if we're able to reproduce the output based on the transient decomposition. If this fails, we will still complete the build, but print warnings to stderr (or equivalent) and return a non-zero exit code. If the byline *is* included, but it has a mismatched checksum, then we will outright refuse to perform the transformation unless `--force` is passed to the build command.
---
/// "handcrafted"
//? <script>
class Foo { }
//? </script>
//? <script>
class Bar { }
//? </script>
//? <script>
class Baz { }
//? </script>
//? <script>
window.onload = () => {
document.write(Foo.name);
document.write(Bar.name);
document.write(Baz.name);
}
//? </script>
2020 October 09: So this is implemented now in trplkt 0.11, but not necessarily following the design laid out above. There is a problem, though, which is that if we want the generic (g-block-based) form to be suitable for the Web (and it's clear that we do, necessarily...), then we have to do something about the close delimiters. Testing a very simple example, where we create an ordinary HTML document, but add a simple script element after the body and dump an unaltered g-block script into it surfaces concerns about parsing. First, and most minor, each block gets its own script parent, which is not necessarily what we want. Secondly, the stray `//? ` show up in between blocks, which we need to do something about. However, if we omit all close delimiters except for the one on the last line, then we have no strays to take care of, and everything ends up in one script parent. Something to think about (e-profile? i.e. "embedded"/"embeddable"?)