Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    The Phantom Derpstorm
    @ThePhD
    It is a warning, and a lot of times I can ignore it, but I don't really get any hint as to what I'm doing to trigger this.
    Tab Atkins Jr.
    @tabatkins
    @ThePhD Ah, yes, that message. It's an error surfacing from the html parser I'm using, and it gives no information and is very annoying, sigh. What it means is that you've fed it invalid HTML, usually either a missing quote on your attribute value or a missing > on a tag, so now it's trying to parse random content as a tagname or attribute name and failing. Finding the error is often hard, tho.
    Tab Atkins Jr.
    @tabatkins
    Only way I've found so far to get more info is to locally patch the _hatexml.py file named there. Find the two instances of "Coercing non-XML name", and add a + name to the string so it'll actually print out the thing it's complaining about.
    Then just look for whatever it talks about in your file.
    One thing to note that sometimes causes this is Bikeshed's support for markdown blockquotes, which is instigated by starting a line with >. If you're the sort of person that linebreaks the inside of the HTML tags when they're long, then you might put the closing > on its own line, and inadvertently trigger that; now the tag you meant to close isn't closed and you have a problem.
    The Phantom Derpstorm
    @ThePhD
    @tabatkins The + name hint helped quite a bit: it seems like when I have Blah<Foo>, the entities in the < and > need to be XML-escaped, even though it's just "text" that goes into the document. So in my case, I had blah<c++>, so I could either escape the contents or do blah&gt;c++&lt; or individually escape the ++'s. I chose the former for some, the latter for others, and they both worked out.
    Tab Atkins Jr.
    @tabatkins
    If you use markdown code blocks/spans, you don't have to escape anything 😀
    Or the <xmp> element, which is similar to a markdown block (don't need to escape anything unless it looks like </xmp>,) and will become a <pre> in your output.
    (It's an actual deprecated HTML element that's still required to be supported by parsers.)
    Sander Saares
    @sandersaares
    Hi! We are considering migrating a large Word document over to Bikeshed format. One concern is that this will result in a giant .bs file that will be hard to navigate in and to edit in web based textbox editors (e.g. GitHub inline editor). Can we split the doc up by chapters and then merge at build time? I looked in the docs for some #include feature or something similar but was unable to find one. Is there a feature in Bikeshed that can help us?
    Sander Saares
    @sandersaares
    Oh I think I see the answer to my question above with a Jun 19 date!
    Sander Saares
    @sandersaares
    But the Web API does not appear to support supplying any files to be included at build time. Is that right?
    Sander Saares
    @sandersaares
    Well, I was unable to get a local install working to try it out (tabatkins/bikeshed#1352) so I request that multiple file support be added to the hosted compiler I can invoke via curl (https://github.com/tabatkins/bikeshed/issues/1353)
    Tab Atkins Jr.
    @tabatkins
    Heya @sandersaares. Thanks for the issue. Yeah, there's no multi-file support in the online version yet.
    How large is the Word file you're currently writing, in pages?
    Sander Saares
    @sandersaares
    234 pages
    Tab Atkins Jr.
    @tabatkins
    Okay, so at least that's probably similar or smaller to the DOM spec, which is about 10k source lines or approximately 400 pages. ^_^
    Sander Saares
    @sandersaares
    I am glad to hear that we are not out of the comfort zone :)
    Sander Saares
    @sandersaares

    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!

    Tab Atkins Jr.
    @tabatkins
    @sandersaares Ooh, ok. That's useful information. In that case, maybe you don't want to be using the web service at all; it would probably be even better to just run Bikeshed on Travis (or your CI of choice)? Check out https://github.com/rtoy/auto-deploy-spec (which is linked from Bikeshed's docs) for thoro details on how to set that up, so you don't have to worry about running it yourself.
    In particular, since that guide sets you up to run Bikeshed on the CI server, it automatically handles everything that a "local" Bikeshed installation would do, including multiple files.
    Sander Saares
    @sandersaares
    Yeah, I considered doing something like that but the sticking point was that I would still like to enable contributors to do the building locally if they wish. Given that I was even unable to make a local install work right on my PC out of the box, I felt like the web service was the only practical way to ensure that contributors can perform a build locally.
    Sander Saares
    @sandersaares

    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.

    Tab Atkins Jr.
    @tabatkins
    Hm, interesting. Did the contributor follow the exact instructions in the docs? I can affirm that the Linux instructions work precisely as advertised, as I've done them several times; other people have contributed and followed the Mac/Windows instructions and successfully installed it.
    Most of the time when people have run into problems installing, it's because they're trying to do something that makes sense to them, rather than just following the actual instructions.
    (The reason I'm trying to find other solutions for you is that the web service isn't maintained by me; it's a completely separate project by @plinss.)
    Sander Saares
    @sandersaares
    I know that he was trying to install it on Windows. However, he did not share with me the details of the issue he was facing (at least he has not responded to my questions so far).
    Sander Saares
    @sandersaares
    How do specref updates get distributed to Bikeshed? An entry was added an hour or two ago. The W3C build service currently does not recognize it. What should my expectations be with regard to specref updates in this aspect?
    Tab Atkins Jr.
    @tabatkins
    The bikeshed-data project runs every 10 minutes, polling all of its data sources for updates. (You can check https://github.com/tabatkins/bikeshed-data/commits/master to see what's been picked up.) I'm unsure of exactly how often the online Bikeshed widget updates its data files.
    (I suspect this commit tabatkins/bikeshed-data@cfd18b3, from 6 hours ago, is the one you're talking about.)
    Sander Saares
    @sandersaares
    Yeah. Looks like it is available now, so whatever the update interval of the online service is, it seems to be less than 24 hours.
    Nicolas Rouquette
    @NicolasRouquette
    I am using bikeshed with our internal github enterprise repository. To enable github issue repository support in bikeshed, I made a small patch to parse https://github.<namespace>/<user-org>/<name> here: tabatkins/bikeshed#1421
    Tab Atkins Jr.
    @tabatkins
    Nice, merged. Didn't even know that was possible!
    Nicolas Rouquette
    @NicolasRouquette

    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?

    Nicolas Rouquette
    @NicolasRouquette

    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.

    Nicolas Rouquette
    @NicolasRouquette
    @tabatkins I needed a Bikeshed docker image to run Bikeshed in CI. There was an issue about this: tabatkins/bikeshed#1354 I proposed a PR w/ a Dockerfile and documentation about this here: tabatkins/bikeshed#1428
    Tab Atkins Jr.
    @tabatkins
    @NicolasRouquette Whoops, I missed these messages when I fell behind on email! Sorry about that.
    Nicolas Rouquette
    @NicolasRouquette
    @tabatkins Ok; there is still the PR for 'include-svg' for you to review: tabatkins/bikeshed#1427
    Now that we can build a docker image for bikeshed, are you going to publish an official image somewhere?
    Yuvraj Manral
    @yuvraaaj
    Hello everyone,
    I am Yuvraj, Computer Engineering sophomore. Would like to contribute to bikeshed.
    I've also went through the project proposal for GSoC 2020, which aims to write Python codebase of bikeshed into Rust.
    Would love to proceed with this task.
    Gunwant Jain
    @WantGuns
    Hello!
    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.
    Uday Mewada
    @udaymewada
    Hello everyone,
    Uday Mewada
    @udaymewada
    I have cloned the bikeshed repo from GitHub. Is it necessary to install docker for contributing in bikeshed
    David Turner
    @dturnerx
    I hope this is the right place to post help questions. I'm getting inconsistent behavior with my 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?
    Tab Atkins Jr.
    @tabatkins
    Hm, the boilerplate files are included based solely on the Group and Status metadata. Can you point to some examples that don't work?
    David Turner
    @dturnerx
    I thought it was that simple. I'll double-check (again!). I can't point you to examples because they're in private repos (for the FIDO Alliance).
    David Turner
    @dturnerx
    Yeah. There's something funky in my build process. Local build does it right. Auto build doesn't. Grr.