RE: Various respec enhancements ...

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:robin@w3.org]
> Sent: Tuesday, September 16, 2014 3:56 AM
> To: Steve Glaser; spec-prod@w3.org
> 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.
-----------------------------------------------------------------------------------

Received on Tuesday, 16 September 2014 18:50:37 UTC