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.

> 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

Received on Tuesday, 16 September 2014 10:56:00 UTC