This repository hosts the documentation source for both TokenScript and SmartLayer websites. We've adopted dita
for our documentation. Curious about our choice? Check out why not GitBook.
Setup Dita Toolkit:
dita-4.1
as it's the only version we've tested with.Plugin Installation:
$ dita install fox.jason.extend.css
$ dita install fox.jason.favicon
$ dita install net.infotexture.dita-bootstrap
A deviation from this order might necessitate a reinstall.
Dita Diagram Plugin:
com.oxygenxml.diagrams.svg
folder from the dia-ot-diagrams-plugin to the plugins
directory in your dita installation. Then, run:
$ dita --install
A successful installation will acknowledge the plugin com.oxygenxml.diagrams.svg
.
Generate Stuff:
To create a website for a document project, use:
$ dita --project config/smartlayer-docsite.yaml -o out/document.smartlayer.network
This command populates the out/
directory with the website.
To create a website for TokenScript project, use:
$ dita --project config/tokenscript-docsite.yaml -o out/tokenscript-docs
For compiling the Smart Token paper, use:
$ pandoc --toc=true --resource-path=src/papers --csl src/papers/chicago-author-date.csl --citeproc --bibliography src/papers/smart-token-paper.bib -o out/smart-token-paper.pdf src/papers/smart-token-paper.md
For compiling the TokenScript Design paper, use:
$ dita --project config/tokenscript-papers.xml
The results - tokenscript-design-paper.pdf and tokenscript-short-paper.pdf - can be found in out
For compiling the SmartLayer Overview paper and its detailed counterpart:
$ dita --project config/smartlayer-paper.xml
The results - smartlayer-overview.pdf and smartlayer-paper.pdf can be found in out
For the Smart Token Technical paper, which wasn't using dita, it can be created using
$ pandoc --resource-path=src/papers --csl src/papers/chicago-note-bibliography.csl --citeproc --bibliography src/papers/smart-layer-technical-paper.bib -o out/smartlayer-technical-paper.pdf src/papers/smart-layer-technical-paper.md
This result is a single PDF file: smart-layer-technical-paper.pdf.
Here's a snapshot of our directory structure and their respective roles:
Directory | Description |
---|---|
cli/ | Command-line utility documents. Future plans include moving this to product/cli . |
concept/ | Houses conceptual documents. |
developers/ | Developer-centric documents. These will be relocated to usecase and guide . |
elements/ | TokenScript elements. |
faq/ | Frequently Asked Questions. |
features/ | Details on features across different versions of Smart Layers or TokenScript. |
guide/ | Code-based guides for developers. |
integration/ | Initially contained integration guides. These will be distributed among other directories. |
privacyandsecurity/ | Will be distributed into other directories. |
research/ | A collection of research papers and studies. |
specs/ | Technical specifications, primarily for implementors. This will be renamed to spec/ . |
technology/ | Introductory materials for a broader audience, sans immediate code solutions. |
tokenscript-paper/ | Contains chapters of the paper written in markdown. |
usecase/ | Use-case materials, including technical guides and case studies. |
Assuming using Linux or OS X, to avoid commit errors, consider creating a .git/hooks/pre-commit
with:
#!/bin/sh
dita --project config/smartlayer-paper.xml
dita --project config/tokenscript-papers.xml
pandoc --resource-path=src/papers --csl src/papers/chicago-note-bibliography.csl --citeproc --bibliography src/papers/smart-layer-technical-paper.bib -o out/smart-layer-technical-paper.pdf src/papers/smart-layer-technical-paper.md
Then make it executable. This should detect any error before commit.
This isn't added to the git repo due to potential variations in dita
executable locations and system differences.
If you possess the requisite credentials, you can upload the website to a hosting account:
$ lftp -c 'open cobalt.primarywebservers.com; mirror -x .git --exclude-glob-from=.gitignore -R out/ ./'
Error from running pandoc: option '--toc' doesn't allow an argument
Solution: Likely because your pandoc version is too low, consider pandoc 3.2.
Error from running pandoc: `pdflatex not found. Please select a different --pdf-engine or install pdflatex
Solution: install the package that provides pdflatex. On Ubuntu/Debian, it is sudo apt install texlive-latex-base
.
Error from running pandoc: ! LaTeX Error: File
xcolor.sty' not found.`
Solution: install the package that provides it. On Ubuntu/Debian, it is texlive
Error: "html5-bootstrap" is not a recognized transformation type
Solution: This arises from an improper installation of net.infotexture.dita-bootstrap
. Resolve by reinstalling the plugins in the specified order:
$ dita uninstall net.infotexture.dita-bootstrap
$ dita uninstall fox.jason.favicon
$ dita uninstall fox.jason.extended.css
$ dita install fox.jason.extend.css
$ dita install fox.jason.favicon
$ dita install net.infotexture.dita-bootstrap