speced / bikeshed Goto Github PK

I've hit several bugs from dfnTypes not including "dfn" by default. See what the usages of dfnTypes are, and whether it'll be more correct in general to make dfnTypes contain "dfn" or not.

Sometimes you want multiple paras in your abstract. Currently you have to do somewhat hacky markup in the single Abstract line you're allowed.

Bikeshed should allow multiple Abstract lines, with each creating a separate paragraph.

Bikeshed will auto-gen an id for your headings, but this often isn't very good (it can get long and confusing), and it's not stable across changes to the heading text. I should probably add a warning whenever I autogen an id for them, to discourage the practice.

The section "Status of this document" has bogus links. The links are relative instead of absolute, causing problems as an ED.

I believe this is a related issue to issue #47 .

If the "Values" sections have links, the text is not used in the "Miscellaneous Descriptors" table.

Linking to issues is annoying. Auto-add ids to issues, and a permalink icon like headings get.

Though, we preferably want the ids to be stable, so that linking to an issue doesn't go stale as soon as you add/remove an issue preceding it. Hmm. Maybe hash the contents with something simple?

Even bikeshed update does not create the full list of HTML elements for reference. So far it just seems to be video, audio, canvas, script and meta.

Note that this might not be an issue with bike shed. Opening an issue anyway for reference.

Some time it happens that I capitalize wrong, like Previous version: instead of Previous Version: or name: instead of Name:.

Also, there is some inconsistency. It is Computed value: instead of Computed Value:.

Would it be possible to make these keywords case insensitive?

For CSS Masking I have an element and an property with the same name: mask. (Affects Filter Effects too with filter).

For the property I use the <pre class='propdef'>, the element is an auto generated table which looks quite similar to a property definition table.

I modified the SVG preprocessor to use <dfn element>mask</dfn> and let Bikeshed handle the auto linking as described in the documentation. The resulting document looks like:

<table class=propdef summary="mask element">
  <tr>
    <th>Name:</th>
    <td><dfn element>mask</dfn>
  </tr>

However, Bikeshed seems to ignore the hint and still produces:

<dfn class="css-code" data-dfn-type="property" data-export="" id="propdef-mask">mask<a class="self-link" href="#propdef-mask"></a></dfn>

and still throws:

FATAL ERROR: Multiple local 'property' <dfn>s have the same linking text 'mask'.

Some propdef values are really complicated, but right now you have to put them on a single line. You should be able to specify Value: multiple times, and have bikeshed glom them together.

Putting in duplicate propdef blocks doesn't trigger any errors. It should.

This should be just a regex like s/([\w>])'(s|t)/\1’\2/

Some properties are defined in both SVG and newer CSS specs, and the CSS definitions are the ones that should win out. Should I just make those specs replace SVG?

Alternately, just add those terms to autolink defaults as they come up.

Running bikeshed give the issue from the title. setup.py does not have as requirement widlparser.

I assume I need to install https://github.com/plinss/widlparser ?

I have the following meta code for the property 'transform'

<pre class='propdef'>
Name: transform
Value: none | <<transform-list>>
Initial: none
Applies to: <i>transformable elements</i>
Inherited: no
Percentages: refer to the size of <i>bounding box</i>
Computed value: As specified, but with relative lengths converted into absolute lengths.
Media: visual
Animatable: as <a href="#interpolation-of-transforms">transform</a>
</pre>

Which results in nonsense in the following nonsense in the property index table:

none | <a data-link-type="type" class="production" title="&lt;transform-list&gt;" href="#typedef-transform-list">&lt;transform-list&gt;</a>

W3C pubrules require a "Latest Version" link in the metadata, before previous versions links. Bikeshed should generate this automatically, or let editors insert it at the correct position. Currently, a manually-specified link ends up at the end of the table.

I get the following mistake:

FATAL ERROR: Couldn't find 'GLSLES' in bibliography data.
FATAL ERROR: Couldn't find 'WEBGL' in bibliography data.
Traceback (most recent call last):
  File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 1613, in <module>
    main()
  File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 90, in main
    config.doc.preprocess()
  File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 1205, in preprocess
    processAutolinks(self)
  File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 900, in processAutolinks
    classifyLink(el)
  File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 861, in classifyLink
    if linkType == "maybe" and re.match(r"([\w-/]+)/([\w-]+)", linkText):
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/re.py", line 137, in match
    return _compile(pattern, flags).match(string)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/re.py", line 244, in _compile
    raise error, v # invalid expression
sre_constants.error: bad character range

Both, GLSLES and WEBGL are references normatively in the spec: [[!WEBGL]] and [[!GLSLES]].

Maybe make use of data-link-spec look for unexported things? (The main problem with non-exported things is that there are a lot of conflicts, but having a single spec helps with that.)

Or just add a data-link-force attribute (written force or link-force) which forces you it to include non-exported things.

Right now bikeshed requires you to end function/method definitions with "()", so that links to "foo()" will grab it properly. That means you can't easily have <dfn function>foo(bar)</dfn> - you have to mark it with an explicit title="foo()" to get bikeshed to accept it.

Similarly, examples like ''foo(bar)'' don't autolink to "foo()", because the linking text isn't recognized.

Bikeshed should instead verify that methods/functions have a linking text of /^[\w-]+\(.*\)$/, and fill in a title with "foo()" if necessary, for both dfns and autolinks.

<dfn title="foo()">foo(bar)</dfn> will generate an id of "functiondef-foobar".

It should recognize it's a function, and just generate the id off of that, producing "functiondef-foo".

Bikeshed does not support ordered or unordered (and nested) markdown list

Following output on some properties:

WARNING: Multiple possible 'propdesc' refs for 'filter'.
Arbitrarily chose the one in filters-1.
If this is wrong, insert one of the following lines into 'Link Defaults':
    filters-1 (property) filter
    filters-1 (property) filter

Note that the strings are duplicated. I assume that there is something wrong with the property definition in the anchor data. But hopefully the referencing spec does not get a warning because of a mistake in another spec.

PS: I didn't check what or if there is a mistake in Filter Effects yet. But it happens with other properties as well.

Bikeshed seems to add <a> elements inside <a> elements for self-links, which the validator does not like.

Allow "Issue List" as meta data at the beginning which takes a link to the filed bug reports.

It would be great if I could choose between different WGs and TFs. I would be interested in SVG WG and FXTF specifically.

The tweaks do of course affect the public mailing list address and the status of document text as well.

The Markup document says:

• <i> elements are treated as autolinks as well, for legacy reasons.
• 'foo' (apostophes/straight quotes) is an autolink to a property or descriptor named "foo"

So assume if I have mask source then I should be able to reference it with 'mask source'. But doesn't work.

Also, what about <var> and <span>? Bert's pre-processor takes them as auto links as well if it finds a <dfn> for that. It is used in some specs. For span often with <span class="term">

Bert's preprocessor allowed a "foo!!bar" syntax in titles, which affected Index generation. I forget which is supposed to be the main term and which is the sub-term - I'll have to look that up.

I got this error when running the preprocessor. Removing encoding="utf8", in calls to html5lib.parse() "solved" it, but I have no idea if that was the right thing to do. The whole code could probably use a pass of looking at what’s supposed to by bytes and what’s supposed to be Unicode ;)

Traceback (most recent call last):
  File "/home/simon/.local/bin/css-preprocess", line 9, in <module>
    load_entry_point('css-preprocessor==0.0.0', 'console_scripts', 'css-preprocess')()
  File "/home/simon/projects/css/css-preprocessor/preprocess.py", line 67, in main
    doc.preprocess()
  File "/home/simon/projects/css/css-preprocessor/preprocess.py", line 986, in preprocess
    self.document = parseDocument(self.html)
  File "/home/simon/projects/css/css-preprocessor/preprocess.py", line 124, in parseDocument
    doc = html5lib.parse(str, treebuilder='lxml', encoding='utf-8', namespaceHTMLElements=False)
  File "/home/simon/.virtualenvs/css-preprocessor/lib/python2.7/site-packages/html5lib/html5parser.py", line 28, in parse
    return p.parse(doc, encoding=encoding)
  File "/home/simon/.virtualenvs/css-preprocessor/lib/python2.7/site-packages/html5lib/html5parser.py", line 224, in parse
    parseMeta=parseMeta, useChardet=useChardet)
  File "/home/simon/.virtualenvs/css-preprocessor/lib/python2.7/site-packages/html5lib/html5parser.py", line 88, in _parse
    parser=self, **kwargs)
  File "/home/simon/.virtualenvs/css-preprocessor/lib/python2.7/site-packages/html5lib/tokenizer.py", line 40, in __init__
    self.stream = HTMLInputStream(stream, encoding, parseMeta, useChardet)
  File "/home/simon/.virtualenvs/css-preprocessor/lib/python2.7/site-packages/html5lib/inputstream.py", line 128, in HTMLInputStream
    raise TypeError("Cannot explicitly set an encoding with a unicode string")
TypeError: Cannot explicitly set an encoding with a unicode string

223bc23 broke my bikeshed:

Traceback (most recent call last):
  File "/home/simon/.local/bin/bikeshed", line 9, in <module>
    load_entry_point('Bikeshed==0.0.0', 'console_scripts', 'bikeshed')()
  File "/home/simon/.virtualenvs/bikeshed/lib/python2.7/site-packages/bikeshed/__init__.py", line 90, in main
    config.doc.preprocess()
  File "/home/simon/.virtualenvs/bikeshed/lib/python2.7/site-packages/bikeshed/__init__.py", line 1205, in preprocess
    processAutolinks(self)
  File "/home/simon/.virtualenvs/bikeshed/lib/python2.7/site-packages/bikeshed/__init__.py", line 900, in processAutolinks
    classifyLink(el)
  File "/home/simon/.virtualenvs/bikeshed/lib/python2.7/site-packages/bikeshed/__init__.py", line 861, in classifyLink
    if linkType == "maybe" and re.match(r"([\w-/]+)/([\w-]+)", linkText):
  File "/home/simon/.virtualenvs/bikeshed/lib/python2.7/re.py", line 137, in match
    return _compile(pattern, flags).match(string)
  File "/home/simon/.virtualenvs/bikeshed/lib/python2.7/re.py", line 242, in _compile
    raise error, v # invalid expression
sre_constants.error: bad character range

I’m using Python 2.7.5.

Properties are occasionally extended in new specs. Rather than the two definitions conflicting, it would be great if there was some way to detect that a given propdef table was a "partial" table, augmenting an existing definition, so that a ref wouldn't produce conflicts.

This requires some data-model thought.

If you have multiple keyword or value definitions, the auto linking doesn't work so well anymore. Instead of just ''auto'' you now have to type <a value for='property'>auto</a>.

Could that be simplified to just ''property/auto''?

Right now autolink defaults just controls how you interpret the links coming from Shepherd. We should have some way to add additional links. Maybe just copy what Anolis does, so people can drop their refs directly into spec-data/?

I constantly get a FATAL ERROR: No 'idl' refs found for ... for IDL definitions I wrote my self. There is nothing wrong with the definition. Bikeshed should just ignore them.

How can I flag a section to be ignored?

The "Applies To" column is added twice to the Property index table. Just the second "Applies To" column seems to have data.

Miscellaneous Descriptors table does not get an id. I get the warning:

WARNING: You should manually provide IDs for your headings:
  <h3 class="no-num heading" id="miscellaneous-descriptors"><span class="content">Miscellaneous Descriptors</span></h3>

Right now propdef parsing will crash bikeshed if you violate its expectations. I need to be more defensive in it, and give good error messages.

I assume that is one of the problems with the member access to the original biblio.refer file?

However, biblio.refer is not updated with the command:

bikeshed.py update

Fatal errors normally stop the spec generation, but --debug makes it continue. This is useful when you need to publish something now, but have some errors that Bikeshed doesn't like. Using it like this, though, requires that every die() location gracefully continues by skipping whatever it hit an error with.

I know that many/most of the die() locations do this, but I need to thoroughly review all of them to ensure that this is true of every location.

I have the following code:

<li>'filter'

'filter' is not recognized until I add a space between tag and property reference.

If you run into local conflicts where there are multiple definitions of a term in different types, but your link is a wide type (like "maybe"), the error message talks about specifying the for attribute, rather than talking about the type.

The error message should inspect the list of available local refs, and see whether it's something to be solved by narrowing the type or narrowing the for.

What is a good way to add own normative or informative references? Some may not need to go into a global reference list, or the modification takes too long.

It seems that there is no way to take a source file with a name other than Overview.src.html. Furthermore, the output file name can not be specified. To chain bikeshed.py with other tools it would be useful to have these opportunities.

Right now all of the values but none of the properties are being added to the regular index, which isn't that useful. Since bikeshed should know which values belong to which property, the property could be added to the index with each of its values as a sub-item. So instead of this (from flexbox)

<number> (value), 7.3.1
<number> (value), 7.3.2

you'd get

flex-shrink, 7.3.1
   <number> (value), 7.3.1
flex-basis, 7.3.2
   <number> (value), 7.3.2

The word "editors'" has a foot-mark instead of a curly apostrophe

For CSS Masking I am using a lot of definitions from CSS Background and Borders, Filter Effects and CSS Transforms that are not opt-in for external access yet and won't be for a long time until we publish new WDs (and the editors agree to add this extra markup). Could we instead opt-out definitions for external access?
I am not sure how often editors surround text with , , without actually referring to exactly this definition.

If I run bikeshed on an unprepared spec I get the following (in this case CSS Transforms):

FATAL ERROR: No 'propdesc' refs found for 'linear'.
FATAL ERROR: No 'propdesc' refs found for 'lineargradient'.
FATAL ERROR: No 'propdesc' refs found for 'animate'.
Traceback (most recent call last):
  File "/.../bikeshed.py", line 1702, in <module>
    main()
  File "/.../bikeshed.py", line 103, in main
    config.doc.preprocess()
  File "/.../bikeshed.py", line 1306, in preprocess
    addPropertyIndex(self)
  File "/.../bikeshed.py", line 1486, in addPropertyIndex
    key = re.match(u'(.*):', textContent(row[0])).group(1).strip()
AttributeError: 'NoneType' object has no attribute 'group'

If one uses <pre class='propdef'> twice with the same property name for Name: twice, bikeshed crashes with:

Traceback (most recent call last):
File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 1557, in
main()
File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 103, in main
config.doc.preprocess()
File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 1161, in preprocess
processAutolinks(self)
File "/Users/dschulze/Downloads/bikeshed/bikeshed.py", line 884, in processAutolinks
error=(text not in doc.ignoredTerms))
File "/Users/dschulze/Downloads/bikeshed/lib/ReferenceManager.py", line 116, in getRef
refs[0]['type'],
UnboundLocalError: local variable 'refs' referenced before assignment

Right now that is hard to do because https://www.w3.org/Style/Group/css3-src/biblio.ref is W3C Member-only and password-protected, which it really shouldn’t be.

See https://lists.w3.org/Archives/Member/w3c-css-wg/2013JulSep/0215.html (err... also Member-only, sorry.)

Older code, in order to distinguish local links from cross-spec links, abused the "spec" field of the anchor data. I now properly distinguish this in the "status" field, so I should go back to filling in "spec" properly, so I can provide a good error message when you remove a link from a local spec, but it still exists in the foreign anchor data for your spec.

(That is, if a local link exists, I need to kill any non-local versions of the anchor unreservedly.)

This is a regression since one of the last commits:

<a class='attr-name' href='#MaskElementMaskContentUnitsAttribute'>'maskContentUnits'</a>

This is no longer ignored by Bikeshed and Bikeshed tries to link to 'maskContentUnits'.