Q & A
Questions and answers about Spec-Up-T.
When I use Spec-Up-T do I get all the updates of Spec-Up too?
Yes. The administrator team behind Spec-Up-T will keep Spec-Up of DIF as a strict subset of code and features.
Can't we wait with the split up until because it might mess up thing for people curating the documents?
Splitting Spec-Up content over files is not an issue for people working on the content and looking at the github.io pages of the specification. It won't affect them. They see the same generated one-page document as a result. The index.html only has enhanced features. They can offer PRs as they always could.
How to get the original Spec-Up?
I don't want Spec-Up-T, I want the original Spec-Up, but then with their improvements to be able to xref, and keep track of history etc. Is this possible?
Some improvements have been incorporated into Spec-Up. Spec-Up will remain a subset of Spec-Up-T. The extensions you will find only in Spec-Up-T are listed in the introduction.
Where to find Spec-Up-T?
Spec-Up-T is a github.com repo under Blockchainbird user: https://github.com/blockchainbird/spec-up-t. You can find the source code there.
Unlike the DIF Spec-Up repository, the Spec-Up-T repository does not generate an example specification on github.io.
This functionality has been moved to the Spec-Up-T installer.
For more details, refer to the installation section in the admin guide.
Why do I need to put commands on the command line?
Brief answer: because Spec-Up-T is based on NPM packaging and version control.
To understand why more thoroughly: Spec-Up-T is team-work tooling based on NPM, git versioning and (automated) github deployment. Therefore participants incept and maintain local version of specifications on their computer, manage updates to and fro github.com and generate local test and finally production sites (github actions github.io site). With this type of creation and collegial management of versions and updates come commands on the command line.
What is the command for help?
TODO: npx Spec-Up-T --help gives all commands I can give.
Why does Spec-Up-T look so complicated?
Spec-Up was simple, Spec-Up-T looks complicated, why?
Spec-Up is a subset of Spec-Up-T. The expansion "T" complicates the handling of term definitions, - references and external references (xrefs) of term in other repo's glossaries. ToIP added functionality as well: diff tooling, search bar, and navigation aids.
On the other hand, Spec-Up-T is installable via just a single command:
npx create-spec-up-t my-spec-up-t-website
For who is Spec-Up-T?
The repo, command-line tools and the Docusaurus User guide is for Authors, Curators and Administrators of repo's that use Spec-Up-T to run there specification effort in text, images, terms & definitions, etc.
The resulting github.io site is intended for any user interested in the content of the specification.
Do you have a how-to video to get started with Spec-Up-T?
Yes. Find it here: Short video
Where can I find the motivation of this move to create the Spec-Up bolt on "Spec-Up-T"?
Our enhancement proposal and git governance strategy is here.
Why doesn't the Spec-Up-T repo generate a github.io-served specification itself?
The repo Spec-Up-T doesn't generate an example specification on github.io. because it's not the purpose of this repo. Your example site will pop up when “spec-up-t” is installed in node_modules of spec-up-t-starterpack when you run npm install.
How to integrate Spec-Up-T in other systems
We already have a Docusaurus (or Jekyll, etc) site. Is it possible to have a Spec-Up-T specification inside this site?
Yes and No.
No
Installing Spec-Up-T inside Docusaurus (or Jekyll, etc) is possible, however it is not recommended practice to have nested node_modules directories. Docusaurus (or Jekyll, etc) have their own node_modules directory. You can install Spec-Up-T in a sub directory in which it will get it's own node_modules directory after installation but this is not recommended.
Yes
You can install Spec-Up-T in it's own separate directory in your file system and generate the index.html file. This file can be moved around freely and live in it's own directory, for example in the /static directory of your Docusaurus site. You can rename index.html to foo.html or whatever you like. You could link to this file from other files in your Docusaurus site.
However, the Spec-Up-T file (a one-page website) will have it's own menu and have no connection to your Docusaurus site.