Guidedog 0.2.1

Guidedog 0.2.1 adds discussion catalogs for any project, with two small programs: dsc and dscc.

A discussion catalog keeps proposals and decisions, one reStructuredText record each, under a prefix of your choice. Guidedog's own design records (GDS) are one. dsc creates a catalog, numbers drafts when they open for review, records each decision with its reason, and builds the catalog into a website and PDF books with the installed guidedog. dscc is dsc with Guidedog built in, for a machine with nothing else installed. guidedog gds now runs the same code on Guidedog's own catalog.

dsc init docs/eds --prefix=eds --name="Enso Discussions"
cd docs/eds
dsc new "Cache policy" --labels=architecture
dsc promote cache-policy
dsc state 1 --to=accepted --reason="Review converged"
dsc build

Records show their metadata as Number, Title, Authors, Updated, and Labels in HTML and PDF, for any prefix. A change to a catalog is whole or not made: when memory runs out, dsc stops and changes nothing it had not prepared whole, and an interrupted update rolls back with dsc recover --rollback. CHANGELOG.md lists the changes, and GDS 0007 explains the design.

This is still a beta for trusted documentation projects. Linux and macOS are the supported platforms; the Windows builds pass the automated checks and smoke tests but have had little use. Reports of problems are welcome as issues.

Downloads

File	For
guidedog-linux-amd64.tar.gz	Linux x86-64 with glibc 2.35 or later (Ubuntu 22.04, Debian 12, Fedora 36 or newer) and libcurl 4
guidedog-linux-arm64.tar.gz	Linux ARM64, with the same requirements
guidedog-macos-arm64.tar.gz	macOS 12 or later on Apple silicon
guidedog-macos-amd64.tar.gz	macOS 12 or later on Intel
guidedog-windows-amd64.zip	Windows 10 or later, x86-64
dscc-linux-amd64.tar.gz, dscc-linux-arm64.tar.gz	dscc alone, for Linux, with the same requirements
dscc-macos-arm64.tar.gz, dscc-macos-amd64.tar.gz	dscc alone, for macOS 12 or later
dscc-windows-amd64.zip	dscc alone, for Windows 10 or later
guidedog-0.2.1-source.tar.gz	The source of this release
guidedog.rb	A Homebrew formula that installs the macOS or Linux archive
SHA256SUMS	The SHA-256 checksum of every file above

Each guidedog archive holds one folder with guidedog and dsc, README.md, LICENSE, NOTICE, CHANGELOG.md, SOURCE.txt (the commit and the exact build commands), and guidedog.build.json (the version, target, toolchain, and the programs' checksums). Each dscc archive holds dscc with the same files, and dscc.build.json.

Verify

Download SHA256SUMS next to the archive and check it:

sha256sum -c --ignore-missing SHA256SUMS          # Linux
shasum -a 256 -c --ignore-missing SHA256SUMS      # macOS

The archives also have build provenance from GitHub Actions, which the GitHub CLI checks:

gh attestation verify guidedog-linux-amd64.tar.gz --repo insanai/guidedog

Install

With Homebrew, on macOS or Linux, install from the official tap. It installs guidedog and dsc:

brew tap insanai/guidedog
brew install insanai/guidedog/guidedog

Or unpack the archive and put the programs on your PATH:

tar -xzf guidedog-macos-arm64.tar.gz
sudo install guidedog-macos-arm64/guidedog guidedog-macos-arm64/dsc /usr/local/bin/
guidedog --version

dscc installs the same way from its own archive. On Windows, unzip the archive and add the folder to your PATH; keep the DLLs and config8 next to guidedog.exe and dscc.exe.

Platform notes

• The programs are not code-signed. On macOS, a file downloaded with a browser is quarantined; run xattr -d com.apple.quarantine guidedog once for each program, or download with curl. Windows SmartScreen may ask before the first run.
• Linux builds link the system's glibc and libcurl; on minimal systems install libcurl (apt install libcurl4, dnf install libcurl).
• macOS x86-64 is cross-compiled on Apple silicon, because Odin has no macOS x86-64 toolchain; it is smoke-tested on an Intel Mac.
• Linux and macOS link Graphviz 16.1.0 statically. Windows carries the official Graphviz 16.1.0 DLLs instead (windows-notice.txt lists them and their licenses). On Windows, diagram labels in scripts other than Latin are sized with Graphviz's own width tables, so long CJK labels can be wider than their shapes.
• PDF books use Typst's embedded fonts and the system's fonts. Books in Chinese, Japanese, Korean, or Hindi need fonts for those scripts installed.

License

Guidedog, dsc, and dscc are released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), with an additional permission to link and distribute them with Graphviz; see LICENSE and NOTICE. For other licensing terms, contact the authors.

Credits

Created by Vikrant Rathore, with assistance from Ronak Rathore and Kanak Rathore.

Thanks to Sphinx and Georg Brandl, Docutils and David Goodger, Typst, Tree-sitter and Max Brunsfeld, Graphviz, and Ginger Bill and the Odin community.

Guidedog 0.2.0

Guidedog 0.2.0 is the first public release.

Guidedog builds HTML documentation sites and PDF books from reStructuredText and Markdown. It is one program, written in Odin. The release builds carry the Typst compiler, Graphviz, and tree-sitter inside them, so building a site or a book needs no Python environment, no LaTeX installation, and no separate Typst program.

This is a beta for trusted documentation projects. Linux and macOS are the supported platforms. The Windows build is new: it passes the automated checks and a smoke test, but it has had little use so far. CHANGELOG.md lists what is in this release. Reports of problems are welcome as issues.

Downloads

File	For
guidedog-linux-amd64.tar.gz	Linux x86-64 with glibc 2.35 or later (Ubuntu 22.04, Debian 12, Fedora 36 or newer) and libcurl 4
guidedog-linux-arm64.tar.gz	Linux ARM64, with the same requirements
guidedog-macos-arm64.tar.gz	macOS 12 or later on Apple silicon
guidedog-macos-amd64.tar.gz	macOS 12 or later on Intel
guidedog-windows-amd64.zip	Windows 10 or later, x86-64
guidedog-0.2.0-source.tar.gz	The source of this release
guidedog.rb	A Homebrew formula that installs the macOS or Linux archive
SHA256SUMS	The SHA-256 checksum of every file above

Each archive holds one folder with the guidedog program, README.md, LICENSE, NOTICE, CHANGELOG.md, SOURCE.txt (the commit and the exact build command), and guidedog.build.json (the version, target, toolchain, and the program's checksum).

Verify

Download SHA256SUMS next to the archive and check it:

sha256sum -c --ignore-missing SHA256SUMS          # Linux
shasum -a 256 -c --ignore-missing SHA256SUMS      # macOS

The archives also have build provenance from GitHub Actions, which the GitHub CLI checks:

gh attestation verify guidedog-linux-amd64.tar.gz --repo insanai/guidedog

Install

On Linux or macOS, unpack the archive and put the program on your PATH:

tar -xzf guidedog-macos-arm64.tar.gz
sudo install guidedog-macos-arm64/guidedog /usr/local/bin/
guidedog --version

With Homebrew, install the formula from a local tap:

brew tap-new --no-git "$USER/local"
curl -fsSL -o "$(brew --repository "$USER/local")/Formula/guidedog.rb" \
    https://github.com/insanai/guidedog/releases/download/v0.2.0/guidedog.rb
brew install "$USER/local/guidedog"

On Windows, unzip guidedog-windows-amd64.zip and add the folder to your PATH. Keep the DLLs and config8 next to guidedog.exe.

Platform notes

• The programs are not code-signed. On macOS, a file downloaded with a browser is quarantined; run xattr -d com.apple.quarantine guidedog once, or download with curl. Windows SmartScreen may ask before the first run.
• Linux builds link the system's glibc and libcurl; on minimal systems install libcurl (apt install libcurl4, dnf install libcurl).
• macOS x86-64 is cross-compiled on Apple silicon, because Odin has no macOS x86-64 toolchain; it is smoke-tested on an Intel Mac.
• Linux and macOS link Graphviz 16.1.0 statically. Windows carries the official Graphviz 16.1.0 DLLs instead (windows-notice.txt lists them and their licenses). On Windows, diagram labels in scripts other than Latin are sized with Graphviz's own width tables, so long CJK labels can be wider than their shapes.
• PDF books use Typst's embedded fonts and the system's fonts. Books in Chinese, Japanese, Korean, or Hindi need fonts for those scripts installed.

License

Guidedog is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), with an additional permission to link and distribute it with Graphviz; see LICENSE and NOTICE. For other licensing terms, contact the authors.

Credits

Created by Vikrant Rathore, with assistance from Ronak Rathore and Kanak Rathore.

Thanks to Sphinx and Georg Brandl, Docutils and David Goodger, Typst, Tree-sitter and Max Brunsfeld, Graphviz, and Ginger Bill and the Odin community.