[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [cmis] Spec formatting
NB. "** Disclaimer" at the end of the message
[Dennis]
"the published form of the specification needs printed line numbers..."
I don't normally disagree with Dennis E. Hamilton (who is
obviously hard at work in OASIS TCs - thanks, Dennis!), but here
offer an alternative opinion about line numbers:
* I don't think line numbers are required in the "published" form
of the OASIS specification (or in any SSO's specification); in
most cases, I don't think they are desirable.
* OASIS TCs should designate one of the three required formats
(editable source, HTML/XHTML, PDF) as "authoritative" [1],
and (thus) 'HTML/XHTML' may be THE authoritative format
version. Some TCs, as in other SSOs, author in HTML/XHTML,
so the editable source *IS* the (X)HTML, and no word
processor format is ever available. The published (X)HTML version
will not have line numbers. Obviously
* In 2009, in the WWW environment, I think HTML/XHTML is by
far the superior choice for a specificiation format: that's
why (e.g.,) W3C publishes its deliverables in (X)HTML.
Much better (hypertext) functionality, etc... [arguments
omitted here -- and indeed, I don't intend to launch a
debate about the (de)merits of competing formats]
* As far as I know, the idea os using line numbers in specs
is a recent "innovation" -- oddly, because we have had the
technical ability to print line numbers for decades.
In early 2007 (maybe late 2006?), I made a quick survey of the
standards space, using the Internet and my small collection of
ISO and ANSI print copy standards: I found no standards that
use line numbers. [NB, the situation is now slightly different]
I think I checked W3C [3], IETF [4], ISO [5], WS-I [6],
Unicode Consortium [7], DCMI [8], ANSI/NISO [9], OMG [10],
ITU-T [11], IEEE [12], ECMA [13], ETSI [14], XBRL [15]
(references missing, but I can supply for anyone who wishes)
The reason is that well-written specifications are finely
granulated by (sub)section identifiers, and identifiers for
figures, tables, etc. Lack of line numbers has never --
as far as I know -- been an impediment to good standards work.
In the typical case, lemma citation requires or benefits from substring
quoting as well as provision of identifier(ID).
In summary: while the topic of line numbering for specs could be debated,
I think everyone agrees that a specification becomes clearer
and easier to use when the (sub)sections are finely granulated,
and provided with machine-readable (URI-addressable, linkable) anchors
for hypertext navigation. This memo has been written chiefly to
encourage good document design which does not depend upon line
numbers for citation.
[1] http://www.oasis-open.org/committees/process-2008-06-19.php#specQuality
Verbatim:
-----------------------------------------------------------------------------
Editable formats of all versions of TC documents must be
delivered to the TC's document repository. TC Working
Drafts may be in any format (i.e. produced by any application).
All TC-approved versions of documents (i.e. Committee Drafts,
Public Review Drafts, and Committee Specifications) must be
delivered to the TC's document repository in the (1) editable
source, (2) HTML or XHTML, and (3) PDF formats; and the TC
must explicitly designate one of those delivered formats as
the authoritative document. Any links published by the TC
shall be to the HTML, XHTML and/or PDF formats stored using
repositories and domain names owned by OASIS and as approved
by the TC Administrator.
All schema and XML instances, whether by inclusion or by
reference, including fragments of such, must be well formed.
All expressions must be valid. Each schema and XML instance
that is part of the specification must be delivered in its
own separate plain text file.
------------------------------------------------------------------------------
** Disclaimer: this memo is not official OASIS guidance; it's just a
personal (but studied) opinion by an OASIS Staff members speaking
for himself as an individual, not for OASIS Staff.
Cheers,
- Robin Cover
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783
On Mon, 12 Jan 2009, Dennis E. Hamilton wrote:
> 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
>
>
> ---------------------------------------------------------------------
> 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
>
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]