Re: Various respec enhancements ...

see inline, but need help finding v1 documentation

regards, Frederick

Frederick Hirsch, Nokia
@fjhirsch



On Sep 16, 2014, at 6:55 AM, Robin Berjon <robin@w3.org> 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
>

Received on Tuesday, 16 September 2014 13:35:08 UTC