Re: ReSpec2 section references and figures

Hi Gregg,

thanks for your input!

On May 25, 2010, at 01:39 , Gregg Kellogg wrote:
> Figures
> 
> Proposed: Figures may be designated by setting class to figure. An automatically numbered title will be generated with content set from the title or alt attribute of the same element.
> 
> Figures may be referenced within the document using an a element, as with Definitions. To generate a reference including the figure number, use an a element with empty content.
> 
> <img class="figure" id="my-image" src="images/image.jpg" alt="Cool Image"/>
> <p>Check out <a href="#my-image"></a>.</p>
> 
> will generate the following output:
> 
> <img class="figure" id="my-image" src="images/image.jpg" alt="Cool Image"/>
> <p class="figure-title"><span class="figno">1</span>: Cool Image</p>
> <p>Check out <a class="figno-ref" href="#my-image">1</p>
> 
> A Table of Figures could be generated fairly easily too.

I would very much support the addition of a plugin for figures. It was suggested previously that we use the HTML5 <figure> element for this, but it appears to be in flux so it might not be advisable. I would suggest the following details:

  - if the a element referencing a figure has content, it isn't touched
  - it might be worth having more structure in the output, such as having a div with class figure around the img and its caption
  - for the ToF I'd suggest DWIMing. If there's a div in the document with id='tof' then put the appropriate content in there, otherwise do nothing

> Internal Section References
> 
> Normal section references may be created using an a element with an href pointing to the id of a specific section. If the content of the a element is left empty, ReSpec will fill it in with the auto-numbered section reference as follows:
> 
> <section id="this">
> <h2>This Section</h2>
> <p>Reference to <a href="#this"></a>.</p>
> </section>
> 
> would result in the following output:
> 
> <section id="this">
> <h3><span class="secno">2.4 </span>This Section</h3>
> <p>Reference to <a class="secno-ref" href="#this">2.4</a>.</p>
> </section>

This is also very useful. Ideally, for consistency, we would also add class=secno-ref to any a that references a section (by which I mean, even those not processed by this plugin). It would also be nice to have output options that would allow one to control whether the section number, the title, or both are generated, whether it's prefixed with "Section", etc. But I guess that can be added later (the same goes for figures actually).

Thanks a lot!

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

Received on Wednesday, 26 May 2010 10:50:43 UTC