RE: [cmis] Spec formatting

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

Yes, and the published form of the specification needs printed line numbers
in the margins, too.  This is important when there are editorial comments on
specific items, in being clear when a passage is being commented on, and in
providing instructions in errata.

I think of deep section numbering (whether TOC is deep or not), line
numberings, and permalinks as dealing with lifecycle issues around the
birth, approval, maintenance, and death of a specification.  It also helps
when describing changes between one specification and its successor.

 - Dennis

PS: The advantage of permalinks everywhere there is a section number
(including numbered paragraphs) is that clicking on it serves up the URL
that is needed to include in a comment on that portion of the specification.
It is *really* useful in having people make precise comments. 

-----Original Message-----
From: David Nuescheler [mailto:david@day.com] 
Sent: Sunday, January 11, 2009 23:53
To: dennis.hamilton@acm.org
Cc: Julian Reschke; cmis@lists.oasis-open.org
Subject: Re: [cmis] Spec formatting

Hi all,

Yeah, Julian has been pushing me to do that for a long time in JCR,
(for very good reasons I might add;)

The online JCR version this looks like this ...

http://www.day.com/specs/jcr/1.0/

... while one can argue the granularity of the spec I think it helps
collaboration
tremendously.

An additional very small detail related to referencing parts of the
specification
(which is very painful when printed), the 0.5 draft does not have page
numbers
which is an issue when using the TOC.
Maybe we should log this as an issue just so it doesn't get lost.

regards,
david

On Mon, Jan 12, 2009 at 3:26 AM, Dennis E. Hamilton
<dennis.hamilton@acm.org> wrote:
> What he said.
>
> I'm all for permalinks down to the numbered paragraph level.  It's a big
win
> for reference to specific passages of a specification, especially if it is
> made available on-line for navigation by browser.
>
>  - Dennis
>
> -----Original Message-----
> From: Julian Reschke [mailto:julian.reschke@greenbytes.de]
> Sent: Sunday, January 11, 2009 11:40
> To: cmis@lists.oasis-open.org
> Subject: [cmis] Spec formatting
>
> Hi,
>
> while opening issues against the spec I find looking for section (and
> subsection) numbers :-)
>
> Speaking of which; an online HTML version that can easily
> linked/referred to would be even better (yes, people who are also in the
> JCR EG will find me sounding like a broken recored ;-).
>
> BR, Julian
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
>



-- 
Visit: http://dev.day.com/

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php