:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
Perhaps it would be useful to you to know how we use Bikeshed in our workflow. I will share some details here.
Our documents consist of contributions from subject matter experts who are as a rule not familiar with Git or writing code. We expect a large set of contributions to come from people just using the text editor in GitHub web GUI, without ever cloning a repo onto their local workstation. In this light, we have made a quick "what is a fork and what is a pull request" style guide for our contributors and editors: https://dashif.org/DocumentAuthoring/
The contributors and editors generally never interact with Bikeshed or any other tooling. When they create a PR, our build bot publishes the outputs in a comment for author/editor review. We have the Bikeshed HTML and also a PDF generated from this HTML. We also post a link to a diff of this HTML to the master branch HTML (using the W3C HTML diff tool).
In addition to basic Bikeshed compilation (which we use the web service for), we include diagram generation from PlantUML text files, to enable diagrams to be more easily authored and versioned. Probably there are contributors who will find this uncomfortable and would prefer Visio diagrams etc but I guess it is worth it in the end.
For contributors who feel more comfortable with using Git and command line tooling, we publish a PowerShell module (both Windows and Linux compatible) called BikeshedDocumentAuthoring that provides them an Invoke-DocumentCompiler command, which when run in a repo matching our workflow performs all the necessary operations to go from source code to final outputs (diagram generation, Bikeshed validate + compile, PDF conversion).
This workflow was worked out on a smaller 25-page document earlier this year and the experience felt comfortable enough to take it up also for our larger outputs. Will see over the next 6 months how it works out in practice!
One of our contributors somehow ended up installing Bikeshed anyway, despite the guide never saying to do so :) He ran into trouble at the Python/pip stage pretty fast.
I really like Go's style of building self-contained executables. I recall in the past seeing some Python apps also distributed as self-contained directories, "just run unzip and run the binary" style. No idea what packaging like that entails, though - I have not touched Python in 10 years - but a distribution model like that would probably be very helpful in making Bikeshed more foolproof to install.
https://github.<namespace>/<user-org>/<name> here: tabatkins/bikeshed#1421
Although I've had no problems including SVG diagrams created with https://draw.io in bikeshed, I've ran into lots of problems w/ SVG created from https://plantuml.com
I put some comments about this on a related issue: tabatkins/bikeshed#1403
Basically, the problem is that with the following:
<pre class=include>
path: diagram.svg
</pre>bikeshed is parsing diagram.svg as if it was bikeshed source!
So, I'm wondering about adding a mechanism to allow including raw HTML in bikeshed, i.e., something like this:
<pre class=include-html>
path: diagram.svg
</pre>I realize that this could be abused and a source of difficult to figure out problems. However, its clear that we need some way of letting bikeshed include diagram content without parsing it as bikeshed source.
Has this topic been discussed/addressed before?
See tabatkins/bikeshed#1427
This handle things like:
<dfn lt="examplea">Example A</dfn>
<dfn lt="exampleb">Example B</dfn>
<xmp highlight=html>
<pre class=include-svg>
path: example.svg
</pre>
</xmp>where example.svg has hyperlinks like this:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg viewBox="0 0 150 50" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<defs></defs>
<rect x="10" y="10" width="40" height="40" style="fill: rgb(216, 216, 216);"></rect>
<a xlink:href="#examplea">
<text x="20" y="40" style="white-space: pre; fill: rgb(51, 51, 51); font-size: 24px;">A</text>
</a>
<rect x="100" y="10" width="40" height="40" style="fill: rgb(216, 216, 216);"></rect>
<a xlink:href="#exampleb">
<text x="110" y="40" style="white-space: pre; fill: rgb(51, 51, 51); font-size: 24px;">B</text>
</a>
<line style="stroke: rgb(0, 0, 0);" x1="50" y1="30" x2="100" y2="30"></line>
</svg>This is actually taken from a new clause 5.11.2 in the bikeshed spec.
Now that we can build a docker image for bikeshed, are you going to publish an official image somewhere?
I am aspiring for Google Summer of Code 2020. I came across the idea you are mentoring for, i.e. rewriting bikeshed in Rust, and would want to how I can help. I have some adequate experience with RustLang and Python. But still, I request your guidance with relevant resources in order to make better contributions.
status-ED.include and status-RD.include files. They show up properly for some specs, but not for others. I've verified that Status is either ED or RD. Is there another parameter I'm missing?
I cloned a repository containing multiple .bs files, people pointed me there, I installed bikeshed but I do not get how to build/access my builded files
spec command
