I sent the message to the internal psarc alias last Friday. Resending to the external discussion alias...
--Hyon Hyon Kim wrote: > > Here is the project team's response on the isnsadm command line > argument discusssion. > > The team has a list of alternatives which has been discussed with the > UIRB owner. Most violate current guidance by CLIP and the CLIP > companion, but two are acceptable. The project team would like to > choose alternative F > below with rationale that is described subsequently. > > The team would appreicate guidance from PSARC in finalizing the > discussion (and constructing feedback to UIRB to clarify things for > future cases). > > The following is the summary, details follow. > > A) Existing proposal: UIRB Approved. PSARC doesn't like > > isnsadm add-dd --dd <dd name> <dd set name> # add dd to dd set > isnsadm add-node --node <node name> <dd name> # add node to dd > > B) Alternate 1: UIRB says not CLIP Companion recommended because of > mutually exclusive options for a single subcommand, and stylistic > inconsistency: > > isnsadm add --dd <dd name> <dd set name> > isnsadm add --node <node name> <dd name> > > C) Alternate 2: UIRB says not CLIP Companion recommended because of > non-hyphenated subcommands. Also, positional paramenters are not CLIP > Companion preferred: > > isnsadm adddd <dd name> <dd set name> > isnsadm addnode <node name> <dd name> > > D) Alternative 3: UIRB says not CLIP compliant for use of double-word > subcommands. Also, positional paramenters are not CLIP Companion > preferred: > > isnsadm add dd <dd name> <dd set name> > isnsadm add node <node name> <dd name> > > E) Penultimate Alternative: UIRB says positional paramenters are not > CLIP Companion preferred, but could be considered acceptable: > > isnsadm add-dd <dd set name> <dd name ...> > isnsadm add-node <dd name> <node name ...> > > F) Final Alternative: UIRB says acceptable, perhaps preferred though > it goes against some mild guidance in the CLIP Companion: > > isnsadm add-node --dd=<dd name> <node name> > isnsadm add-dd --dd-set=<dd set name> <dd name> > > ------------------ > > Historical background: > > PSARC 2003/126 iSCSI project (20030305_rick.mcneal) > UIRB 2004/636 iSCSI CLI (20040825_john.forte) > PSARC 2004/848 Remove SLP from iSCSI (20041223_eric.taylor) > SHARC 2005/066 iSCSI Management API (20050202_kenneth.davis) > PSARC 2005/307 iSNS Client Support for iSCSI (20050512_waikwan.hui) > PSARC 2005/441 iSCSI Target Project (20050725_rick.mcneal) > UIRB 2005/539 iSCSI Target CLI (20050919_rick.mcneal) > UIRB 2005/543 iSCSI MS/T CLI (20050920_david.weibel) > PSARC 2005/591 ISCSI MS/T CLI (20051011_david.weibel) > PSARC 2006/622 iSCSI/ZFS integration (20061103_adam.leventhal) > PSARC 2006/319 iSNS Server (20060516_victor.li) > UIRB 2006/527 iSNS Server CLI (20060907_victor.li) > UIRB 2006/674 iSNS Server BUI (20061205_gary.horton) > > 2005/441's CLI spec: > > Usage: iscsitadm create [-?] <OBJECT> [-?] [<OPERAND>] > iscsitadm create target <OPTIONS> <local-target> > iscsitadm create initiator <OPTIONS> <local-initiator> > iscsitadm create tpgt <local-tpgt> > Usage: iscsitadm list [-?] <OBJECT> [-?] [<OPERAND>] > iscsitadm list target [OPTIONS] [<local-target>] > iscsitadm list initiator [OPTIONS] [<local-initiator>] > iscsitadm list tpgt [OPTIONS] [<local-tpgt>] > ...etc... > > 2005/441's opinion says > > The other main issue discussed at commitment review was the > sytnax of the iscsitadm CLI and why it was not CLIP compli- > ant. The project team noted that iscsiadm had been approved > by the UIRB and it too was not CLIP compliant. The team > wanted the CLIs for iSCSI to be consistent. Hence, the > requirements regarding the syntax of the CLI became muddy to > the project team. After considerable discussion, the PSARC > members decided to approve the iscsitadm interface as is. > However, there was the strong desire of the members that a > follow on project be considered to bring the interface into > CLIP compliance. See PAC advice below regarding CLIP compli- > ance. Moreover, members stated that no future CLI would be > approved that utilizes the syntax that iscsiadm, iscsitadm > and mpathadm employ. > > 2. The PAC must consider funding a follow on project to > fix the syntax used by mpathadm, iscsiadm, and iscsi- > tadm to become CLIP compliant. Also, no future pro- > jects will be approved that employ the syntax used by > these CLIs. > > > In the issues for 2006/319: > > jdc-6 It seems awkward to have to specify the argument type twice > for the add-* and remove-*functions. In other words, > "add-dd --dd foo bar" seems redundant (the "dd" type of the > argument is specified twice), where either "add-dd foo bar" or > "add --dd foo bar" would be more natural. > > (If this is a CLIP problem, let's do what is usable rather > than what the standard says.) > > Charles LaBrec (UIRB case owner) concludes > > I don't mean to be overly pedantic, but given that the guidelines > were given scrutiny and approval by PSARC, I don't feel I have the > latitude to go against them without good justification, at least at > the UIRB. I've always felt that ARCs have the capability to > override, if they wish (and particularly PSARC, as it governs the > guidelines). The only thing I would ask is that there be guidance by > a change to CLIP and the companion so that I and project teams know > what is the correct direction. > > Hyon, John Plocher, Mark, and Charles LaBrec (UIRB) looked at several > alternatives: > > A) Existing proposal: > > isnsadm add-dd --dd <dd name> <dd set name> # add dd to dd set > isnsadm add-node --node <node name> <dd name> # add node to dd > isnsadm remove-dd --dd <dd name> <dd set name> # remove dd from dd set > isnsadm remove-node --node <node name> <dd name> # remove node from dd > > UIRB Approved. > > B) Alternate 1 > > isnsadm add --dd <dd name> <dd set name> # add dd to dd set > isnsadm add --node <node name> <dd name> # add node to dd > isnsadm remove --dd <dd name> <dd set name> # remove dd from dd set > isnsadm remove --node <node name> <dd name> # remove node from dd > > There is a strong recommendation in the CLIP Companion to avoid > having mutually exclusive sets of options for a given subcommand. > > This clarifies the usage lines and documentation, by making it > absolutely clear which options go with which subcommand. In the > above case, the syntax is relatively simple, so it wouldn't be as > confusing. However, if more options start to be added to one form or > the other as the CLI evolves, then we get into this situation. > > The reference in the CLIP companion is in section 4.3 Subcommands: > > Q: My subcommand allows two very different uses, and each has > mutually unrelated options (e.g., myutility add [-gou] entity and > myutility add [-ghklr] entity > > A: You should revise your design. This suggests that you actually > have two different operations, and so should use different names. > > In this case, one would also have consider an overall "style" issue, > as it would seem awkward that some subcommands are single words, and > others hyphenated. If this alternative were chosen, it would seem > necessary to overhaul all the subcommand names to be consistent. > > C) Alternate 2: > > isnsadm adddd <dd name> <dd set name> > isnsadm addnode <node name> <dd name> > isnsadm removedd <dd name> <dd set name> > isnsadm removenode <node name> <dd name> > > Also from the CLIP Companion, 4.3 Subcommands: > > In some cases, a utility may operate on a type of object and its > sub-objects. In these cases, the subcommand should be a verb > followed by a hyphen followed by the name of the kind of object to > operate on. > > Q: I'd prefer to see verbNoun, verbnoun, "verb noun", "verb -t > noun" or "noun" as my subcommand form, rather than "verb-noun" > > A: This is one of these cases where all the possible design > alternatives provide roughly the same level of usability. The > design question then becomes: what is most consistent? Each of these > design possibilities has been closely examined, and the "verb-noun" > scheme seems to be the best. "verbNoun" involves mixed > capitalization which many dislike. "verbnoun" tends to produce names > that are hard to parse when unusual terms appear in them. "verb > noun" and "verb -t noun" don't really save any typing and add other > complexities. Finally, "noun" doesn't convey any sense of action. > > In the above, "adddd" seems to be the type of command one would > mistype a lot. > > This alternative also suffers from the usage of positional > parameters, which will be discussed later. > > D) Alternative 3: > > isnsadm add dd <dd name> <dd set name> > isnsadm add node <node name> <dd name> > isnsadm remove dd <dd name> <dd set name> > isnsadm remove node <node name> <dd name> > > Double-word subcommands are not CLIP #14 compliant, nor recommended > by the Companion: > > #14: The form ?command subcommand [options] [operands]? is > appropriate for grouping similar operations. Subcommand names should > follow the same conventions as command names as specified in > guidelines 1 and 2. > > #2: Utility names should include lower-case letters (the lower > character classification) and digits only from the portable > character set. [Subsequently relaxed to include the hyphen by the > Companion] > > Q: I'd prefer to see ... "verb noun", ... as my subcommand form, > rather than "verb-noun" > > A: This is one of these cases where all the possible design > alternatives provide roughly the same level of usability. The design > question then becomes: what is most consistent? Each of these design > possibilities has been closely examined, and the "verb-noun" scheme > seems to be the best. .... "verb noun" and "verb -t noun" don't > really save any typing and add other complexities.... > > E) Penultimate Alternative > > isnsadm add-dd <dd set name> <dd name ...> > isnsadm add-mode <dd name> <node name ...> > isnsadm remove-dd <dd set name> <dd name ...> > isnsadm remove-node <dd name> <nodename ...> > > Team: The user has to remember the order since there is no option > involved. zpool has the simliar syntax. > > In the CLIP Companion, under 4.6 Operands: > > Q: I'd like to specify things with operands in a particular order. > Rather than using required options, I'd like to say that operand #1 > is one thing, operand #2 is another thing, and so on. > > A: These are called "positional parameters". In general, these seem > to be a bad idea. More than two positional parameters is hard for > people to remember. In the general case, even two is difficult > because it is often hard to remember whether A goes before or after > B. One common utility which uses positional parameters reasonably > easily is cp, where the last operand is the destination while the > preceding are all the things to be moved. Yet, you have probably on > occasion not specified the destination item and so moved all the > files into some other location than you intended. This demonstrates > that this good case can still cause problems. In general, we > strongly recommend the use of options (even required options) rather > than positionally-significant operands because this reduces the > usability problems that positional ones involve. > > In this case if you think along the lines of: "since I can add more > than one dd name, the first is the set and the rest are the dd's", > then the syntax makes some sense. > Note, however, that this is opposite to the rationale used in the > far more commonly used utilities mv and cp, where it's the last one > that is the container (i.e., directory)... > > F) Final Alternative: > > isnsadm add-node --dd=<dd name> <node name> > isnsadm add-dd --dd-set=<dd set name> <dd name> > isnsadm remove-node --dd=<dd name> <node name> > isnsadm remove-dd --dd-set=<dd set name> <dd name> > > UIRB: "preferred" > > The CLIP companion is not very specific on the issue of whether the > operands of a command should refer to the "noun" of the subcommand > or whether the noun should be referred to in an option. However, an > example in the Companion shows the latter, which was the rationale > for preferring the CLI syntax that was approved: > > | qsset create myset|| > qsset add-drive -q newdrive myset > > [ using "long-option notation", the above might look like: ] > qsset add-drive --drive=newdrive myset > | > > On reflection, considering this from the principle of consistency > and the principle of least surprise, I believe this guidance is > suspect, and leads to at least part of the issue raised by the PSARC > review. > > It would seem preferred to have the operands match the object type > specified by the "noun". This would eliminate confusion similar to > that raised by the discussion for positional parameters--otherwise, > users have to remember for each subcommand which argument is the > option, and which is the operand. Secondly, it allows for a CLI to > extend itself if the design at first only has some kind of "global > collection" and later adds "named collections". In other words, > "qsset add-drive newdrive" might be an acceptable design initially, > and then when named sets are created, the option referring to the > set can then simply be added. This is also extensible to situations > where an object might be added to more than one class of collection. > > If this rationale is accepted, the UIRB would like to consider it a > precedent for future reviews.|| > > > > >
