Ron,
I can go along with making your suggested changes for items 1, 2, 4, 5,
and 7:
1. Removing the PJL example use of "job" and "document", though it was
a long standing action item for Bob Pentecost and me that we finally did.
2. Starting each definition with a capital letter, even though they
aren't sentences.
4. Removing the explanation that the jmGeneralJobPersistence object
can be set either by the system administrator or by the implementation
in an implementation-dependent manner,
but instead of "Configuration of this parameter is implementation dependent."
how about:
Configuring this object is implementation-dependent.
(We haven't used the term "parameter" before to describe an object).
I agree that we can explain in the FAQ at least these two ways.
5. Same for jmGeneralAttributePersistence?
7. Ordinarily, I avoid the passive voice in order to make it clear which
side of the interface is performing the action. But in this case its OK
to use the passive voice on setting the read-only object, since
it couldn't be the application that sets a read-only object, and I agree
that it could be either the agent or the device (and doesn't matter which).
I'll reply to items 3 and 6 as separate messages, since I have some variations
to propose, in case anyone else is interested.
Tom
At 16:59 08/20/97 PDT, 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
>>>>>>>