RE: [cmis] Spec formatting

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

1. Actually, the use of line numbers in specifications is a forgotten
practice, used back when it was hard but it was the printer who had to do
it, not some desktop-publishing software.  I worked on ANSI X3.4
specifications in the 60s that had marginal line numbers.  I don't think I
have any copies left though.  

2. I have no quarrel with the omission of line numbers in XHTML documents,
where pagination is also not used, but that does make the use of permalinks
all the more valuable.

3. [Off-topic: The best place for line numbers to be useful is when a PDF is
the authoritative text.  For office-document formats the line numbers are
not authoritative (and neither is the document, really) because the
pagination and numbering can differ from one computer to another, and one
version/platform/configuration of the software to another (leading to a
variety of fidelity issues).  I do not think [X]HTML of lengthy texts or
ones in multiple pages are a good idea, unless a downloadable complete
version is also provided.  There are fidelity issues between different user
agents and it is important to be able to use the document reliably in an
off-line situation, including printed on paper.  That pretty much makes the
default choice a PDF at the current state of our technology.

You cannot believe how many man hours were wasted on the just-issued ODF 1.0
Errata 01 document because of problems counting lines, applying changes to
the wrong, but similar, place, etc.

4. [Agreement [;<) I enthusiastically agree with Robin Cover that having
finer granularity for section and even paragraph numbering will also do the
job.  Either way permits annotation of implementations, conformance reports,
and other artifacts (sermons included) by precise reference to appropriate
passages of the specification.  I accept the spirit of that completely.

 - Dennis

PS: Robin, Thanks for the quote on what must be delivered from the TC.  It
answers a question about schemas that I have over on another TC. 

-----Original Message-----
From: Robin Cover [mailto:robin@oasis-open.org] 
http://lists.oasis-open.org/archives/cmis/200901/msg00023.html
Sent: Monday, January 12, 2009 09:23
To: Dennis E. Hamilton
Cc: 'David Nuescheler'; 'Julian Reschke'; cmis@lists.oasis-open.org
Subject: RE: [cmis] Spec formatting

NB. "** Disclaimer" at the end of the message

[Dennis]
http://lists.oasis-open.org/archives/cmis/200901/msg00022.html
"the published form of the specification needs printed line numbers..."

[ ... ]

* 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 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

[ ... ]