Various respec enhancements ...

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

Various respec enhancements ...

Steve Glaser

I thought this audience might be interested in some changes I’ve made to respec. I forked the respec repository a while back to create a flavor that would work for PCISIG Specifications (PCI Express hardware specs).

 

My version has diverged quite a bit from Robin’s version so I haven’t created pull requests, but there are a few features I thought might be interesting to make folks aware of:

 

1.       Register pictures – PCISIG specs are chock full of diagrams of hardware registers. These were being drawn by hand in Illustrator. I added code to respec to automatically draw these figures using a JSON representation and to optionally create that JSON representation from an HTML table elsewhere in the document. For instructions, see http://sglaser.github.io/regpict

2.       Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn> types that were formatted differently by CSS. If you include <dfn class=”field”>foo</dfn>, then any <a>foo</a> fields will automatically get the right class (assuming no ambiguity – if it’s ambiguous, you get a message and have to put the class attribute on the <a> tag).

3.       Automatic subscripts in <dfn>. I remember the innerHTML for each <dfn> and copy it to the <a>. That way if you have <dfn>T<sub>active</sub></dfn> and you reference it as <a>Tactive</a>, you get the <sub> stuff in the expansion..

4.       Enhanced figure numbering. PCISIG figures are numbered within a chapter. If you set the config property “figFmt”, you can alter how they are named and numbered.

5.       Table numbering. Per chapter, like figure numbering but using “tblFmt”.

6.       Table of Tables. Like Table of Figures. If you have <section id=”tot”>, you get one.

7.       Expanded references. If you reference a section, figure, etc. The generated HTML includes the figure/section/table number and the figure/section/table caption. You can use css to hide what you don’t want. This way, print media can have “See Figure 4-2” without having to work hard.

8.       Dump <dfn> table. If you set the addDefinitionMap config propter to true, you get a table at the end of your document with every <dfn> in the document.

9.       Dump section, figure and table names. If you set the addXrefMap config property to true, you get a table at the end of your document with the caption and id values for every section, figure, and table in the document.

 

My fork of respec is http://github.com/sglaser/respec. I’ve pulled Robin’s latest changes in, but as I said earlier, I haven’t submitted any pull requests.

 

An example that uses most of the features above is http://sglaser.github.io/respec/examples/xxx.html (with JavaScript) and http://sglaser.github.io/respec/examples/xxx-snap.html (no JavaScript -- respec snapshot output).

 

Feel free to copy / reuse whatever you find interesting / useful. Same license as respec.

 

Steve Glaser

 

 


This email message is for the sole use of the intended recipient(s) and may contain confidential information.  Any unauthorized review, use, disclosure or distribution is prohibited.  If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message.

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Robin Berjon-6
Hi Steve,

On 25/08/2014 02:56 , Steve Glaser wrote:
> 1.Register pictures – PCISIG specs are chock full of diagrams of
> hardware registers. These were being drawn by hand in Illustrator. I
> added code to respec to automatically draw these figures using a JSON
> representation and to optionally create that JSON representation from an
> HTML table elsewhere in the document. For instructions, see
> http://sglaser.github.io/regpict

That is a very cool feature. However, It's pretty specific and is a
feature that isn't commonly required by Web specs so I'd be hesitant to
see it added to core ReSpec.

Do you know that one can use ReSpec *and* build a new profile in order
to match the needs of a different community? The process is a bit
convoluted, but https://github.com/darobin/respec-docs/ makes use of it.

> 2.Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn>
> types that were formatted differently by CSS. If you include <dfn
> class=”field”>foo</dfn>, then any <a>foo</a> fields will automatically
> get the right class (assuming no ambiguity – if it’s ambiguous, you get
> a message and have to put the class attribute on the <a> tag).

That's cool, and I think it makes sense. One notion that I've thought of
previously is to have dfn-namespacing as well as alternatives.

Namespacing would work basically like this. Say you have a markup
attribute and a DOM attribute both called 'unicorn'. You could have
<dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and
<a>dom:unicorn</a> would link to the right one (and drop the namespace
on render of course). If you need a : in your dfn, \-escaping works.

Alternatives would solve the common problem of referring to the same dfn
with variants (typically, plurals) for which today one has to annoyingly
resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
horse</dfn>.

Of course the two could be mixed.

> 3.Automatic subscripts in <dfn>. I remember the innerHTML for each <dfn>
> and copy it to the <a>. That way if you have
> <dfn>T<sub>active</sub></dfn> and you reference it as <a>Tactive</a>,
> you get the <sub> stuff in the expansion..

Indeed, hadn't thought of that. Good feature.

> 4.Enhanced figure numbering. PCISIG figures are numbered within a
> chapter. If you set the config property “figFmt”, you can alter how they
> are named and numbered.

That's certainly useful.

> 5.Table numbering. Per chapter, like figure numbering but using “tblFmt”.

Ditto. That said, not all tables always need to be numbered. Do you have
a way of disabling that for a given table?

> 6.Table of Tables. Like Table of Figures. If you have <section
> id=”tot”>, you get one.

Again, I can see that being used.

> 7.Expanded references. If you reference a section, figure, etc. The
> generated HTML includes the figure/section/table number and the
> figure/section/table caption. You can use css to hide what you don’t
> want. This way, print media can have “See Figure 4-2” without having to
> work hard.

Didn't we support that already? I thought Frederick had added support
for that (but I may be wrong).

> 8.Dump <dfn> table. If you set the addDefinitionMap config propter to
> true, you get a table at the end of your document with every <dfn> in
> the document.

That's pretty cool! I'd suggest a different syntax though. <section
id="dnf-table"></section> could be found and if present be used to
generate that section. It's how it's done for other similar features.

> 9.Dump section, figure and table names. If you set the addXrefMap config
> property to true, you get a table at the end of your document with the
> caption and id values for every section, figure, and table in the document.

Same as previous.

> My fork of respec is http://github.com/sglaser/respec. I’ve pulled
> Robin’s latest changes in, but as I said earlier, I haven’t submitted
> any pull requests.

Don't hesitate to make PRs! It would be simpler to process these
features individually, but they're cool!

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

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Frederick Hirsch
see inline, but need help finding v1 documentation

regards, Frederick

Frederick Hirsch, Nokia
@fjhirsch



On Sep 16, 2014, at 6:55 AM, Robin Berjon <[hidden email]> wrote:

> Hi Steve,
>
> On 25/08/2014 02:56 , Steve Glaser wrote:
>> 1.Register pictures – PCISIG specs are chock full of diagrams of
>> hardware registers. These were being drawn by hand in Illustrator. I
>> added code to respec to automatically draw these figures using a JSON
>> representation and to optionally create that JSON representation from an
>> HTML table elsewhere in the document. For instructions, see
>> http://sglaser.github.io/regpict
>
> That is a very cool feature. However, It's pretty specific and is a feature that isn't commonly required by Web specs so I'd be hesitant to see it added to core ReSpec.
>
> Do you know that one can use ReSpec *and* build a new profile in order to match the needs of a different community? The process is a bit convoluted, but https://github.com/darobin/respec-docs/ makes use of it.
>
>> 2.Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn>
>> types that were formatted differently by CSS. If you include <dfn
>> class=”field”>foo</dfn>, then any <a>foo</a> fields will automatically
>> get the right class (assuming no ambiguity – if it’s ambiguous, you get
>> a message and have to put the class attribute on the <a> tag).
>
> That's cool, and I think it makes sense. One notion that I've thought of previously is to have dfn-namespacing as well as alternatives.
>
> Namespacing would work basically like this. Say you have a markup attribute and a DOM attribute both called 'unicorn'. You could have <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and <a>dom:unicorn</a> would link to the right one (and drop the namespace on render of course). If you need a : in your dfn, \-escaping works.
>
> Alternatives would solve the common problem of referring to the same dfn with variants (typically, plurals) for which today one has to annoyingly resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed horse</dfn>.
>
> Of course the two could be mixed.
>
>> 3.Automatic subscripts in <dfn>. I remember the innerHTML for each <dfn>
>> and copy it to the <a>. That way if you have
>> <dfn>T<sub>active</sub></dfn> and you reference it as <a>Tactive</a>,
>> you get the <sub> stuff in the expansion..
>
> Indeed, hadn't thought of that. Good feature.
>
>> 4.Enhanced figure numbering. PCISIG figures are numbered within a
>> chapter. If you set the config property “figFmt”, you can alter how they
>> are named and numbered.
>
> That's certainly useful.
>
>> 5.Table numbering. Per chapter, like figure numbering but using “tblFmt”.
>
> Ditto. That said, not all tables always need to be numbered. Do you have a way of disabling that for a given table?
>
>> 6.Table of Tables. Like Table of Figures. If you have <section
>> id=”tot”>, you get one.
>
> Again, I can see that being used.
>
>> 7.Expanded references. If you reference a section, figure, etc. The
>> generated HTML includes the figure/section/table number and the
>> figure/section/table caption. You can use css to hide what you don’t
>> want. This way, print media can have “See Figure 4-2” without having to
>> work hard.
>
> Didn't we support that already? I thought Frederick had added support for that (but I may be wrong).
>

yes i think so, certainly for section references

I  cannot find this in the new user guide or reference and the old documentation seems to be completely gone (v1 docs link to v2 arghh)

maybe I have an offline copy somewhere - Robin do you have a copy of the v1 documentation, I documented everything I did...

however, looking at the source of one of my specs:

section references:

<a href="#signers-separate-keys"
                   class="sectionRef"></a>.

I also did best practices numbering.

not sure about figures thought I did it, if not  it would be similar to sectionRef



>> 8.Dump <dfn> table. If you set the addDefinitionMap config propter to
>> true, you get a table at the end of your document with every <dfn> in
>> the document.
>
> That's pretty cool! I'd suggest a different syntax though. <section id="dnf-table"></section> could be found and if present be used to generate that section. It's how it's done for other similar features.
>
>> 9.Dump section, figure and table names. If you set the addXrefMap config
>> property to true, you get a table at the end of your document with the
>> caption and id values for every section, figure, and table in the document.
>
> Same as previous.
>
>> My fork of respec is http://github.com/sglaser/respec. I’ve pulled
>> Robin’s latest changes in, but as I said earlier, I haven’t submitted
>> any pull requests.
>
> Don't hesitate to make PRs! It would be simpler to process these features individually, but they're cool!
>
> --
> Robin Berjon - http://berjon.com/ - @robinberjon
>


Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Tab Atkins Jr.
In reply to this post by Robin Berjon-6
On Tue, Sep 16, 2014 at 3:55 AM, Robin Berjon <[hidden email]> wrote:

> On 25/08/2014 02:56 , Steve Glaser wrote:
>> 2.Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn>
>> types that were formatted differently by CSS. If you include <dfn
>> class=”field”>foo</dfn>, then any <a>foo</a> fields will automatically
>> get the right class (assuming no ambiguity – if it’s ambiguous, you get
>> a message and have to put the class attribute on the <a> tag).
>
> That's cool, and I think it makes sense. One notion that I've thought of
> previously is to have dfn-namespacing as well as alternatives.
>
> Namespacing would work basically like this. Say you have a markup attribute
> and a DOM attribute both called 'unicorn'. You could have
> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and <a>dom:unicorn</a>
> would link to the right one (and drop the namespace on render of course). If
> you need a : in your dfn, \-escaping works.
>
> Alternatives would solve the common problem of referring to the same dfn
> with variants (typically, plurals) for which today one has to annoyingly
> resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
> horse</dfn>.

We've already solved this problem in Bikeshed/Shepherd, and it would
be a crying shame to have ReSpec try to solve it in an incompatible
way, as it would mean the two types of specs couldn't talk to each
other.

Bikeshed's relevant documention is here:
<https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
We've got a taxonomy of dfn types, which can also be applied to
autolinks to disambiguate.  There are multiple ways to specify what
type a dfn is - an explicit data-dfn-type attribute, an id matching a
particular pattern, a class (on the element or an ancestor) matching a
particular pattern, or the text of the dfn itself matching certain
patterns.  Bikeshed makes this all pretty trivial and turns it
explicit in the source for you, but ReSpec specs obviously would need
to be a little more explicit about things, so that the correct
information shows up in the source html.

I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
I can autolink into ReSpec specs.

>> 3.Automatic subscripts in <dfn>. I remember the innerHTML for each <dfn>
>> and copy it to the <a>. That way if you have
>> <dfn>T<sub>active</sub></dfn> and you reference it as <a>Tactive</a>,
>> you get the <sub> stuff in the expansion..
>
> Indeed, hadn't thought of that. Good feature.

Agreed.  Does this feature *only* cover subscripts/superscripts, or is
there more formatting copied over?

~TJ

Reply | Threaded
Open this post in threaded view
|

RE: Various respec enhancements ...

Steve Glaser


-----Original Message-----
From: Tab Atkins Jr. [mailto:[hidden email]]
Sent: Tuesday, September 16, 2014 11:02 AM
To: Robin Berjon
Cc: Steve Glaser; [hidden email]
Subject: Re: Various respec enhancements ...

On Tue, Sep 16, 2014 at 3:55 AM, Robin Berjon <[hidden email]> wrote:

> On 25/08/2014 02:56 , Steve Glaser wrote:
>> 2.Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn>
>> types that were formatted differently by CSS. If you include <dfn
>> class=”field”>foo</dfn>, then any <a>foo</a> fields will
>> automatically get the right class (assuming no ambiguity – if it’s
>> ambiguous, you get a message and have to put the class attribute on the <a> tag).
>
> That's cool, and I think it makes sense. One notion that I've thought
> of previously is to have dfn-namespacing as well as alternatives.
>
> Namespacing would work basically like this. Say you have a markup
> attribute and a DOM attribute both called 'unicorn'. You could have
> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and
> <a>dom:unicorn</a> would link to the right one (and drop the namespace
> on render of course). If you need a : in your dfn, \-escaping works.
>
> Alternatives would solve the common problem of referring to the same
> dfn with variants (typically, plurals) for which today one has to
> annoyingly resort to @title. For that, just use
> <dfn>unicorn|unicorns|long-toothed
> horse</dfn>.

We've already solved this problem in Bikeshed/Shepherd, and it would be a crying shame to have ReSpec try to solve it in an incompatible way, as it would mean the two types of specs couldn't talk to each other.

Bikeshed's relevant documention is here:
<https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
We've got a taxonomy of dfn types, which can also be applied to autolinks to disambiguate.  There are multiple ways to specify what type a dfn is - an explicit data-dfn-type attribute, an id matching a particular pattern, a class (on the element or an ancestor) matching a particular pattern, or the text of the dfn itself matching certain patterns.  Bikeshed makes this all pretty trivial and turns it explicit in the source for you, but ReSpec specs obviously would need to be a little more explicit about things, so that the correct information shows up in the source html.

I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that I can autolink into ReSpec specs.

[Steve Glaser] I did it with different classes as that tied in to my desire to use different css formatting. I'm not wedded to that approach though and I agree the singular / plural issue is a pain. Any solution should play nicely with the automatic subscripts stuff (next item).

>> 3.Automatic subscripts in <dfn>. I remember the innerHTML for each
>> <dfn> and copy it to the <a>. That way if you have
>> <dfn>T<sub>active</sub></dfn> and you reference it as <a>Tactive</a>,
>> you get the <sub> stuff in the expansion..
>
> Indeed, hadn't thought of that. Good feature.

Agreed.  Does this feature *only* cover subscripts/superscripts, or is there more formatting copied over?

[Steve Glaser] I copy the entire innerHTML over. You can use anything you want.

~TJ

-----------------------------------------------------------------------------------
This email message is for the sole use of the intended recipient(s) and may contain
confidential information.  Any unauthorized review, use, disclosure or distribution
is prohibited.  If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.
-----------------------------------------------------------------------------------
Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Tobie Langel-3
In reply to this post by Tab Atkins Jr.
On Tue, Sep 16, 2014 at 8:01 PM, Tab Atkins Jr. <[hidden email]> wrote:
On Tue, Sep 16, 2014 at 3:55 AM, Robin Berjon <[hidden email]> wrote:
> On 25/08/2014 02:56 , Steve Glaser wrote:
>> 2.Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn>
>> types that were formatted differently by CSS. If you include <dfn
>> class=”field”>foo</dfn>, then any <a>foo</a> fields will automatically
>> get the right class (assuming no ambiguity – if it’s ambiguous, you get
>> a message and have to put the class attribute on the <a> tag).
>
> That's cool, and I think it makes sense. One notion that I've thought of
> previously is to have dfn-namespacing as well as alternatives.
>
> Namespacing would work basically like this. Say you have a markup attribute
> and a DOM attribute both called 'unicorn'. You could have
> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and <a>dom:unicorn</a>
> would link to the right one (and drop the namespace on render of course). If
> you need a : in your dfn, \-escaping works.
>
> Alternatives would solve the common problem of referring to the same dfn
> with variants (typically, plurals) for which today one has to annoyingly
> resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
> horse</dfn>.

We've already solved this problem in Bikeshed/Shepherd, and it would
be a crying shame to have ReSpec try to solve it in an incompatible
way, as it would mean the two types of specs couldn't talk to each
other.

Bikeshed's relevant documention is here:
<https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
We've got a taxonomy of dfn types, which can also be applied to
autolinks to disambiguate.  There are multiple ways to specify what
type a dfn is - an explicit data-dfn-type attribute, an id matching a
particular pattern, a class (on the element or an ancestor) matching a
particular pattern, or the text of the dfn itself matching certain
patterns.  Bikeshed makes this all pretty trivial and turns it
explicit in the source for you, but ReSpec specs obviously would need
to be a little more explicit about things, so that the correct
information shows up in the source html.

I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
I can autolink into ReSpec specs.

So looking into this is on my todo list for Q4 this year.

Would love to find a solution that simplifies cross-referencing between specs and searching for definitions within the whole platform, e.g. what's a browsing context, what the event loop, etc.

Will look into the documentation you provided. Happy to chat more about this in a bit.

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

Re: Various respec enhancements ...

Tab Atkins Jr.
On Tue, Sep 16, 2014 at 11:27 AM, Tobie Langel <[hidden email]> wrote:

> On Tue, Sep 16, 2014 at 8:01 PM, Tab Atkins Jr. <[hidden email]>
> wrote:
>> I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
>> I can autolink into ReSpec specs.
>
> So looking into this is on my todo list for Q4 this year.
>
> Would love to find a solution that simplifies cross-referencing between
> specs and searching for definitions within the whole platform, e.g. what's a
> browsing context, what the event loop, etc.
>
> Will look into the documentation you provided. Happy to chat more about this
> in a bit.

This has basically revolutionized CSS spec editing, and made the new
layout specs actually possible to write sanely (as they can just
cross-ref each other for terms, rather than requiring people to
remember precisely which words are terms of art, and what they mean,
and where they're defined).  I would love to help make this easier for
others, especially as it means I accrue the benefits as well.

~TJ

Reply | Threaded
Open this post in threaded view
|

RE: Various respec enhancements ...

Steve Glaser
In reply to this post by Robin Berjon-6
I forgot to mention it, but in my pcisig fork, the text at the left is automatically generated. This means I don't need a bunch of stylesheets that are identical except for the "background-image: url(//www.w3.org/StyleSheets/TR/logo-ED);" line.

Also, when you print, it turns into the page header.

> -----Original Message-----
> From: Robin Berjon [mailto:[hidden email]]
> Sent: Tuesday, September 16, 2014 3:56 AM
> To: Steve Glaser; [hidden email]
> Subject: Re: Various respec enhancements ...
>
> Hi Steve,
>
> On 25/08/2014 02:56 , Steve Glaser wrote:
> > 1.Register pictures - PCISIG specs are chock full of diagrams of
> > hardware registers. These were being drawn by hand in Illustrator. I
> > added code to respec to automatically draw these figures using a JSON
> > representation and to optionally create that JSON representation from
> > an HTML table elsewhere in the document. For instructions, see
> > http://sglaser.github.io/regpict
>
> That is a very cool feature. However, It's pretty specific and is a feature that
> isn't commonly required by Web specs so I'd be hesitant to see it added to
> core ReSpec.
>
> Do you know that one can use ReSpec *and* build a new profile in order to
> match the needs of a different community? The process is a bit convoluted,
> but https://github.com/darobin/respec-docs/ makes use of it.
>
[Steve Glaser] I looked at respec-docs a while back and got lost. I agree it's not a big draw for this audience. Based on other requests, I'm integrating this into blockdiag (http://blockdiag.com). That way it automatically gets supported in a bunch of places (e.g. Asciidoctor-diagram).

[Steve Glaser] The current code is a bit messy and interacts with the <dfn> code in ReSpec. That way <dfn class="field">foo</dfn> links to the foo field in the figure and vice versa.

> > 2.Lots of <dfn> classes. I wanted to be able to have a bunch of <dfn>
> > types that were formatted differently by CSS. If you include <dfn
> > class="field">foo</dfn>, then any <a>foo</a> fields will automatically
> > get the right class (assuming no ambiguity - if it's ambiguous, you
> > get a message and have to put the class attribute on the <a> tag).
>
> That's cool, and I think it makes sense. One notion that I've thought of
> previously is to have dfn-namespacing as well as alternatives.
>
> Namespacing would work basically like this. Say you have a markup attribute
> and a DOM attribute both called 'unicorn'. You could have
> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and
> <a>dom:unicorn</a> would link to the right one (and drop the namespace
> on render of course). If you need a : in your dfn, \-escaping works.
>
> Alternatives would solve the common problem of referring to the same dfn
> with variants (typically, plurals) for which today one has to annoyingly resort
> to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
> horse</dfn>.
>
> Of course the two could be mixed.
[Steve Glaser] As mentioned in a branch of this thread, the plural issue would be good to fix. Any solution needs to play well with automatic subscripts.

[Steve Glaser] I did things using classes as that meshed with my desire to format <dfn> and <a> differently based on <dfn> class. I ended up needing css classes anyway.

>
> > 3.Automatic subscripts in <dfn>. I remember the innerHTML for each
> > <dfn> and copy it to the <a>. That way if you have
> > <dfn>T<sub>active</sub></dfn> and you reference it as <a>Tactive</a>,
> > you get the <sub> stuff in the expansion..
>
> Indeed, hadn't thought of that. Good feature.
[Steve Glaser] As mentioned in a branch of this thread, it's not limited to <sub>. Any innerHTML gets preserved.

>
> > 4.Enhanced figure numbering. PCISIG figures are numbered within a
> > chapter. If you set the config property "figFmt", you can alter how
> > they are named and numbered.
>
> That's certainly useful.
>
> > 5.Table numbering. Per chapter, like figure numbering but using "tblFmt".
>
> Ditto. That said, not all tables always need to be numbered. Do you have a
> way of disabling that for a given table?
>
[Steve Glaser] Tables get numbered if they have a <caption>. No caption --> no number assigned.

> > 6.Table of Tables. Like Table of Figures. If you have <section
> > id="tot">, you get one.
>
> Again, I can see that being used.
>
> > 7.Expanded references. If you reference a section, figure, etc. The
> > generated HTML includes the figure/section/table number and the
> > figure/section/table caption. You can use css to hide what you don't
> > want. This way, print media can have "See Figure 4-2" without having
> > to work hard.
>
> Didn't we support that already? I thought Frederick had added support for
> that (but I may be wrong).
>
[Steve Glaser] This version also plays well with print output. The HTML includes the figure/section/chapter/table number and the caption title. Css hides what it wants. For example, output using princexml looks great.

> > 8.Dump <dfn> table. If you set the addDefinitionMap config propter to
> > true, you get a table at the end of your document with every <dfn> in
> > the document.
>
> That's pretty cool! I'd suggest a different syntax though. <section id="dnf-
> table"></section> could be found and if present be used to generate that
> section. It's how it's done for other similar features.
>
[Steve Glaser] I agree this is a cleaner way to request the table.

> > 9.Dump section, figure and table names. If you set the addXrefMap
> > config property to true, you get a table at the end of your document
> > with the caption and id values for every section, figure, and table in the
> document.
>
> Same as previous.
>
> > My fork of respec is http://github.com/sglaser/respec. I've pulled
> > Robin's latest changes in, but as I said earlier, I haven't submitted
> > any pull requests.
>
> Don't hesitate to make PRs! It would be simpler to process these features
> individually, but they're cool!
>
> --
> Robin Berjon - http://berjon.com/ - @robinberjon
-----------------------------------------------------------------------------------
This email message is for the sole use of the intended recipient(s) and may contain
confidential information.  Any unauthorized review, use, disclosure or distribution
is prohibited.  If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.
-----------------------------------------------------------------------------------

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Robin Berjon-6
In reply to this post by Tab Atkins Jr.
Hi Tab,

On 16/09/2014 20:01 , Tab Atkins Jr. wrote:

>> Namespacing would work basically like this. Say you have a markup attribute
>> and a DOM attribute both called 'unicorn'. You could have
>> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and <a>dom:unicorn</a>
>> would link to the right one (and drop the namespace on render of course). If
>> you need a : in your dfn, \-escaping works.
>>
>> Alternatives would solve the common problem of referring to the same dfn
>> with variants (typically, plurals) for which today one has to annoyingly
>> resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
>> horse</dfn>.
>
> We've already solved this problem in Bikeshed/Shepherd, and it would
> be a crying shame to have ReSpec try to solve it in an incompatible
> way, as it would mean the two types of specs couldn't talk to each
> other.

I was aware that you'd solved the alternatives issues, which is why I
was thinking of the same syntax, but I hadn't seen that you had the
namespacing as well. That's pretty cool!

In general I *completely* agree with you. I shudder to utter the
sentence "standard for standards" but there are many things that it
would enable.

> Bikeshed's relevant documention is here:
> <https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
> We've got a taxonomy of dfn types, which can also be applied to
> autolinks to disambiguate.  There are multiple ways to specify what
> type a dfn is - an explicit data-dfn-type attribute, an id matching a
> particular pattern, a class (on the element or an ancestor) matching a
> particular pattern, or the text of the dfn itself matching certain
> patterns.  Bikeshed makes this all pretty trivial and turns it
> explicit in the source for you, but ReSpec specs obviously would need
> to be a little more explicit about things, so that the correct
> information shows up in the source html.

Actually I'm pretty sure that ReSpec could support exactly the same syntax.

> I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
> I can autolink into ReSpec specs.

Note that specref has nominal support for cross reference finding, but
the data is lacking (to say the least). You, Tobie, and I should bang
our heads together to make this broadly available. It's not rocket surgery.

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

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Tab Atkins Jr.
On Wed, Sep 17, 2014 at 2:47 AM, Robin Berjon <[hidden email]> wrote:

> On 16/09/2014 20:01 , Tab Atkins Jr. wrote:
>>> Namespacing would work basically like this. Say you have a markup
>>> attribute
>>> and a DOM attribute both called 'unicorn'. You could have
>>> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and
>>> <a>dom:unicorn</a>
>>> would link to the right one (and drop the namespace on render of course).
>>> If
>>> you need a : in your dfn, \-escaping works.
>>>
>>> Alternatives would solve the common problem of referring to the same dfn
>>> with variants (typically, plurals) for which today one has to annoyingly
>>> resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
>>> horse</dfn>.
>>
>>
>> We've already solved this problem in Bikeshed/Shepherd, and it would
>> be a crying shame to have ReSpec try to solve it in an incompatible
>> way, as it would mean the two types of specs couldn't talk to each
>> other.
>
>
> I was aware that you'd solved the alternatives issues, which is why I was
> thinking of the same syntax, but I hadn't seen that you had the namespacing
> as well. That's pretty cool!

It's even stronger than that - some things are namespaced on not just
their type, but on what thing they're associated with.  CSS, for
example, defines a million "auto" keywords in various contexts;
Bikeshed's data model allows them to be marked up with a
"data-dfn-for" attribute containing what it's for (usually the
property name), and you can then reference that when auto-linking to
disambiguate.

>> Bikeshed's relevant documention is here:
>>
>> <https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
>> We've got a taxonomy of dfn types, which can also be applied to
>> autolinks to disambiguate.  There are multiple ways to specify what
>> type a dfn is - an explicit data-dfn-type attribute, an id matching a
>> particular pattern, a class (on the element or an ancestor) matching a
>> particular pattern, or the text of the dfn itself matching certain
>> patterns.  Bikeshed makes this all pretty trivial and turns it
>> explicit in the source for you, but ReSpec specs obviously would need
>> to be a little more explicit about things, so that the correct
>> information shows up in the source html.
>
> Actually I'm pretty sure that ReSpec could support exactly the same syntax.

The problem is that Shepherd isn't really able to do the ReSpec
transformations, so it'd need to be reflected in the source.  As an
offline processor, this is trivial for Bikeshed, but it means more
work for someone using an online processor like ReSpec.

>> I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
>> I can autolink into ReSpec specs.
>
> Note that specref has nominal support for cross reference finding, but the
> data is lacking (to say the least). You, Tobie, and I should bang our heads
> together to make this broadly available. It's not rocket surgery.

Yeah, SpecRef's cross-linking support is Anolis-inspired, where you
have to specify the id every time (and you have to uniquify IDs across
all documents, I think?).  It's a very poor data model, unfortunately.
Shepherd (maintain by Peter Linss) does all the parsing and
dfn-finding for Bikeshed, and is aware of Bikeshed's data model (me
and Peter evolved it together).  It's publicly available at
<http://api.csswg.org/shepherd/>.

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Shane McCarron
Does specref even really support cross-linking?  Or maybe you are using the term differently than I do?

SpecRef is just a database of bibliographic references.  I suppose it would be possible to reference items within the other documents (e.g., [MyOtherSpec#fragment] but I don't think we do anything like that today.  

FWIW the PFWG is going to have a requirement for this sort of thing sooner than later.  So yes, it would be great if we could settle on a syntax.

On Wed, Sep 17, 2014 at 2:36 PM, Tab Atkins Jr. <[hidden email]> wrote:
On Wed, Sep 17, 2014 at 2:47 AM, Robin Berjon <[hidden email]> wrote:
> On 16/09/2014 20:01 , Tab Atkins Jr. wrote:
>>> Namespacing would work basically like this. Say you have a markup
>>> attribute
>>> and a DOM attribute both called 'unicorn'. You could have
>>> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and
>>> <a>dom:unicorn</a>
>>> would link to the right one (and drop the namespace on render of course).
>>> If
>>> you need a : in your dfn, \-escaping works.
>>>
>>> Alternatives would solve the common problem of referring to the same dfn
>>> with variants (typically, plurals) for which today one has to annoyingly
>>> resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
>>> horse</dfn>.
>>
>>
>> We've already solved this problem in Bikeshed/Shepherd, and it would
>> be a crying shame to have ReSpec try to solve it in an incompatible
>> way, as it would mean the two types of specs couldn't talk to each
>> other.
>
>
> I was aware that you'd solved the alternatives issues, which is why I was
> thinking of the same syntax, but I hadn't seen that you had the namespacing
> as well. That's pretty cool!

It's even stronger than that - some things are namespaced on not just
their type, but on what thing they're associated with.  CSS, for
example, defines a million "auto" keywords in various contexts;
Bikeshed's data model allows them to be marked up with a
"data-dfn-for" attribute containing what it's for (usually the
property name), and you can then reference that when auto-linking to
disambiguate.

>> Bikeshed's relevant documention is here:
>>
>> <https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
>> We've got a taxonomy of dfn types, which can also be applied to
>> autolinks to disambiguate.  There are multiple ways to specify what
>> type a dfn is - an explicit data-dfn-type attribute, an id matching a
>> particular pattern, a class (on the element or an ancestor) matching a
>> particular pattern, or the text of the dfn itself matching certain
>> patterns.  Bikeshed makes this all pretty trivial and turns it
>> explicit in the source for you, but ReSpec specs obviously would need
>> to be a little more explicit about things, so that the correct
>> information shows up in the source html.
>
> Actually I'm pretty sure that ReSpec could support exactly the same syntax.

The problem is that Shepherd isn't really able to do the ReSpec
transformations, so it'd need to be reflected in the source.  As an
offline processor, this is trivial for Bikeshed, but it means more
work for someone using an online processor like ReSpec.

>> I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
>> I can autolink into ReSpec specs.
>
> Note that specref has nominal support for cross reference finding, but the
> data is lacking (to say the least). You, Tobie, and I should bang our heads
> together to make this broadly available. It's not rocket surgery.

Yeah, SpecRef's cross-linking support is Anolis-inspired, where you
have to specify the id every time (and you have to uniquify IDs across
all documents, I think?).  It's a very poor data model, unfortunately.
Shepherd (maintain by Peter Linss) does all the parsing and
dfn-finding for Bikeshed, and is aware of Bikeshed's data model (me
and Peter evolved it together).  It's publicly available at
<http://api.csswg.org/shepherd/>.

~TJ


Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Tab Atkins Jr.
On Wed, Sep 17, 2014 at 1:03 PM, Shane McCarron <[hidden email]> wrote:
> Does specref even really support cross-linking?  Or maybe you are using the
> term differently than I do?
>
> SpecRef is just a database of bibliographic references.  I suppose it would
> be possible to reference items within the other documents (e.g.,
> [MyOtherSpec#fragment] but I don't think we do anything like that today.

Check out the README <https://github.com/tobie/specref/> - it's mainly
for bibliographic refs, yes, but it also supports cross-refs, by
serving as a repository of terms and urls.

> FWIW the PFWG is going to have a requirement for this sort of thing sooner
> than later.  So yes, it would be great if we could settle on a syntax.

I think everyone has a requirement for good cross-refs; it's
super-annoying to ref other specs yourself, so it happens far less
than it should.

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Robin Berjon-6
In reply to this post by Tab Atkins Jr.
On 17/09/2014 21:36 , Tab Atkins Jr. wrote:
> Yeah, SpecRef's cross-linking support is Anolis-inspired, where you
> have to specify the id every time (and you have to uniquify IDs across
> all documents, I think?).  It's a very poor data model, unfortunately.
> Shepherd (maintain by Peter Linss) does all the parsing and
> dfn-finding for Bikeshed, and is aware of Bikeshed's data model (me
> and Peter evolved it together).  It's publicly available at
> <http://api.csswg.org/shepherd/>.

Well, given that at this point no one relies on SpecRef's support for
xrefs I don't think it would be a big issue to change how it works.

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

Reply | Threaded
Open this post in threaded view
|

Re: Various respec enhancements ...

Tobie Langel-3
On Mon, Sep 22, 2014 at 2:37 PM, Robin Berjon <[hidden email]> wrote:
On 17/09/2014 21:36 , Tab Atkins Jr. wrote:
Yeah, SpecRef's cross-linking support is Anolis-inspired, where you
have to specify the id every time (and you have to uniquify IDs across
all documents, I think?).  It's a very poor data model, unfortunately.
Shepherd (maintain by Peter Linss) does all the parsing and
dfn-finding for Bikeshed, and is aware of Bikeshed's data model (me
and Peter evolved it together).  It's publicly available at
<http://api.csswg.org/shepherd/>.

Well, given that at this point no one relies on SpecRef's support for xrefs I don't think it would be a big issue to change how it works.

Agreed.

As mentioned previously. This is on my todo list for Q4. I'll ping you all when I get there (unless of course, someone beats me to it, which would be all kinds of awesome).

--tobie