Spec authoring tools

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Spec authoring tools

Tobie Langel-3
Hi all,

I'm currently doing some work that involves parsing specs to gather some of their content.

Given that there's pretty much no standard for how specs are structured, I'm mostly forced to branch per spec authoring tool.

Right now, I've identified Respec (drafts and rendered), Bikeshed and Anolis. Am I missing any?

Thanks for your help.

--tobie
Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tab Atkins Jr.
On Fri, Dec 12, 2014 at 8:14 AM, Tobie Langel <[hidden email]> wrote:
> I'm currently doing some work that involves parsing specs to gather some of
> their content.
>
> Given that there's pretty much no standard for how specs are structured, I'm
> mostly forced to branch per spec authoring tool.
>
> Right now, I've identified Respec (drafts and rendered), Bikeshed and
> Anolis. Am I missing any?

There's still one or two CSS specs generated from the old CSSWG
preprocessor, but Bikeshed is basically a superset over it, so if you
can parse Bikeshed you'll be fine.

There's also Hixie's custom pipeline for HTML, and the SVGWG processor
which is entirely distinct.

I recommend talking to plinss, as he's already done a lot of the
compat work necessary to parse different types of specs.

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Robin Berjon-6
In reply to this post by Tobie Langel-3
Hi,

On 12/12/2014 17:14 , Tobie Langel wrote:
> I'm currently doing some work that involves parsing specs to gather some
> of their content.
>
> Given that there's pretty much no standard for how specs are structured,
> I'm mostly forced to branch per spec authoring tool.
>
> Right now, I've identified Respec (drafts and rendered), Bikeshed and
> Anolis. Am I missing any?

In addition to those that Tab mentioned there's also XMLSpec. It's still
used a fair bit, but if you're sticking to "Web" specs you should be in
the clear.

Then there are crazy people like Web Driver who handcraft their specs.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

David Carlisle
In reply to this post by Tobie Langel-3
On 12/12/2014 16:14, Tobie Langel wrote:

> Hi all,
>
> I'm currently doing some work that involves parsing specs to gather some
> of their content.
>
> Given that there's pretty much no standard for how specs are structured,
> I'm mostly forced to branch per spec authoring tool.
>
> Right now, I've identified Respec (drafts and rendered), Bikeshed and
> Anolis. Am I missing any?
>
> Thanks for your help.
>
> --tobie

xmlspec (and variants) is used for several specs,

mathml, xslt, xquery, xpath, and probably some more I don't know about.

David


Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tobie Langel-3
In reply to this post by Tab Atkins Jr.
On Fri, Dec 12, 2014 at 5:23 PM, Tab Atkins Jr. <[hidden email]> wrote:
There's still one or two CSS specs generated from the old CSSWG
preprocessor, but Bikeshed is basically a superset over it, so if you
can parse Bikeshed you'll be fine.

Thanks. Would the CSS 2.1 spec be a good example of the output of that previous preprocessor? 

There's also Hixie's custom pipeline for HTML, and the SVGWG processor
which is entirely distinct.

Darn. I'll look at both. Thanks.

I recommend talking to plinss, as he's already done a lot of the
compat work necessary to parse different types of specs.

Had a while back. Will do again.
Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tobie Langel-3
In reply to this post by David Carlisle

On Fri, Dec 12, 2014 at 5:58 PM, David Carlisle <[hidden email]> wrote:
xmlspec (and variants) is used for several specs,

mathml, xslt, xquery, xpath, and probably some more I don't know about.

Would XPath 3.0[1] be a good example of the output of that authoring tool?

--tobie

---
Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

David Carlisle
On 12/12/2014 18:40, Tobie Langel wrote:
> Would XPath 3.0[1] be a good example of the output of that authoring tool?

well personally I prefer MathML 3 [1]:-)

I'm not on the XSLT WG so I don't know how far they have customised
xmlspec or whether it's now so different as to be not xmlspec at all.
MathML is more or less recognisable xmlspec (although we forked it back
before XSLT 1 was a REC) xml entities [2] is more or less vanilla
xmlspec without any additions (as it is such a simple document)

In addition I just saw a transition request today for xproc
which apparently uses docbook+xslt rather than xmlspec+xslt
the draft says <meta name="generator" content="DocBook XSL 2.0
Stylesheets V2.0.7" /> (not sure the URL for that is public but you can
find it:-)


David


[1] http://www.w3.org/TR/MathML3/
[2] http://www.w3.org/TR/xml-entity-names/








Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tobie Langel-3
On Fri, Dec 12, 2014 at 10:04 PM, David Carlisle <[hidden email]> wrote:
On 12/12/2014 18:40, Tobie Langel wrote:
Would XPath 3.0[1] be a good example of the output of that authoring tool?
well personally I prefer MathML 3 [1]:-)

Which uses concatenated &nbsp; entities to mimic nested content in the ToC. #sadpanda

OK, so I probably won't be supporting those for now. :(

--tobie




Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

David Carlisle
On 12/12/2014 21:14, Tobie Langel wrote:
> Which uses concatenated &nbsp; entities to mimic nested content in
> the ToC. #sadpanda

yes I should probably have changed that this time round.
when we tried originally couldn't get anything that worked well enough
(but that was probably ie4 and netscape 4, it goes back a while:-)

the editors draft is public of course, if (when you're done) there is a
spec for the rules the html version should follow, we/I can easily fit
just as the current html output is designed to fit pubrules.

Scraping structure from generated html when that's generated from well
structured XML seems backwards, but I know that's the world we live in
so if there is a spec for the required structure can generate that.
Can't do much about the documents already in TR of course.

David







Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tobie Langel-3
On Fri, Dec 12, 2014 at 10:22 PM, David Carlisle <[hidden email]> wrote:
On 12/12/2014 21:14, Tobie Langel wrote:
Which uses concatenated &nbsp; entities to mimic nested content in
the ToC. #sadpanda

yes I should probably have changed that this time round.
when we tried originally couldn't get anything that worked well enough
(but that was probably ie4 and netscape 4, it goes back a while:-)

 Heh.

the editors draft is public of course, if (when you're done) there is a
spec for the rules the html version should follow, we/I can easily fit
just as the current html output is designed to fit pubrules.

That would be grand.

The other option would be to simply add support for it in the tools themselves, once they're published.

Scraping structure from generated html when that's generated from well
structured XML seems backwards, but I know that's the world we live in

Heh. Is the src code even available online?
 
so if there is a spec for the required structure can generate that.

I don't think there'll be a spec per se, but at least a list of requirements and tests to pass.
 
Can't do much about the documents already in TR of course.

Which is why adding support in the toolset might end up being a more productive route.

Thanks,

--tobie
Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tab Atkins Jr.
In reply to this post by Tobie Langel-3
On Fri, Dec 12, 2014 at 10:32 AM, Tobie Langel <[hidden email]> wrote:
> On Fri, Dec 12, 2014 at 5:23 PM, Tab Atkins Jr. <[hidden email]>
> wrote:
>> There's still one or two CSS specs generated from the old CSSWG
>> preprocessor, but Bikeshed is basically a superset over it, so if you
>> can parse Bikeshed you'll be fine.
>
> Thanks. Would the CSS 2.1 spec be a good example of the output of that
> previous preprocessor?

No, CSS 2.1 was done with something else entirely.  The Fonts spec is
still on the old processor for now.

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

fantasai
In reply to this post by Tobie Langel-3
On 12/12/2014 10:32 AM, Tobie Langel wrote:
> On Fri, Dec 12, 2014 at 5:23 PM, Tab Atkins Jr. <[hidden email] <mailto:[hidden email]>> wrote:
>
> > There's still one or two CSS specs generated from the old CSSWG
> > preprocessor, but Bikeshed is basically a superset over it, so if you
> > can parse Bikeshed you'll be fine.
>
>
> Thanks. Would the CSS 2.1 spec be a good example of the output of that previous preprocessor?

No, but CSS3 Backgrounds and Borders is, IIRC, still on that preprocessor.
(Note, I expect that to change in the next round of publication or so. But
that's why we have dated snapshots on /TR.)

CSS2.1 is generated using Yet Another Custom Preprocessor. I think it is
specific to CSS2.1.

Wondering why aren't you just using plinss's Shepherd code?

~fantasai

Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tobie Langel-3
On Sat, Dec 13, 2014 at 7:06 PM, fantasai <[hidden email]> wrote:
On 12/12/2014 10:32 AM, Tobie Langel wrote:
On Fri, Dec 12, 2014 at 5:23 PM, Tab Atkins Jr. <[hidden email] <mailto:[hidden email]>> wrote:

> There's still one or two CSS specs generated from the old CSSWG
> preprocessor, but Bikeshed is basically a superset over it, so if you
> can parse Bikeshed you'll be fine.


Thanks. Would the CSS 2.1 spec be a good example of the output of that previous preprocessor?

No, but CSS3 Backgrounds and Borders is, IIRC, still on that preprocessor.
(Note, I expect that to change in the next round of publication or so. But
that's why we have dated snapshots on /TR.)

OK, thanks. 

CSS2.1 is generated using Yet Another Custom Preprocessor. I think it is
specific to CSS2.1.

Sounds fun! :-/

Wondering why aren't you just using plinss's Shepherd code?

We're talking about the specificationparser python module[1] found in the specification Hg repo, right?

I looked at it again this morning. From reading through the code, and looking at sample output from the CSSWG API[2], it doesn't seem to be meeting my needs; I'm currently looking at:

- listing normative references,
- listing links to external DFNs,
- listing DFNs,
- linking WebIDL internals to their respective sections.

I also happen to need a solution that supports a large number of authoring tools, including ReSpec drafts (which are generated on the fly and which require a JS-aware parser). I'm not sure specificationparser supports that (couldn't find any tests for it outside of the live code which focuses on CSS specs).

Finally, I also need a tool that's easy for me to contribute to and that welcomes external contributions. specificationparser uses Python, a language I'm not fluent in, a different versioning system than what I use for the rest of the project, and doesn't have any testing framework setup. There are deterrents, tbh. The fact it's not on GitHub also makes it harder for third party contributions which I'd like to encourage (to support other spec formats, e.g. some accessibility specs, the WebDriver spec which doesn't use any authoring tool, etc.).

All in all, it doesn't seem like the best option at present. 

--tobie

---
Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Marcos Caceres-4
In reply to this post by Robin Berjon-6



On December 13, 2014 at 2:36:53 AM, Robin Berjon ([hidden email]) wrote:
> > In addition to those that Tab mentioned there's also XMLSpec.  
> It's still
> used a fair bit, but if you're sticking to "Web" specs you should  
> be in the clear.

I think WebIDL uses this :)  

Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Robin Berjon-6
On 15/12/2014 01:25 , Marcos Caceres wrote:
> On December 13, 2014 at 2:36:53 AM, Robin Berjon ([hidden email]) wrote:
>>> In addition to those that Tab mentioned there's also XMLSpec.
>> It's still
>> used a fair bit, but if you're sticking to "Web" specs you should
>> be in the clear.
>
> I think WebIDL uses this :)

Hahaha. No.

WebIDL, unless I am mistaken, uses its own weird homegrown XSLT 1.0
processor that converts a format that is 95% XHTML with some extra XML
stuff. In that way it is a fair bit like the ancestral version of ReSpec:

http://dev.w3.org/2006/webapi/ReSpec/

:)

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Tobie Langel-3


On Mon, Dec 15, 2014 at 11:44 AM, Robin Berjon <[hidden email]> wrote:
On 15/12/2014 01:25 , Marcos Caceres wrote:
On December 13, 2014 at 2:36:53 AM, Robin Berjon ([hidden email]) wrote:
In addition to those that Tab mentioned there's also XMLSpec.
It's still
used a fair bit, but if you're sticking to "Web" specs you should
be in the clear.

I think WebIDL uses this :)

Hahaha. No.

WebIDL, unless I am mistaken, uses its own weird homegrown XSLT 1.0 processor that converts a format that is 95% XHTML with some extra XML stuff. In that way it is a fair bit like the ancestral version of ReSpec:

That's it. I give up. 
Reply | Threaded
Open this post in threaded view
|

Re: Spec authoring tools

Robin Berjon-6
On 15/12/2014 11:49 , Tobie Langel wrote:
>     WebIDL, unless I am mistaken, uses its own weird homegrown XSLT 1.0
>     processor that converts a format that is 95% XHTML with some extra
>     XML stuff. In that way it is a fair bit like the ancestral version
>     of ReSpec:
>
> That's it. I give up.

Nah, c'mon, don't give up. The outputs aren't that different, and I'm
sure we can get fixes in Cam's generator if it helps.

--
Robin Berjon - http://berjon.com/ - @robinberjon