Manpage_Style_Guide.txt

All manpages will include the following elements

0. Steps to Reading a Manpage
1. Manpage heading
2. NAME section
3. SYNOPSIS section
4. DESCRIPTION section
5. REQUIRED PARAMETERS (if any)
6. OPTIONAL PARAMETERS (if any)
7. EXAMPLES section
8. SEE ALSO section
9. AUTHORS section
10. BUGS section
11. COPYRIGHT section
12. NOTES section (if needed)

0. Steps to Reading a Manpage - a user should be able to quickly scan a manpage for information in the order that they need it. The manpage will answer the following questions top to bottom
	1. What is the name of the command and briefly what does it do?
	2. What is the Syntax of the command?
	3. What more information do I need about the command?
	4. What parameters do I HAVE to include when running it?
	5. What optional parameters can I use?
	6. How do I use it to accomplish common tasks?
	7. Who wrote this manpage?
	8. What other commands might be useful?
	9. Under what restrictions is it being distributed?
	10. What should I do if I find a bug in the command/manpage?
	11. Who owns the copyright to the manpage?
	12. Is there any after thoughts?


1. Manpage Heading

The Manpage Heading shall include the following items
	doctype
	man source
	man version
	man manual

 
2. NAME
 
The NAME section will have the name of the command which can contain no spaces. (e.g. xe-cd-list) followed by a hyphen and a short one sentence description.
 
	xe-cd-list - List CD images
 
 
3. SYNOPSIS
 
The SYNOPSIS section shows the command syntax. 
* All commands that provide the --minimal and --multiple options should include them here even if xe help does not.
* Parameters are encased in square brackets [] and parameter values in angle brackets <>
* Parameters between <> should be capitalized. 
* The command name should be bolded where ever it is used!



	*xe cd-list* [ params=<PARAMETER> ] [--minimal]

 
4. DESCRIPTION

The DESCRIPTION section describes the command and its uses. This can be as short or long as necessary. If there is ambiguity concerning the command more clarification is needed.


* When writing a description for a *-list command, use the following structure. 


	*xe network-list* displays networks and their parameters.

	Output can be filtered by using the *params* parameter and a value (separate multiple parameters with commas): ::
		*xe network-list params=PIF-uuids* +
		*xe network-list params=PIF-uuids,VIF-uuids,name-label,name-description*

	Output can be filtered by using parameter values and the desired value: ::
		*xe network-list bridge=xapi0*

	Append --minimal to display values for one parameter on a single line separated by commas: ::
		*xe network-list params="MTU" --minimal*


* When commands attempt to execute a function (*-param-clear) we will use the verbage - attempts.
	
	e.g xe pif-param-clear attempts to clear all values for a specific writable parameter for a PIF.
	
* Low level sub-commands are universal commands, so the same style can be applied to each set of commands (param-clear, param-remove, param-set, param-add, param-list, param-get). Use the style provided below for each sub-command. 

	*-param-clear*:
		- xe *-param-clear attempts to clear any writable parameter. Use xe *-list and xe *-param-list to identify writable parameters (RW, SRW, MRW)".
		
	*-param-remove*:
		- xe *-param-remove removes a key from a set parameter or key/value pairs from a map parameter. Use xe *-list and xe *-param-list to identify writable set or map parameters (SRW, MRW)".
		
	*-param-set*:
		- xe *-param-set sets writable parameters. Use xe *-list and xe *-param-list to identify writable parameters (RW, MRW). To add to a set parameter, use *-param-add. 
		
	*-param-add*:
		- xe *-param-add* adds a key or key/value pair to a writable set or map parameter. If Use xe *-list and xe *-param-list to identify writable set or map parameters (SRW, MRW).

	*-param-list*:
		- xe *-param-list* displays all parameters for a specific *. 

	
	*-param-get*:
		- xe *-param-get* returns a parameter or a key value for a specific *.
		
* All commands that provide the --minimal and --multiple options should should mention it here even if xe help does not.	


 
5. REQUIRED PARAMETERS
 
* List all required Parameters here with a very short description. Refer to xe help to determine required/optional parameters and double check.
* Parameter option syntax will use square brackets with each possible option separated by pipes.
	ethtool-autoneg=[ on | off ]

*uuid*
	Display CD UUIDs


 
6. OPTIONAL PARAMETERS

* List all optional parameters here with a very short description.

* Parameter option syntax will use square brackets with each possible option separated by pipes.
	ethtool-autoneg=[ on | off ]

* All List commands should use the word "Display" in their description. 
	*name-label*::
		Display CD name labels
	*name-description*::
		Display CD name descriptions
	*is-a-snapshot*::
		Display if a CD is a snapshot [ true | false ]

* All List commands should include the params=all option.
	*all*::
		Display all parameter values 

 * All commands that use the --multiple and/or --minimal options should include those options here
	*--minimal*::
	Specify --minimal to only show minimal output.
 


7. EXAMPLES

* Quote the variables used in the examples. 
* If examples have multiple lines - insert a line break by finishing the line with a space and a +  
* Include the following four example types if they're relevant to your comand. 
* Parameters between <> should be capitalized. 
* The param-add command should contain an example of setting a map parameter and an example of setting a set parameter.
* Order examples from least complicated to most complicated.
 
1. Filtering results based on params=parameter 
	xe vif-list params=uuid
2. Filtering results based on parameter=value 
	xe vif-list currently-attached="false"
3. Getting more information on parameter=<expensive field> using a param-get command 
	xe host-cpu-param-get uuid=<CPU UUID> param-name="utilisation"
4. Setting a map parameter
	xe vm-param-set uuid=<VM UUID> other-config:"install-repository=http://mirror.centos.org/centos/6/os/i386/"

 

8. SEE ALSO
 
List other commands that would be related and/or useful to the user. 
Also list xe help <command> as a second source. 

 
9. AUTHORS

The AUTHORS section should specify all the authors that worked on the manpage.

Manpage Author(s):: 
	[Author(s)]
 
 
10. BUGS

The BUGS sectin should include the following message. 
 
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.
 

11. COPYRIGHT
The COPYRIGHT message should give way to the author of the manpage. 

Copyright \(C)  2012 - Grant McWilliams
 
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
 
 
12. NOTES
 
NOTES should contain anything that didn't fall into other categories. For instance if a command did not work on Xenserver, Kronos or Zeus etc.


 
Example for List Commands
 
XE(1)
=======
:doctype: manpage
:man source:   	xe-cd-list 
:man version:  	{1}
:man manual:   	xe cd-list Manual


NAME
----
xe-cd-list - Lists CD images

SYNOPSIS
--------

*xe cd-list* [ params=<PARAMETER> ] [--minimal]


DESCRIPTION
-----------

*xe cd-list* displays cds and their parameters.

Output can be filtered by using the *params* parameter and a value (separate multiple parameters with commas): ::
	*xe cd-list params=uuid* +
	*xe cd-list params=uuid,name-label,name-description*

Append --minimal to display values for one parameter on a single line separated by commas: ::
	*xe cd-list params="name-label" --minimal*


OPTIONAL PARAMETERS
-------------------

*all*::
	Display all parameter values
*uuid*::
	Display CD UUIDs
*name-label*::
	Display CD name labels
*name-description*::
	Display CD name descriptions
*is-a-snapshot*::
	Display if a CD is a snapshot [ true | false ]
*snapshot-of*::
	Display UUID of snapshotted CD
*snapshots*::
	Display how many snapshots the CD has
*snapshot-time*::
	Display the time of the snapshot
*allowed-operations*::
	Display allowed operations 
*current-operations*::
	Display current operations 
*sr-uuid*::
	Display UUID of the ISO Storage Repository where the CD resides
*sr-name-label*::
	Display name-label of the ISO Storage Repository where the CD resides
*vbd-uuids*::
	Display any Virtual Block Device UUIDs
*crashdump-uuids*::
	Display any crash dump UUIDs
*virtual-size*::
	Display the virtual size in bytes
*physical-utilisation*::
	Display utilised size in bytes
*location*::
	Display the CD filename
*type*::
	Display the CD type [ User | System ]
*sharable*::
	Display if the CD is sharable [ true | false ]
*read-only*::
	Display if the CD is read-only [ true | false ]
*storage-lock*::
	Display if the disk is locked at the storage level [ true | false ]
*managed*::
	Display if managed [ true | false ]
*parent*::
	Display parent disk if CD is part of a chain
*missing*::
	Display if the ISO Storage Repository has reported CD missing [ true | false ]
*other-config*::
	Display additional configuration parameter values for CD
*xenstore-data*::
	Display data to be inserted into xenstore tree
*sm-config*::
	Display storage manager device config keys
*on-boot*::
	Display on-boot config
*allow-caching*::
	Display if caching is allowed [ true | false ]
*metadata-latest*::
	Display latest CD metadata
*metadata-of-pool*::
	Display pool metadata
*tags*::
	Display tags
*--minimal*::
	Specify --minimal to only show minimal output.

	

EXAMPLES
--------

To display all CD name-labels: ::
	*xe cd-list* params="name-label"

To display all parameters for all CDs: ::
	*xe cd-list* params="all"
	
To display minimal output for all CDs: ::
	*xe cd-list* --minimal



SEE ALSO
--------
*xe help cd-list*, *xe-vm-cd-add*(1), *xe-vm-cd-eject*(1), *xe-vm-cd-insert*(1), *xe-vm-cd-list*(1), *xe-vm-cd-remove*(1)


AUTHORS
-------
Manpage Author(s): ::
Grant McWilliams <grant@soundlinuxtraining.com>


BUGS
----
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.


COPYRIGHT
---------
Copyright \(C) 2012 - Grant McWilliams

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License"


 
XE(1)
=======
:doctype: manpage
:man source:   xe network-list
:man version:  {1}
:man manual:   xe network-list manual

NAME
-----
xe-network-list - Displays all networks and their parameters.

SYNOPSIS
--------
*xe network-list*  [ params=<PARAMETER> ] [--minimal]


DESCRIPTION
-----------

*xe network-list* displays networks and their parameters.

Output can be filtered by using the *params* parameter and a value (separate multiple parameters with commas): ::
	*xe network-list params=PIF-uuids* +
	*xe network-list params=PIF-uuids,VIF-uuids,name-label,name-description*

Output can be filtered by using parameter values and the desired value: ::
	*xe network-list bridge=xapi0*

Append --minimal to display values for one parameter on a single line separated by commas: ::
	*xe network-list params="MTU" --minimal*



OPTIONAL PARAMETERS
-------------------

*all*::
	Display all parameter values
*uuid*::
	Display network UUIDs
*name-label*::	
	Display network name-labels	
*name-description*::	
	Display network descriptions
*VIF-uuids*::	
	Display VIFs attached to networks
*PIF-uuids*:: 	
 	Display PIFs attached to networks
*MTU*::	
	Display network MTU values	
*bridge*::
	Display network bridge names
*blobs*::	
	Display binary data stores
*tags*::	
	Display writable tag parameters
*other-config:static-routes*::	
	Display comma seperated list of Static routes present on network [ <SOURCE NETWORK ADDRESS>/<CIDR MASK>/<NEXT HOP ADDRESS> ] 
*other-config:ethtool-autoneg*::
	Display ethernet Autonegotiation status [ on | off ]
*other-config:ethtool-rx*:: 
	Display receive checksum status [ on | off ]
*other-config:ethtool-tx*::
	Display transmit checksum status [ on | off ]
*other-config:ethtool-sg*:: 
	Display scatter gather status [ on | off ]
*other-config:ethtool-tso*::
	Display TCP segmentation offload status [ on | off ]
*other-config:ethtool-ufo*::
	Display UDP fragment offload status [ on | off ]
*other-config:ethtool-gso*::
	Display generic segmentation offload status [ on | off ]	
*--minimal*::
	Specify --minimal to only show minimal output.

EXAMPLES
--------

To display all parameters for all networks in a pool: ::
	*xe network-list* params="all"

To display all paramters for a specific network: ::
	*xe network-list* uuid=<NETWORK UUID> params="all"
	
To display *VIF-uuids* for a specific network: ::
	*xe network-list* uuid=<NETWORK UUID> params="VIF-uuids"
	
To display the *name-label* and *UUID* parameters of all networks with a *MTU* of 1500: ::
	*xe network-list* MTU="1500" params="name-label,uuid"


SEE ALSO
--------
*xe help network-list*, *xe-network-create*(1), *xe-network-destroy*(1), *xe-network-param-set*(1), *xe-network-param-add*(1), *xe-network-param-clear*(1), *xe-pif-list*(1)

AUTHORS
-------
Manpage Author(s): ::
Matthew Spah <spahmatthew@xenapiadmin.com>


BUGS
----
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.

COPYRIGHT
---------
Copyright \(C)  2012 - Matthew Spah
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License"


 
 

 
Example for Other Commands
 
XE(1)
=======
:doctype: manpage
:man source: xe-vif-create
:man version: {1}
:man manual: xe vif-create manual
 
NAME
----
*xe vif-create* - Create a virtual interface
 
SYNOPSIS
--------
*xe vif-create* vm-uuid=<VM UUID> network-uuid=<NETWORK UUID> device=<ETHERNET DEVICE NUMBER> [ mac=<MAC ADDRESS> ]
 
 
DESCRIPTION
-----------
 
*xe vif-create* create a new VIF interface for a VM on a network. A VIF interface created on a running VM needs to be attached to the VM using *xe vif-plug*. The resulting VIF interface UUID will be returned.
 
 
REQUIRED PARAMETERS
-------------------
 
*vm-uuid*::
	VM for the VIF. Use *xe vm-list* to obtain a list of VMs.
 
*network-uuid*::
	Network for the VIF. Use *xe network-list* to obtain a list of networks.
 
*device*::
	Machine-readable network interface number. (e.g. eth0)
 
 
 
OPTIONAL PARAMETERS
-------------------
 
*mac*::
	48-bit MAC Address. A MAC Address is autogenerated if one isn't provided.
 
 
EXAMPLES
--------
 
To check the allowed VIF devices for a VM: ::
	*xe vm-param-get* uuid=<VM UUID> param-name="allowed-VIF-devices"
 
To create a VIF interface on a running VM: ::
	*xe vif-create* vm-uuid=<VM UUID> device=<ETHERNET DEVICE NUMBER> network-uuid=<NETWORK UUID>   +
	*xe vif-plug* uuid=<VIF UUID>
 
To create a VIF interface on a halted VM: ::
	*xe vif-create* vm-uuid=<VM UUID> device=<ETHERNET DEVICE NUMBER> network-uuid=<NETWORK UUID>
 
 

 
SEE ALSO
--------
 
*xe-vif-list*(1), *xe-vif-destroy*(1), *xe-vif-param-set*(1), *xe-network-list*(1), *xe-vm-list*(1)
 
 
AUTHORS
-------
Manpage Author(s)::
	Matthew Spah < spahmatthew@gmail.com>
 
 
BUGS
----
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.
 
 
COPYRIGHT
---------
Copyright \(C)  2012 - Matthew Spah
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".


Examples of the low level commands

XE(1)
=======
:doctype: manpage
:man source:   xe network-param-set
:man version:  {1}
:man manual:   xe network-param-set manual

NAME
-----
xe-network-param-set - Set parameters for a network

SYNOPSIS
--------
*xe network-param-set* uuid=<NETWORK UUID> [ name-label=<NAME LABEL> ] [ name-description=<DESCRIPTION> ] [ MTU=<MTU SIZE> ] [ default-locking-mode=<LOCKING MODE> ]
										   [ other-config:<PARAMETER NAME>=<KEY VALUE> ]
	

DESCRIPTION
-----------
*xe network-param-set* sets read/write parameters for a network.


REQUIRED PARAMETERS
-------------------
*uuid*::
	Network UUID - Use *xe network-list* to obtain a list of network UUIDs.

OPTIONAL PARAMETERS
-------------------

*name-label*::
	Set name of network.
	
*name-description*::
	Set description of network.
	
*MTU*::
	Set MTU size for a network.

*default-locking-mode*::	
	Set switchport locking mode: default-lockingmode=*[ disabled | unlocked ]*
	
*other-config:static-routes*::
	Create a static route for a network. Seperate multiple routes using a comma. static-routes=*[ <SOURCE NETWORK ADDRESS>/<CIDR MASK>/<NEXT HOP ADDRESS> ]* 
		
*other-config:ethtool-autoneg*::
	Enable autonegotiation: ethtool-autoneg=*[ on | off ]*
	
*other-config:ethtool-rx*:: 
	Enable receive checksum: ethtool-rx=*[ on | off ]*
	
*other-config:ethtool-tx*::
	Enable transmit checksum: ethtool-tx=*[ on | off ]*
	
*other-config:ethtool-sg*:: 
	Enable scatter gather: ethtool-sg=*[ on | off ]*
	
*other-config:ethtool-tso*::
	Enable TCP segmentation offload: ethtool-tso=*[ on | off ]*
	
*other-config:ethtool-ufo*::
	Enable UDP fragment offload: ethtool-ufo=*[ on | off ]*
	
*other-config:ethtool-gso*::
	Enable generic segmentation offload: ethtool-gso=*[ on | off ]*
	

EXAMPLES
--------

To create a static route that would route traffic from 192.168.1.0/24 to the gateway of 192.168.0.1: ::
	*xe network-param-set* uuid=<Network UUID> other-config="static-routes=192.168.1.0/24/192.168.0.1"

To set the MTU size for a network: ::
	*xe network-param-set* uuid=<Network UUID> MTU=<MTU Size>

To set the network default-locking-mode to *disabled*: ::
	*xe network-param-set* uuid=<Network UUID> default-locking-mode="disabled"

SEE ALSO
--------
*xe-network-list*(1), *xe-network-create*(1), *xe-network-param-list*(1), *xe-network-param-remove*(1), *xe-pif-list*(1), *xe-vif-list*(1)



AUTHORS
-------
Manpage Author(s): ::
Matthew Spah <spahmatthew@xenapiadmin.com>


BUGS
----
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.

COPYRIGHT
---------
Copyright \(C)  2012 - Matthew Spah
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License"

XE(1)
=======
:doctype: manpage
:man source:   xe network-param-list
:man version:  {1}
:man manual:   xe network-param-list manual

NAME
----
xe-network-param-list - Lists all parameters for a network 

SYNOPSIS
--------
*xe network-param-list* uuid=<NETWORK UUID>

DESCRIPTION
-----------
*xe network-param-list* displays all parameters for a specific network. 


REQUIRED PARAMETERS
-------------------

*uuid*::
	Network UUID - Use *xe network-list* to obtain a list of network UUIDs.
	
EXAMPLES
--------
To display all parameters for a specific network: ::
	*xe network-param-list* uuid=<NETWORK UUID>

SEE ALSO
--------
*xe-network-create*(1), *xe-network-destroy*(1), *xe-network-param-remove*(1), *xe-network-param-set*(1), *xe-pif-list*(1), *xe-pool-vlan-create*(1)


AUTHORS
-------
Manpage Author(s): ::
Matthew Spah <spahmatthew@xenapiadmin.com>


BUGS
----
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.


COPYRIGHT
---------
Copyright \(C) 2012 - Matthew Spah
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License"


XE(1)
=======
:doctype: manpage
:man source:   xe network-param-get
:man version:  {1}
:man manual:   xe network-param-get manual

NAME
----
xe-network-param-get - Returns a parameter for a network

SYNOPSIS
--------
*xe network-param-get* uuid=<NETWORK UUID> param-name=<PARAMETER> [ param-key=<PARAMETER KEY> ]


DESCRIPTION
-----------
*xe network-param-get* returns a parameter or a key value for a specified network. 


REQUIRED PARAMETERS
-------------------
*uuid*::
	Network UUID - Use *xe network-list* to obtain a list of network UUIDs.

*param-name*::
	The network parameter to return.
	
OPTIONAL PARAMETERS
-------------------
*param-key*::
	The network key to return.  


EXAMPLES
--------
To display the *VIF-uuids* attached to a network: ::
	*xe network-param-get* uuid=<NETWORK UUID> param-name="VIF-uuids"
	
To display the *static-routes* present on a network: ::
	*xe network-param-get* uuid=<NETWORK UUID> param-name="other-config" param-key="static-routes"

To display the *default-locking-mode* parameter on a network: ::
	*xe network-param-get* uuid=<NETWORK UUID> param-name="default-locking-mode"

SEE ALSO
--------
*xe-network-list*(1), *xe-network-create*(1), *xe-network-param-list*(1), *xe-pif-list*(1), *xe-vif-list*(1), *xe-network-param-set*(1)

AUTHORS
-------
Manpage Author(s): ::
Matthew Spah <spahmatthew@xenapiadmin.com>

BUGS
----
For guidelines on submitting bug reports see http://wiki.xen.org/wiki/Reporting_Bugs_against_XCP. Submit bugs and general questions to xen-api@lists.xen.org.

COPYRIGHT
---------
Copyright \(C)  2012 - Matthew Spah
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License"