NeoFS Technical Specification
This document uses a mix of Markdown and LaTeX in pandoc flavors. Target output formats are PDF and HTML.
For non-generated plain text we follow single line paragraph style.
Install pandoc and LaTeX base. Please see Dockerfile for the detailed list of what you might need.
After pandoc and LaTeX base are available, you can simply run make, which will generate the specification paper in pdf and html.
The easiest way to build a specification document is to use Docker. Just add docker/ to any Makefile target to run it inside a container having all required tools already available.
- Compile the specification paper pdf using
make docker/pdf - Output will be generated as
output/neofs-spec-<revision>.pdf
You can build docker image locally with make image command.
If you know NeoFS technology and want to contribute, feel free to directly submit a Pull Request with the desired changes.
Initially, the idea is to create a broad and complete initial version of the document, which will be polished in the future.
Pictures should be placed in pic directory of the corresponding section. Vector formats are preferred and strongly recommended. Please always provide the source file for the picture to allow future edits.
Expected formats:
When referencing a picture in the document text, please omit file extension. Most appropriate format will be used depending on the document output format.
Example:
To render all PlantUML files to SVG run make puml2svg or make docker/puml2svg
To convert all SVG files to PDF make svg2pdf or make docker/svg2pdf
Place PlantUML files under pic/ directory of the corresponding section and name it with .puml or .plantuml file extension. It will be automatically rendered to SVG format by puml2svg make target.
Draw.io diagrams must be exported to SVG format and saved under pic/ directory of corresponding section. To avoid text rendering errors, please follow this guide. Don't enable Embed Images checkbox, or raster image version will be saved in PDF instead of vector image version.
Please palace the source .drawio file in the same directory with exported SVG to allow future edits.
License: CC BY-NC-SA 4.0
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Pandoc/LaTeX template Eisvogel is licensed by BSD 3-Clause License.