Subject: Re: JMP> Open Editorial Changes From Rev. 0.83

From: Harry Lewis <[email-masked]>
Date: Mon, 25 Aug 1997 15:38:14 -0400

Ron, I, for one, have printed your issues list but have not had the
opportunity to review it. I did not seem to be able to make determinations
"on line". There lots of "embedded" statements and the issues appear to
have more depth than one would expect for purely editorial comments.
I would like another day or two.

The fact that there seems to be little conversation on these items
implies they must be OK or else others are in the same boat as me.

Harry Lewis - IBM Printing Systems

-------- Forwarded by Harry Lewis/Boulder/IBM on 08/25/97 01:27 PM ---------

[email-masked] on 08/23/97 04:21:19 AM
Please respond to [email-masked] @ internet
To: [email-masked] @ internet
cc:
Subject: Re: JMP> Open Editorial Changes From Rev. 0.83

I have received only one response regarding the following proposal.
If anyone objects please reply immediately, otherwise the following
will be incorporated into the document.  (No reply indicates
acceptance.)

 Ron Bergman

On Wed, 20 Aug 1997, Ron Bergman wrote:

> We need to get the following issues resolved ASAP.  I am requesting
> anyone involved with the Job MIB, please comment immediately if you
> have an opinion for either position on these issues.
>
> None of these issues are of any technical consequence and I will
> agree with the majority vote.  All issues are only editorial but
> should result in a cleaner and more readable document.
>
> The original comments were submitted by me (Ron Bergman) with
> respect to the version 0.83 document and were not included in the
> 0.84 issue.  Tom has included his reasons for not including these
> comments followed by my rebuttal.
>
>  Ron Bergman
>
>
> On Tue, 19 Aug 1997, Tom Hastings wrote:
>
> > At 17:46 08/12/97 PDT, Ron Bergman wrote:
> > >Tom,
> > >
> > >The following editorial corrections from revision 0.83 were not
> > >incorporated into version 0.84.  Please comment if there is a
> > >reason that these should not be incorporated.
> >
> > I'm sorry that I didn't have time to respond before as to why I did not
> > include these (few) editorial comments.  See if you agree with my reasoning
> > for not including them.  I did include 99% of your suggestions and they
> > improved the document.
> >
> > >                                                 I do not believe
> > >that any of the corrections change the intent of the document.
> >
> > I agree that none of your corrections changed the intent of the document,
> > including these few that I did not include.
> >
> > >
> > >
> > >Problems from 0.83:
> > >
> > >1. Section 2. Terminology and Job Model (page 14) states:
> > >
> > >   "PJL systems use the term job to mean what we call a job in this
> > >    specification.  PJL also supports multiple documents per job, but
> > >    does not support specifying per-document attributes independently
> > >    for each document."
> > >
> > >   This text should be a part of the mapping document.  This additional
> > >   example does not provide any additional help in understanding the
> > >   subject paragraph.
> >
> > I disagree.  I think that it is important to understand the terms that
> > the Job Monitoring MIB is using and to have an example mapping on this
> > term.  I also didn't want to include only the PostScript example.  It seems
> > more even handed to keep both examples to show that the mapping varies
> > depending on the job submission protocol.
> >
> This subject is not difficult to understand and I would argue that no
> examples are required.  (All you are stating is that the definitions
> are being locked down in this section.)  The PJL example is much too
> deep and really belongs in the mapping document.  I do not see where
> the PJL example provides any additional explaination as to why we
> need the definitions.
> > >
> > >2. The definitions in section 2 should begin with a capital letter.
> > >   Example:  "Job Set: A group of jobs..."
> >
> > I agree and both the .doc and .txt files have "Job Set", not "job set".
> > None of the definitions themselves start with a capital letter, so I assume
> > that you are not talking about "A group of jobs...", as opposed to "a group
of > > jobs..." > > > My comment was the latter.  I always believed that
sentences should > start with a capital letter. > > > > > >3. The definition
for "Device" (page 14): > > > > > >   "...interfaces to humans in human
perceptible means, such as produces > > >    marks on paper, scans marks on
paper to produce an electronic > > >    representations, or writes CD_ROMS..." >
> > > > >   The second two examples don't appear to be human perceptible.  I am
>
> >   not sure I understand the reason for including other than the first > > >
example. > > > > It is important to clarify that the device can produce other
forms of > > human perciptable output than just printing devices, as we agreed
in > > the requirements document.  So I left these other examples in. > > > How
is scaning marks on paper or writing a CD ROM human perceptible? > The only way
you know for sure the operation was completed (or even > started) was a message
on display or a printer. > > > > > >4. In jmGeneralJobPersistence (page #75),
the second paragraph: > > > > > >        "Depending on implementation, the value
of this object MAY be > > >        either: (1) set by the system administrator
by means outside > > >        this specification or (2) fixed by the
implementation." > > > > > >    Since this is a read only object do we need to
define how it is > > >    configured?  We only need to describe the function.
Suggest: > > > > > >        "Configuration of this parameter is implementation
dependent." > > > > I think that it helps to clarify that there are several
ways that > > an implementation can set the value, so I left in both ways. > > >
Ok, then who does this help?  If I say implementation dependent, the > designer
can devise any method he desires.  If you feel this info > is really important,
it should go into the FAQ.  The specification > should only contain the
requirements and restrictions.  Helpful > hints, unless not obvious to the
average developer, should be in the > FAQ.  In this case, the alternatives are
obvious. > > > > > >5. For jmGeneralAttributePersistence (page #76) the above
comment > > >   also applies. > > > > I left both in for the same reason. > > >
> > > > >6. In jmJobStateReasons1 (page #81), I find the following statement > >
>   hard to disagree with, but why do we need to state this? > > > > > >
"Furthermore, when implemented as with any MIB data, the > > >        agent
SHALL return these values when the reason applies and > > >        SHALL NOT
return them when the reason no longer applies whether > > >        the value of
the job's jmJobState object changed or not." > > > > > >    All this really
states is that the value of an object must be valid. > > >    We do not have a
similar statement for any other object. > > > > I disagree.  One commentor
asked whether the bits had to be turned off or not, > > so I felt it was
important to clarify that these bits are meaningful while > > the job is in each
job state, not just when the job transitions from one > > state to another.
There are hardware implementations in which such bits > > are only meaningful on
the state transitions.  As far as I'm concerned, > > if someone asks about
something it can't hurt to include the explanation > > in the document.  There
will be others who will ask the same question, but > > we won't be there to
answer. > > > Since the question was asked, this should be in the FAQ and not
in the > specification.  All this sentence states is "thou shall not lie".  If >
the document states that this attribute indicates this condition and > the
implementation sets the attribute when the condition is not true, > the
implementation is violating the specification!  I do not believe > that the
document should answer every question that was asked.  That > is why we should
have a FAQ. > > > > > >7. Also in jmJobStateReasons1 (page #81), the next
sentence: > > > > > >        "When > > >        the job does not have any
reasons for being in its current > > >        state, the agent SHALL set the
value of the jmJobStateReasons1 > > >        object and jobStateReasonsN
attributes to 0." > > > > > >    I suggest it be reworded to: > > > > > >
"When the agent cannot provide a reason for the current > > >        state of
the job, the value of jmJobStateReasons1 object > > >        and
jobStateReasonsN attributes shall be 0." > > > > > > > I had taken your
suggestion in V0.84, but kept it in the active voice: > > > >         When the
agent cannot provide a reason for the current state of the > >         job, the
agent SHALL set the value of the jmJobStateReasons1 > >         object and
jobStateReasonsN attributes to 0." > > > > I have tried hard to avoid the
passive voice, since there are many entities > > in the system that do things:
the agent, the device, the server, > > the management app, etc.  So I indicated
that is the agent that sets > > the values to 0. > > > Actually I prefer the
passive voice since it may not be the agent that > sets the value.  The agent
may just collect the information from the > printer controller and pass it to
the SNMP agent. > > > > > > > > > Ron Bergman > > > Dataproducts Corp. > > > > >
 > > So I hope you agree that all of your editorial suggestions are closed. > >
 > > Thanks, > > Tom > > > > > >

---

From: Ron Bergman <[email-masked]>
Date: Mon, 25 Aug 1997 13:05:15 -0700 (PDT)

Harry,

I will close this issue then Wednesday evening.  Let mw know if
you will need more time.  I certainly would like these items to
have a good review before we close the document.

	...Ron

> will be incorporated into the document.  (No reply indicates
...snip...snip.