Skip to content

Commit

Permalink
updated README for easy to read
Browse files Browse the repository at this point in the history
  • Loading branch information
@SmartLayer
SmartLayer committed Sep 5, 2023
1 parent 6c524fe commit 78dd436
Showing 1 changed file with 85 additions and 72 deletions.
157 changes: 85 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,102 @@
# TokenScript and Smart Layer Documentation

This repository contains the source code for the TokenScript and SmartLayer websites' documentation. This repository uses dita. See [why not GitBook](WHY-NOT-GITBOOK.md).

## Building the Documents:

1. Download and install [Dita Open Toolkit](https://www.dita-ot.org). We only test it on dita-4.1 presently.

2. Install the plugins `net.infotexture.dita-bootstrap` and `fox.jason.favicon` in the following order:

````
$ dita install fox.jason.extend.css
$ dita install fox.jason.favicon
$ dita install net.infotexture.dita-bootstrap
````

Please note that the order of installation is crucial on some systems. If you fail to follow this exact order when installing the plugins, you may need to uninstall all of them and start again.

3. Install a dita diagram plugin. This has to be installed manually, by copying the folder `com.oxygenxml.diagrams.svg` to your dita installation location's `plugins` directory, then install it with

```
$ dita --install
```

It should prompt that plugin `com.oxygenxml.diagrams.svg` is successfully installed.

4. Generate a website for one of the document projects. For example, `config/smartlayer-docsite.yaml`:

````
$ dita --project config/smartlayer-docsite.yaml -o out/document.smartlayer.network
````

This will create a website in the `out/` directory.

## Document Structure

The table below provides an overview of the directories and their contents:

| Directory | Status | Content |
|----------------------|--------|---------|
| cli/ | To be moved to product/cli | Command-line utility documents. We plan to have a product folder to introduce a few products and CLI is one of them. |
| concept/ | Stays | Concepts |
| developers/ | To be removed with the introduction of @audience | Developer-oriented documents, to be moved to usecase, guide |
| elements/ | Remains | TokenScript elements |
| faq/ | Remains | FAQ items - many clusters in FAQs.md |
| features/ | Remains | Which version of Smart Layers or TokenScript has which feature. |
| guide/ | Remains | Developer-oriented code-based guides |
| integration/ | To be dispersed into other directories | Originally covering an integration guide and a few documents |
| privacyandsecurity/ | To be dispersed into other directories | |
| research/ | Papers and studies | This is the only container type directory. Other directories represent a category of information, this is just a container of all research to be shared. |
| specs/ | To be renamed spec/ | Tech specifications that are usually only interesting to the implementors |
| technology/ | Remains | It's similar to a codeless version of the guide/, it contains introduction materials written for a wider audience and does not use code immediately to solve every problem. |
| tokenscript-paper/ | Remains | Originally the paper was written in chapters in md, it was later integrated with dita so each chapter remains a file in md. There is no intention to change it too much. |
| usecase/ | Remains | Use-case based materials, there are case-studies and guides. Use-case guides are more technical. |

## Notes for Contributors

We recommend creating a `.git/hooks/pre-commit` with the following content to prevent errors in the commit:
# TokenScript and Smart Layer Documentations

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](WHY-NOT-GITBOOK.md).

## Compiling the Documentation:

1. **Setup Dita Toolkit**:
- Download and set up the [Dita Open Toolkit](https://www.dita-ot.org). Ensure you're using `dita-4.1` as it's the only version we've tested with.

2. **Plugin Installation**:
- It's essential to install the plugins in the correct sequence:
````
$ 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.
3. **Dita Diagram Plugin**:
- Manually copy the `com.oxygenxml.diagrams.svg` folder from the [dia-ot-diagrams-plugin](https://github.com/oxygenxml/dita-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`.
4. **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 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/tokenscript-paper/`
- 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/smartlayer-paper/`
- For the Smart Token Technical paper, which wasn't using dita, it can be created using
````
$ pandoc -o out/smart-layer-technical-paper.pdf src/papers/smart-layer-technical-paper.md
````
This results a single PDF file: `out/smart-layer-technical-paper.pdf`.
## Directory Overview:
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. |
## For Contributors:
To avoid commit errors, consider creating a `.git/hooks/pre-commit` with:
```
#!/bin/sh
dita --project config/tokenscript-docsite.yaml --project config/smartlayer-docsite.yaml
```
Please note that this is not added to the git repo because your `dita` executable might be in a different location or you may be using Windows and lack `/bin/sh`.
## Notes for Sysop
This isn't added to the git repo due to potential variations in `dita` executable locations and system differences.
If you have the necessary credentials, you can upload the website to a web hosting account, like this:
## Sysops:
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/ ./'
````
## Troubleshooting

### `"html5-bootstrap" is not a recognized transformation type`
## Issues and Fixes:
If you encounter the following error:

````
$ dita --project config/smartlayer-docsite.yaml -o out/document.smartlayer.network
Error: [DOTA001F][FATAL] "html5-bootstrap" is not a recognized transformation type. Supported transformation types are dita, eclipsehelp, html5, htmlhelp, markdown, markdown_gitbook, markdown_github, pdf, pdf2, xhtml.
make: *** [Makefile:18: website] Error 1
````
**Error**: `"html5-bootstrap" is not a recognized transformation type`
This is caused by `net.infotexture.dita-bootstrap` not being installed properly. You can resolve it by uninstalling and reinstalling the plugins in the correct order:
**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
Expand Down

0 comments on commit 78dd436

Please sign in to comment.