| Both sides previous revisionPrevious revision | Next revisionBoth sides next revision |
| tools:bikeshed [2014/01/27 23:23] – add Troubleshooting section with a couple of initial beginner errors tantek | tools:bikeshed [2014/04/21 18:12] – Copy/modify a bunch of the older preprocessor instructions tabatkins |
|---|
| ====== Bikeshed ====== | ====== Bikeshed ====== |
| Bikeshed, a spec preprocessor | Bikeshed is a spec preprocessor, allowing you to write specs in a much more convenient source format than raw HTML, and have the full spec with all the boilerplate and other features (table of contents, etc) automatically generated for you. |
| |
| Bikeshed is a pre-processor for the source documents the CSSWG produces their specs from. We write our specs in HTML, but rely on a preprocessor for a lot of niceties, like automatically generating a bibliography and table of contents, or automatically linking terms to their definitions. Specs also come with a lot of boilerplate repeated on every document, which we omit from our source document. | [[https://github.com/tabatkins/bikeshed|Bikeshed is maintained on GitHub]], and the documentation there describes the full suite of features, which are very useful. |
| |
| 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/ | Bikeshed can be easily installed and run locally (requiring no network access unless you're updating the processor or its databases), or accessed as a CGI without any installation at all: https://api.csswg.org/bikeshed/ |
| |
| See https://github.com/tabatkins/bikeshed#bikeshed-a-spec-preprocessor for more details. | See https://github.com/tabatkins/bikeshed#bikeshed-a-spec-preprocessor for more details. |
| |
| ===== Troubleshooting ===== | ===== Basic Overview ===== |
| ==== blank page ==== | |
| If you get a blank page from submitting the bikeshed webform, then | |
| * go back to the Bikeshed web form - https://api.csswg.org/bikeshed/ | |
| * change the "Output" radio button to "Errors & Warnings" | |
| * resubmit to get actual specific errors | |
| |
| | You'll most likely be editing a file called: |
| | |
| | <code>Overview.bs</code> |
| | |
| | that you'll need to turn into (and update in place when it's already there) |
| | |
| | <code>Overview.html</code> |
| | |
| | by running Bikeshed **before** committing your work. |
| | |
| | (If you're not generating a spec for the CSSWG, the filename might be something else, like ''index.bs'' turning into ''index.html''.) |
| | |
| | ==== Using Bikeshed Locally ==== |
| | |
| | [[https://github.com/tabatkins/bikeshed/blob/master/docs/install.md|Bikeshed's install instructions]] are designed for installing on a Debian Linux system, like Ubuntu. I know that people have installed Bikeshed on Mac systems, but they haven't recorded their steps; if you're feeling adventurous, please install it and send me the instructions! |
| | |
| | Once it's installed, just go to the spec's source folder and type: |
| | |
| | <code>$ bikeshed</code> |
| | |
| | Further instructions and tips can be found in the [[https://github.com/tabatkins/bikeshed/|Bikeshed README]]. |
| | |
| | ==== Using a Command-Line Script ==== |
| | |
| | If you're on a system with [[http://curl.haxx.se/|curl]] on it, just save the following line to a file somewhere in your executable path: |
| | |
| | <code> |
| | curl https://api.csswg.org/bikeshed/ -F file=@Overview.bs -F force=1 > Overview.html |
| | </code> |
| | |
| | Mark the file as executable, then just run it from within the folder of the spec you're working on. It will automatically submit ''Overview.bs'' to the post-processor and save the results to ''Overview.html''. |
| | |
| | ==== Using the web form ==== |
| | |
| | - Go to: https://api.csswg.org/bikeshed/ |
| | - Click (Choose File) and select the ''Overview.bs'' file on your local machine that you want to post-process (you should do this when you're ready to check it in). (Alternately, paste in your source text, or enter the URL of the source file, if it's already been committed.) |
| | - Click the (Process) button. You'll get errors and warnings (if any) in one frame, and the processed spec in the other. |
| | - Save the page (e.g. in Firefox, choose the "Save Page as..." menu item from the "File" menu, be sure to choose "Web page, HTML only" from the "Save as" popup), name the file ''Overview.html'' (without the quotes), and save it right next your ''Overview.bs'' - you'll likely be replacing an older version, that's ok, go ahead and confirm (command-R in the replace dialog). |
| | |
| | ===== Troubleshooting ===== |
| ==== requires metadata ==== | ==== requires metadata ==== |
| If you get an error: | If you get an error: |
