Working folder for Polygen Documentation.
Table of Contents
A quick walkthrough the various files and how to use them.
NOTE — In order to distinguish between markdown files intended for GitHub previewing and pandoc markdown files (with PP macros), in these folders we'll adopt the following file extensions convention:
The WORK_NOTES.md file contains important notes that should be read by anyone willing to edit or update the existing docs with new contents, or by translators to new locales.
If you only need to build the documents, you can skip those.
The original Manuals being reprinted (now renamed to Polygen Meta Language Spec), written by Alvise Spanò (author of Polygen):
Used as references during the markdown porting stage. The original HTML files were cleaned-up using HTML Tidy; they were downloaded from:
The markdown source files for Italian Polygen Meta Language Spec:
polygen-spec_IT.markdown— main Italian source filepolygen-spec_IT_inc_tables.markdown— include file with "Translation Rules" tables (Appendix)
The markdown source files for English Polygen Meta Language Spec:
polygen-spec_EN.markdown— main English source filepolygen-spec_EN_inc_tables.markdown— include file with "Translation Rules" tables (Appendix)
include files common to all versions of the manual (locale-agnostic):
polygen-spec_inc_abs.markdown— EBNF for §5.2 Abstract syntax.polygen-spec_inc_con.markdown— EBNF for §5.1 Concrete syntax.polygen-spec_inc_lex.markdown— EBNF for §5.3 Lexical rules.
The "Translation Rules" tables are kept in a separate include-file because of the excessive width of their rows. When editing these, you'll want to disable text wrapping in your code editor.
The converted HTML documents:
polygen-spec_IT.html— converted Italian doc (developers' preview).polygen-spec_EN.html— converted English doc (developers' preview).
These generated HTML docs have the same name as their counterparts in the repository root folder:
../polygen-spec_IT.html— current Italian doc (in root).../polygen-spec_EN.html— current English doc (in root).
The reason why the conversion scripts generate the docs in this folder (instead of directly into the root folder) is to keep development previews separate from the official releases. Having local access to both versions of a document allows developers to compare them in the browser (or via a diff tool) during the editing stages, without having to switch branches or check out specific commits.
As for the reason why we track these preview documents (instead of telling Git to ignore them) it's to enable proofreaders to access Live HTML previews of work-in-progress documents without having to clone the repository.
Although not a very elegant solution, it's a practical one — not only for developers, but also (and foremost) for proofreaders that don't know Git but would like to contribute.
These are the Bash scripts to convert the markdown source docs to html:
convert.sh— convert Italian or/and English doc(s)watch_IT.sh— watch and build Italian docwatch_EN.sh— watch and build English doc
NOTE — These scripts where written for Git Bash, the Bash terminal that ships with Git for Windows. Some commands in the scripts (or instructions) might be specific to Windows' Bash and need adjustments to be used in other *nix shells.
If you encounter problems executing them under different OSs and/or have a solution to improve their cross-platform support, please open an Issue with your suggestions or create a pull request with your solution.
The repository now offers a unified script for converting the documents:
The script accepts a single parameter: either the short-hand of a supported locale (en|it) or the all keyword (to build all available documents).
The script's command line syntax is:
convert.sh <all|en|it>
To convert the Italian document, open the Bash terminal in this folder and type:
./convert.sh itwhich will create/update the polygen-spec_IT.html file.
To convert the English document, same as above but type en instead of the it parameter:
./convert.sh enwhich will create/update the polygen-spec_EN.html file.
And to build the document in all the available languages at once, use the all parameter instead:
./convert.sh allwatch_IT.sh— watch and build Italian sourceswatch_EN.sh— watch and build English sources
The watch scripts will check for changes in all markdown sources connected to a given language, as well as the CSS files: every time you save a source doc the watch script will launch the conversion script for that language. If you're updating the CSS file via the Sass sources, every time the Sass compiler updates the CSS assets the watch script will trigger the conversion scripts again.
This is very useful, you'll only have to refresh the browser to update the output document and see the changes, without having to manually re-run any conversion script.
Various files required for building the docs from markdown to html:
/assets//sass/— Sass modules folderGitHub.html5— pandoc templatepolygen.lang— Polygen syntax for Highlightebnf2.lang— EBNF syntax for Highlightmacros.pp— PP macros module.polyman.css— Polygen docs CSS styles (built via Sass frompolyman.scss)polyman.scss— main Sass source file
You shouldn't bother about these unless you actually want to change elements of the build toolchain.
Third party tools folder:
Tools required for building the docs. You only need to set them up once (see: Third-Party Tools section).
The following script is used internally by convert.sh to setup the working environment:
It prepends the tools/ folder to the $PATH environment variable, so that all the required third-party tools from that folder become available to the current Shell and its scripts, taking precedence over pre-existing system-wide versions of the same tools (i.e. over more recent versions of the tools, if present).
This is a one-time operation that will last as long as the Bash terminal is open. The script contains some checks that make it safe to invoke it more than once (it simply won't have any further effects). No permanent changes are made to the system.
You won't usually need to invoke this script in your working sessions, but you might want to do so if you're planning to tweak the conversion toolchain and carry out some tests.
This feature was designed mainly for the Windows OS, for which the repository offers a script to fetch the exact version of all the required third party tools to build the documentation (see: Third-Party Tools section) in order to ensure that all developers use identical tools, thus preventing errors or differences in the generated HTML docs.
The script won't have any effect on OSs other than Windows, unless the end users has manually added to the tools/ folder the required binaries.
NOTE — Early versions of this repository required end users to manually invoke
init.sh(once) before converting the documents. This is no longer the case.
The scripts for building the documents must be invoked from Bash — you should already have Bash for Windows installed with Git. The Bash requirement is due to some PP macros using Shell commands; in the future I'll fix the macros to make them work with both Shell and CMD (right now it's not on top of the priorities list).
In order to run the conversion scripts you'll need the following tools:
- pandoc
v2.10.1 - PP
v2.14.1 - pandoc-crossref
v0.3.7.0a - Highlight
v3.57.1
The tools' version numbers in the list are the ones used for this project, and to avoid unneeded differences in the generated HTML docs, and potential conflicts, contributors to the project must use those exact versions.
All of these tools are small sized and available as standalone packages, so you don't need to install them system-wide: you can manually download and unpack them in the tools/ folder.
Windows' users can run our tools/download.bat batch script that will automatically download and set them up (for instructions see tools/README.md).
Because some precompiled binaries are only available for x86_64, you'll need a 64-bit OS (or you'll have to compile them yourself for x86).
In order to benefit from the wacth_*.sh scripts, you'll need to install the onchange tool (Node.js):
Onchange requires Node.js to be installed on your system:
The easiest way to install Node.js on Windows is to install the Node.js Chocolatey Package using the Chocolatey GUI package manager.
In order to build the assets/polyman.css stylesheet you'll need to install Dart Sass on your system.
The easiest way to install Dart Sass on Windows is to install the Sass Chocolatey Package using the Chocolatey GUI package manager.
NOTE — Early versions of this repository (
v1.1.0) relied on Ruby Sass, which reached its end of life in March 2019. We switched to Dart Sass in August 2020; so beware that if you checkout commits prior to the switch to Dart Sass the oldassets/SASS-BUILD.batandassets/SASS-WATCH.batscripts won't work with the Dart implementation of Sass.
The creation of Polygen documents reuses some third party resources, all compatible with the GPLv2 license.
For a full list of credits, and their licenses, see: