Bikeshed prebuilt

🚲 Bundles Bikeshed for use without Python or pip
🔀 Forked from speced/bikeshed

GitHub releases (this project) | Official Bikeshed website | Official bikeshed PyPI package | Official Bikeshed GitHub

🐍 Uses PyInstaller
🏭 Compiles the bikeshed PyPI package to a standalone program
🚚 Distributed via GitHub releases
💻 Builds for Windows x64, macOS M1 and Intel, and Linux x64

Installation

🛑 If possible you should install Bikeshed directly from the bikeshed PyPI package as is officially recommended.

pipx install bikeshed

You can get Bikeshed builds built by this bikeshed-builder project from the GitHub releases tab. These are unofficial.

This project is intended to be used & integrated with software that works better without the Python & pip requirements that the official Bikeshed distribution method uses. You can also use it as a standalone way to install Bikeshed without a Python environment. For example an npm redistribution of the Bikeshed project to be npm install <bikeshed_package_name> would not want to require a particular Python environment. Instead, they would opt for a premade all-in-one binary/package such as the PyInstaller bikeshed released by this project! 😊

Here are the relevant URLs that you would use in your code to fetch releases from this bikeshed-builder project:

https://nightly.link/jcbhmr/bikeshed/releases/download/4.1.10/bikeshed-macosx_10_13_universal2.tar.gz
https://nightly.link/jcbhmr/bikeshed/releases/download/4.1.10/bikeshed-manylinux2014_x86_64.tar.gz
https://nightly.link/jcbhmr/bikeshed/releases/download/4.1.10/bikeshed-win_amd64.zip

Programs are encouraged to pin an exact version of Bikeshed and then update Bikeshed as a dependency as opposed to always fetching the latest bikeshed release binaries.

Here's some cool😎 nightly.link URLs which I don't recommend using.

https://nightly.link/jcbhmr/bikeshed/workflows/pyinstaller/main/bikeshed-macosx_10_13_universal2.zip
https://nightly.link/jcbhmr/bikeshed/workflows/pyinstaller/main/bikeshed-manylinux2014_x86_64.zip
https://nightly.link/jcbhmr/bikeshed/workflows/pyinstaller/main/bikeshed-win_amd64.zip

The .zip and .tar.gz archives all have the same layout:

.
├── bikeshed
└── _internal/
    └── <pyinstaller_files>...

Note that everything is in the root folder! TODO: What's the prevailing convention? Should there be a wrapper folder inside the tar/zip archive?

📚 Read the Bikeshed documentation for how to use the bikeshed CLI

Development

This is a friendly fork🔀 of speced/bikeshed. I don't know if upstream wants to host prebuilt binaries. 🤷‍♀️ This project is a small patch (hopefully) that should build each Bikeshed CLI version and publish some sweet precompiled binaries.

Bikeshed doesn't do release tags. Make sure to manually watch the release notes issue and then merge any changes into this fork.

To create a release of this project:

Run the gh release create workflow manually
Choose draft: true
Hope it works
Manually check that things look OK
Publish the draft release
Update the copyable URLs in the Usage section

Bikeshed, a spec preprocessor

Bikeshed is a pre-processor for spec documents, turning a source document (containing only the actual spec content, plus several shorthands for linking to terms and other things) into a final spec document, with appropriate boilerplate, bibliography, indexes, etc all filled in. It's used on specs for CSS and many other W3C working groups, WHATWG, the C++ standards committee, and elsewhere!

The processor can be easily installed and run locally (requiring no network access unless you're updating), or accessed as a CGI without any installation at all: https://api.csswg.org/bikeshed/

A short overview of some of Bikeshed's features:

automatic linking of terms to their definitions based on text, so you can simple write Use <a>some term</a> to... and have it automatically link to the <dfn>some term</dfn> elsewhere in the document, or in another spec entirely!
automatic id generation for headings and definitions, based on their text.
textual shortcuts for autolinks: [[FOO]] for bibliography entries, <<foo>> for grammar productions, 'foo' for CSS property names, {{foo}} for IDL terms, and more.
boilerplate generation, both wholesale and piecemeal.
Bikeshed-flavored Markdown, a slight variant that is extra-friendly to intermixing with normal HTML. (Besides the few intentional divergences, compliance with CommonMark is expected.)
a compact syntax for writing property-definition tables.
automatic whitespace-prefix stripping from <pre> contents, so the contents can be indented properly in your HTML.
automatic IDL processing and syntax-checking for <pre class=idl> contents, so you don't have to mark up every single significant term yourself.
automatic generation of railroad diagrams from <pre class='railroad'> contents.

Documentation Sections

The full Bikeshed documentation is generated by Bikeshed and accessible here.

Note About Fatal Errors

Bikeshed generates "fatal errors" for lots of things that it wants you to fix, but generally recovers gracefully from them anyway. If you're getting a fatal error, but don't have time to fix it and just need a spec right now, you can force Bikeshed to generate anyway with the -f flag, like: bikeshed -f spec.

This is also sometimes useful when converting a spec to Bikeshed for the first time, so you can see all the errors at once and fix them in whatever order is easiest, rather than having to deal with them one-by-one with no idea when they'll end. (You may also want to silence the warnings in this case, to reduce visual noise until you've gotten it at least building successfully. Use bikeshed -qf spec.)

Bikeshed File Extension

The preferred file extensions for Bikeshed source files is bs, like index.bs. Bikeshed will automatically recognize *.bs files in the folder it's run in, and assume that you want an output file of the same name with a .html extension. The repository also contains a syntax highlighting script for Bikeshed source files.

(Bikeshed also recognizes files with *.src.html for backwards compatibility with older CSS specs, though most such specs have switched their source file extensions to .bs now. Using .src.html in most text editors will display the file with HTML source formatting, which isn't generally what you want.)

License

This document and all associated files in the github project are licensed under CC0 . This means you can reuse, remix, or otherwise appropriate this project for your own use without restriction. (The actual legal meaning can be found at the above link.) Don't ask me for permission to use any part of this project, just use it. I would appreciate attribution, but that is not required by the license.

jcbhmr / bikeshed