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

From: Tom Hastings <[email-masked]>
Date: Tue, 19 Aug 1997 12:09:13 PDT

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.

>
>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..."

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

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

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

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

>	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: Wed, 20 Aug 1997 16:59:11 -0700 (PDT)

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

> 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.
> that you are not talking about "A group of jobs...", as opposed to "a group of
My comment was the latter.  I always believed that sentences should 
start with a capital letter.
> 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.
> 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.
> 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.
> the management app, etc.  So I indicated that is the agent that sets
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.

---

From: Ron Bergman <[email-masked]>
Date: Fri, 22 Aug 1997 16:28:33 -0700 (PDT)

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