Re: UCR doc skeleton

On 15/04/2016 07:16, Michael Steidl (IPTC) wrote:
[..]

>
> michaelS: my conclusions
> - the doc on Github is the publicly relevant one, the Wiki page only an internal notepad.

That's how I see it, yes.

> - Sub question: it was said that WG-external persons may submit a UC by the email list, then it should be transferred to the "UC page" - is it requited that this UC takes two hops: Wiki page and Github or may it go directly to the Github?

One hop is sufficient - we're not *that* bad I hope.

>
>> - Q2: How to edit the UCR page 1: how to split the work between my editing and the ReSpec library?
>
> Don't touch ReSpec. Everything you need to know about what it does and how to make best use of its features (which are powerful) is at/linked from https://www.w3.org/respec/
>
> michaelS: The User Guide - https://www.w3.org/respec/guide.html - is quite helpful. To activate the ReSpec features one has to use the HTML markup defined for it.

Yep, that's the idea. It looks through the doc for elements and classes 
and acts accordingly. So, for example, if you have

<section>
   <h2>A heading</h2>

   <section>
     <h1>A bigger heading in a sub section</h1>
   </section>
</section>

It will automatically fix the erroneous heading numbers, generate the 
ToC etc.

Please use <section /> elements as the basis of the document structure, 
and include ids for each one (respec will automatically create ids for 
the <hn /> elements within the sections.


>
>> - Q3: How to edit the UCR page 2: how to trigger the work of the
>> ReSpec library? (or is this implicitly triggered by some event?)
>> - Q4: do I get it right that the Use Cases and the Requirements should be on a single page?
>
> Ah, pages, I remember those ;-)
>
> It's a single document.
>
> michaelS: I'm able to disambiguate pages and documents - and I see that e.g. the HTML5 Recommendation document located at https://www.w3.org/TR/html5/ is made of many pages. That's why I've asked.

I sincerely hope I didn't come across as being rude. I know you know! If 
specs are very long - and the HTML5 spec is a monster - then, yes, we'll 
split it into multiple pages. But I would be surprised if any of the 
docs being produced by this group needed it.

>
> However, if you wish to use some dynamic features then that's OK. For example, the Spatial Data WG has a staggering 50 use cases and 57 requirements. That makes it a *very* long document. To make it more manageable, they collapse all the UCs and you click to expand (if JavaScript is disabled the default view is shown, which is with everything expanded). https://www.w3.org/TR/sdw-ucr/
>
>>
>> Note: I've set up a local POE Git repository and edited a single
>> character in the UCR index.html page - was not able to push it to the
>> W3C Github POE respository. Is this approach wrong or do I only need
>> rights for that action? (I see only you and Ivan are currently
>> collaborators.)
>
> I need to add you to the collaborators - for which all I need is your GitHub user name.
>
>>
>> For me most essential is Q1 as currently I don't understand i/ why to have very similar pages and ii/if there is a chance to update/synchronize data from one page to the other one.
>
> Sorry it's so manual. As editor, you get to choose how you organise and present the doc, based on what the WG decides should be its content. If you like, the wiki is an easy-to edit inbox for you where people can dump stuff. How you take it out and process it is under your control.
>
> michaelS: what I'm not happy about is having to change the HTML markup of the Wiki to the HTML markup of ReSpec manually. This is squandering time.

I understand. The wiki is, as you rightly describe it, a notepad.


One thing that might speed things up is to use the browser's element 
inspector to grab the actual HTML from the wiki. The browsers are all 
slightly different but they have a way to inspect elements - which shows 
you the DOM. For example, in Firefox:

(and forgive me if you know this already).

All these commands are on the context menu (right click/ctrl+click)

 From the contextual menu select Inspect Element

That will show you the DOM in a window at the bottom of the screen.

Select Expand All.

The Copy outer HTML

Paste into a text editor - and then fiddle.

Hope this helps to reduce the drudgery.

Phil.

Received on Friday, 15 April 2016 06:57:41 UTC