Subject: [forces] LFBlib readability suggestions

From: Jamal Hadi Salim <[email-masked]>
Date: Tue, 26 Apr 2011 07:01:26 -0400

to the authors,

As i have whined before, the general draft text is hard to read.
I think making things a little more formal as in the example LFB
in RFC 5812 section 8 will go a long way to improve readability.

I have attempted to redo the EtherPHYCop section, I didnt go 100% with
the RFC5812 format but please take a look in particular the "XXX"
and cross reference with:
- the text that exists right now in the draft
- the xml (and also to make sure it is well described)
- the formal scheme to describe things as i laid it out. The model
draft LFB example in section 8 is a good start.

cheers,
jamal

---

From: "Haleplidis Evangelos" <[email-masked]>
Date: Wed, 27 Apr 2011 00:06:04 +0300

Greetings to all,

After Jamal's suggestion I took his initiative and completed the etherphycop
definition.

Please take a look and comment, in the meantime I'll start working on the
EtherMacIn.

About Jamal's comments:

XXX: It may make sense to have each of Components, Capabilities and Events
on its own section?

I think it is more readable this way and also following the same format as
the model RFC provides consistency.

XXX: I copied this from the draft but i think it may be wrong. The xml says
this component is read-only. And i remember we had a very long discussion
(refer to how one would map a port name to the PHY on how this ID is to be
used).

Well, even the text says that: " is defined so the CE can assign an ID ".
Since the CE can assign the ID then it must be read-write. I think we should
change it in the XML.

XXX: Should we be discussing all the components, capabilities and events?
i.e why the brief description below? Either that or the XML synopsis needs
to be a lot more descriptive.

I think we should be discussing ALL components/capabilities/events.
It's more readable this way. Someone not familiar with xml may want to read
and understand in this way of reading instead of looking around in the xml.

Also there is a typo in the xml definition of the EtherPhyCop. In the
synopsis of the DuplexModeChanged there is a "speed." in the end that is not
supposed to be there.

Regards,
Evangelos Haleplidis.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of Jamal Hadi Salim
> Sent: Tuesday, April 26, 2011 2:01 PM
> To: [email-masked]
> Cc: Chuanhuang Li; wmwang; Joel M. Halpern
> Subject: [forces] LFBlib readability suggestions
> 
> to the authors,
> 
> I think making things a little more formal as in the example LFB in RFC
> 5812 section 8 will go a long way to improve readability.
>

---

From: Jamal Hadi Salim <[email-masked]>
Date: Tue, 26 Apr 2011 17:43:01 -0400

Greetings Evangelos,

Looks very nice!
Now if we could do all the LFBs like that, the document readability
would improve greatly!

More comments inlined.

> the model RFC provides consistency.

Fine with me;->

> Since the CE can assign the ID then it must be read-write. I think we should

I think the CE cannot assign an ID - the FE comes up with it. The
text contradicts the XML (as i was pointing out).

> and understand in this way of reading instead of looking around in the xml.

Like  i said above, I am fine with that approach,

> synopsis of the DuplexModeChanged there is a "speed." in the end that is not

I didnt catch that one, but you are right.

Thanks for the effort Evangelos.

cheers,
jamal

---

From: "Chuanhuang Li" <[email-masked]>
Date: Wed, 27 Apr 2011 09:21:27 +0800

Hi, Evangelos
     
    When you are reorganizing the draft content, and if there is contradiction between 
text and the latest XML which i had post on list before, please use the XML as guidance.
This is because after draft-03, we had discussed some contents and reached some consensuses.
And I think maybe Weiming has the latest draft contents text.
Thanks!

Yours,
Chuanhuang
	
======= 2011-04-27 04:58:08 Haleplidis Evangelos, wrote: =======

---

From: "Wang,Weiming" <[email-masked]>
Date: Wed, 27 Apr 2011 13:33:34 +0800

Hi  Evangelos and Jamal,

There are several changes since 03 version on the LFB description section. Attached is the latest text that I'v been maintaining. Pls use this text as your base text to make  the modification. 

I'l incorparate every LFB description text since it has been made consensus by the list.

Another suggestion is, Evangelos, pls make a title with the LFB name for every text modification so that we can trace the discussions easily. 

thanks a lot.
Weiming

----- Original Message ----- 
From: "Chuanhuang Li" <[email-masked]>

> _______________________________________________
> forces mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/forces
>

---

From: "Wang,Weiming" <[email-masked]>
Date: Wed, 27 Apr 2011 22:18:24 +0800

Hi Jamal and Evangelos,

I have some more thoughts to share with you on the LFB description text. 

Actually I also think it is made easier to reader by sub-sections according to the LFB individual properties. In fact I thought to do like this at beginning. I even thought of two other ways like 1) with a picture to show the inputs and outputs. 2) with the outline as we were discussing the LFB difinitions among authors at the very beginning. The outline can be put at the LFB description start place.  I especially like this format, because it can provide very clear overview of all the LFB definition entities. For insntace, for the EtherPHYCop LFB, the original outline is like the format as  below. 
----
Inputs:
EtherPHYIn,  single input
frameExpected: EthernetAll /*an ethernet frame description that includes all kinds of ethernet frame types */
metadataExpected: none  
 
Outputs:
EtherPHYOut,  single output
frameProduced: EthernetII 
metadataProduced: PHYPortID
----
Components:
(default access property is read-write)

name: PHYPortID
type: uint32

name: AdminLinkSpeed 
type:LANSpeedType   /*include "auto" as the type value */
defaultValue:"auto"

name: OperLinkSpeed 
type:LANSpeedType 
access: read-only

name: AdminDuplexMode
type:DuplexType
defaultValue:"auto"

name: OperDuplexMode 
type:DuplexType 
access: read-only

name: AdminStatus
type:PortStatusValues
defaultValue:"down"

name: CarrierStatus
type:booleanType
access:read-only
defaultValue:"no"

name: PHYPortStats
type: PHYPortStatsType /*please comment that if it is needed and if is, what stats may include?*/
access: read-reset
----
Capabilities: 

name: SupportedLinkSpeed
type: array of LANSpeedTypes

name: SupportedDuplexMode
type: array of DuplexTypes
----
Events:

name: PHYPortStatusChanged

name: LinkSpeedChanged
----

Whereas, in the end, I gave up above thoguts because I have a thought that the "LFB description" is not a text for easy readability purpose, rather it is for the definitions of the LFB itself. To say this, it is to say the LFB description should avoid as much as possible duplications of  definitions for the LFB among the description and the XML file definitions. With this in mind, the current draft only deals with the LFB descriptions that mostly need more definitions with the help of the text. While for  some very obvious definitions like for  some capabilities or events, they are just defined in the XML file. 

I just thought that readers are expected to understand the LFB definitions mainly by reading the XML file and with synopsis helps. I never expected readers to understand the definitions by the desciption. Just like when we parse a software code, we may not expect the programmer to provide a manual as well as the source code. 

But, anyway, I agree to use the new format for the description of the LFBs if you all agree.

thanks,
Weiming

----- Original Message ----- 
From: "Jamal Hadi Salim" <[email-masked]>

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 27 Apr 2011 11:30:21 -0400

On Wed, Apr 27, 2011 at 10:18 AM, Wang,Weiming <[email-masked]> wrote:
> Actually I also think it is made easier to reader by sub-sections according to the LFB >individual properties. In fact I thought to do like this at beginning. I even thought of >two other ways like 1) with a picture to show the inputs and outputs. 2) with the >outline as we were discussing the LFB difinitions among authors at the very >beginning. The outline can be put at the LFB description start place.  I especially like >this format, because it can provide very clear overview of all the LFB definition >entities. For insntace, for the EtherPHYCop LFB, the original outline is like the >format as  below.

I think the document will grow in a big way if you went this way. It is
true this will be more formal - but you dont need to be 100% formal,
you leave that to the xml. Look at chapter 8 in the Model RFC.

>Whereas, in the end, I gave up above thoguts because I have a thought that the >"LFB description" is not a text for easy readability purpose, rather it is for the >definitions of the LFB itself. To say this, it is to say the LFB description should avoid >as much as possible duplications of  definitions for the LFB among the description >and the XML file definitions. With this in mind, the current draft only deals with the >LFB descriptions that mostly need more definitions with the help of the text. While >for  some very obvious definitions like for  some capabilities or events, they are just >defined in the XML file.
>
> I just thought that readers are expected to understand the LFB definitions mainly by >reading the XML file and with synopsis helps. I never expected readers to understand >the definitions by the desciption. Just like when we parse a software code, we may >not expect the programmer to provide a manual as well as the source code.
>

It is tough balance. I agree with you thinking but from experience the current
structuring is not working well. About everybody i had look at the document
found it very hard to follow. I had to print the xml and when i was reading
the document i cross reference.

> But, anyway, I agree to use the new format for the description of the LFBs if

I will leave it upto the authors to make the final decision. I feel i will be
shepherding this document at the end - hence my efforts are purely selfish
to make this readable by the reviewers so we dont waste time at that
stage (it could be very consuming and frustrating).

cheers,
jamal

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 27 Apr 2011 12:42:49 -0400

Let me try to describe the purpose of the <synopsis> and <description> 
clauses of the XML.
They are intended to be available to help a human being working with tools.
Imagine either a tool that is helping a programmer build CE logic, or a 
tool that is displaying the results of extracting the LFB structure of 
an FE.  The synopsis would appear in a tooltip.  The description would 
appear if someone asked for help about the LFB class.

Neither of those is supposed to be as extensive as the actual textual 
description in teh RFC< which provides all of the context, options, 
consideration, design issues, etc...

Yours,
Joel

---

From: "Chuanhuang Li" <[email-masked]>
Date: Fri, 29 Apr 2011 18:50:52 +0800

Hi, all
     I'm sorry for not continuing working on the lib these days, owing to feel not well with my health.
I'll complete to collate the LFB XML definition according Jamal's suggestion text file and previous 
discussion in the following days, and will soon post it on the list.

Yours,
Chuanhuang	

======= 2011-04-28 00:34:49 Joel M. Halpern, wrote: =======

>.

---

From: "Haleplidis Evangelos" <[email-masked]>
Date: Sun, 1 May 2011 01:36:29 +0300

Greetings to all,

Here is the readability suggestion for the EtherMacIn.

I hope I have more within the week.

Regards,
Evangelos Haleplidis.