[brussels-dev] [clearview-discuss] review for merged UV/Brussels dladm(1M) man page

[Terry Gibson]

[meem wrote:]
> In general, I presume most uses of "" are only for review and will be
> replaced with appropriate markup in the official version (Terry?)
> 

Yes, items within quotes are put in literal markup.  These appear in
courier (typewriter-like) font on docs.sun.com and in PDF.  On your
terminal, such terms might look the same as everything else if you
use the default pager.  For connoiseurs of man pages, I recommend
you set your PAGER variable as:

/usr/xpg4/bin/more -s

With this setting, items in literal font appear in bold.

Terry

> Subject: Re: [brussels-dev] [clearview-discuss] review for merged UV/Brussels 
dladm(1M) man page
> To: Sebastien Roy <Sebastien.Roy at sun.com>
> Cc: Terry.Gibson at sun.com, brussels-dev at opensolaris.org, clearview-discuss 
<clearview-discuss at opensolaris.org>
> MIME-version: 1.0
> Content-transfer-encoding: 7BIT
> X-PMX-Version: 5.2.0.264296
> X-Authentication-warning: dhcp-cbjs05-219-62.PRC.Sun.COM: meem set sender to 
peter.memishian at sun.com using -f
> 
> 
> Some additional comments, below:
> 
>  > NAME
>  >       dladm - administer data links
>  > 
>  > SYNOPSIS
>  >       dladm show-link [-pP] [-s [-i interval]] [-o field[,...]] [link]
>  >       dladm rename-link [-R root-dir] link new-link
>  > 
>  > 
>  >       dladm show-dev [-p] [-s [-i interval]] [-o field[,...]] [dev]
>  > 
>  > 
>  >       dladm delete-phys link
>  >       dladm show-phys [-pP] [-o field[,...]] [link]
>  > 
>  > 
>  >       dladm show-ether [-px] [-o field[,...]] [link]
> 
> show-ether probably belongs after show-wifi, since it's mactype-specific.
> 
>  >       Each dladm subcommand  operates  on  one  of  the  following
>  >       objects:
>  > 
>  >       link      Datalinks, identified by a name.
>  > 
>  > 
>  >       dev       Network devices, identified by concatenation of  a
>  >                 driver name and an instance number.
>  > 
>  > 
>  >       aggr      Aggregations of network devices, identified either
>  >                 by a name or an administratively-chosen key between 1 and
>  >                 999.
> 
> The mention of "aggr" here seems a bit strange since we no longer use it
> elsewhere in the manpage.  It might make sense to keep it given that it
> would simplify some of the descriptions of the aggr subcommands, but OTOH
> if we did that, we'd probably want to follow-suit with "vlan" and (one
> day) iptun.  (However, if we do decide to keep it, it should be changed to
> say "aggregations of datalinks".)
> 
>  >               CLASS
>  > 
>  >                   The class of the datalink.  dladm distinguishes
>  >                   between the following classes:
>  > 
>  >                   phys
>  > 
>  >                       A physical datalink.  The show-phys subcommand
>  >                       displays more detail for this class of datalink.
>  >                       For WiFi physical datalinks, the show-wifi
>  >                       subcommand will also display WiFi-specific
>  >                       information.
> 
> Seems like the WiFi sentence should be generalized given the arrival of
> show-ether.
> 
> 
>  >       dladm rename-link [-R root-dir] link new-link
>  > 
>  >           Rename "link" to "new-link".  This is used to give a link a
> 
> In general, I presume most uses of "" are only for review and will be
> replaced with appropriate markup in the official version (Terry?)
> 
>  >       dladm delete-phys link
>  > 
>  >           This command is used to delete the persistent configuration of
>  >           a link associated with physical hardware which has been removed
>  >           from the system.
> 
> This subcommand is also probably worthy of an example.
> 
>  >       dladm create-aggr [-t] [-R root-dir] [-P policy] [-L mode]
>  >       [-T time] [-u address] -l linkn ... link
> 
> "-l linkn ..." notation here needs to be updated to match add-aggr et al.
> 
>  >       dladm create-vlan [-ft] [-R root-dir] -l plink -v vlan-tag [link]
>  > 
>  >           Create a tagged VLAN link with tag "vlan-tag" over physical
>  >           link "plink".  The name of the VLAN link may be specified as
>  >           "link".
> 
> I could be mistaken, but IIRC the VLAN tag includes the VLAN ID -- and all
> that we allow to be specified here is the VLAN ID.  So I think "vlan-tag"
> should be "vid" and "tag" should be replaced with "ID".
> 
>  >               VID
>  > 
>  >                   The VLAN tag (ID) associated with the VLAN.
>  > 
> 
> Likewise, I think my earlier suggestion should be revised to just be "The
> ID associated with the VLAN".
> 
>  >    General Link Property
>  > 
>  >       The following general link property is supported:
>  > 
> 
> With the advent of "autopush", the above bit of text needs to be made
> plural.
> 
>  >       autopush
>  > 
>  > 	     Specifies the set of STREAMS modules to push on the
>  > 	     stream associated with a link when its DLPI device is
>  > 	     opened.  It is a space delimited list of modules.
> 
> [anchor] should probably also be mentioned.
> 
>  >       Example 7 Renaming a Link
>  > 
>  >       To rename the bge0 link to mgmt0, enter the following command:
>  > 
>  >         # dladm rename-link bge0 mgmt0
> 
> Should we mention that the link needs to be unused and that any persistent
> configuration outside of the datalink layer will need to be adjusted?
> 
> -- 
> meem