Add documentation for both types of ethernet and wireless connections

6 files changed, 175 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index 72db45f..dc3427c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,6 @@
 DESTDIR=
 VERSION=2.2.0_B1
+VPATH = doc
 
 install:
 	install -d $(DESTDIR)/usr/lib/network/connections $(DESTDIR)/etc/network.d/examples \
@@ -26,6 +27,15 @@ install-wireless:
 	install -m755 src-wireless/netcfg-auto-wireless $(DESTDIR)/usr/bin
 	install -m755 src-wireless/net-auto $(DESTDIR)/etc/rc.d
 
+install-docs: docs
+	install -d $(DESTDIR)/usr/share/doc/netcfg
+	install -m644 doc/*html $(DESTDIR)/usr/share/doc/netcfg/
+	
+docs: doc/*
+	for doc in $(?); do \
+		pandoc $$doc -o $$doc.html;\
+	done
+
 tarball: 
 	sed -i "s/NETCFG_VER=.*/NETCFG_VER=$(VERSION)/g" src/netcfg
 	mkdir -p netcfg-$(VERSION)
@@ -36,10 +46,12 @@ tarball:
 
 upload: 
 	md5sum netcfg-$(VERSION)*gz > MD5SUMS.$(VERSION)
-	#scp netcfg-$(VERSION)*gz MD5SUMS.$(VERSION) archlinux.org:/home/ftp/other/netcfg/
+	scp netcfg-$(VERSION)*gz MD5SUMS.$(VERSION) archlinux.org:/home/ftp/other/netcfg/
 
 clean:
+	rm doc/*html
 	rm *gz
 	rm -rf netcfg-*$(VERSION)
 	rm -rf pkg
 	rm MD5SUMS*
+	
diff --git a/doc/.html b/doc/.html
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/.html
diff --git a/doc/ethernet b/doc/ethernet
new file mode 100644
index 0000000..9ede84b
--- /dev/null
+++ b/doc/ethernet
@@ -0,0 +1,46 @@
+% ETHERNET netcfg manuals 
+% Arch Linux
+%
+
+# ethernet Manual
+## Description
+This connection method uses the unmaintained net-tools (ifconfig) and dhcpcd to gain an IP address.
+
+## Options
+INTERFACE (required)
+:    The wireless interface to configure
+IP (required)
+:   Can be either 'static' or 'dhcp'.  Static requires IFOPTS at least.
+IFOPTS
+:   Arguments to pass to 'ifconfig'. 
+GATEWAY (requires IP of 'static')
+:   Set specified gateway
+### DNS
+DNS
+:   Array of DNS nameservers. Simply specify the IP's of each of the DNS nameservers. 
+DNS1, DNS2 (deprecated)
+:   Specify first and second nameservers.
+SEARCH
+:   "search" line for /etc/resolv.conf
+DOMAIN
+:   "domain" line for /etc/resolv.conf
+HOSTNAME
+:   Set the system hostname. Ensure any hostname is correctly referenced in /etc/hosts.
+### DHCP
+DHCLIENT
+:   yes/no. Use dhclient instead of dhcpcd. Defaults to no.
+DHCP_OPTIONS
+:   String. Any extra arguments to pass to the dhcp client, presently dhcpcd.
+DHCP_TIMEOUT
+:   Integer. Maximum time to try for a DHCP IP. Default is 10 seconds.
+
+### 802.11x Authentication
+AUTH8021X 
+:   Use 802.11x authentication. Enable with 'yes'. 
+WPA_CONF (required for an AUTH8021X of 'yes' only)
+:   Path to wpa_supplicant configuration. Defaults to '/etc/wpa_supplicant.conf'
+WPA_OPTS (optional for an AUTH8021X of 'yes')
+:   Extra arguments for wpa_supplicant not specified otherwise. Any option here must specify wpa_supplicant driver. Defaults to '-Dwired'. 
+
+## Examples
+See /etc/network.d/examples
diff --git a/doc/ethernet-subr b/doc/ethernet-subr
new file mode 100644
index 0000000..761505a
--- /dev/null
+++ b/doc/ethernet-subr
@@ -0,0 +1,54 @@
+% ETHERNET-IPROUTE netcfg manuals 
+% Arch Linux
+%
+
+# ethernet-iproute Connection manual
+## Description
+This connection method uses the iproute suite of tools and dhcpcd to gain an IP address.
+
+## Options
+INTERFACE (required)
+:    The wireless interface to configure
+IP (required)
+:   Can be either 'static' or 'dhcp'.  Static requires at least one of ADDR or IPCFG. 
+ADDR (requires IP of 'static')
+:   A single IP address to configure a static IP. For example:
+GATEWAY (requires IP of 'static')
+:   Set specified gateway
+IPCFG 
+:   Array of arguments to pass to 'ip'. The power of this options is that it allows both simple and complicated routing configurations, within the framework of netcfg.
+### DNS
+DNS
+:   Array of DNS nameservers. Simply specify the IP's of each of the DNS nameservers. 
+SEARCH
+:   "search" line for /etc/resolv.conf
+DOMAIN
+:   "domain" line for /etc/resolv.conf
+HOSTNAME
+:   Set the system hostname. Ensure any hostname is correctly referenced in /etc/hosts.
+### DHCP
+DHCP_OPTIONS
+:   String. Any extra arguments to pass to the dhcp client, presently dhcpcd.
+DHCP_TIMEOUT
+:   Integer. Maximum time to try for a DHCP IP. Default is 10 seconds.
+
+### 802.11x Authentication
+AUTH8021X 
+:   Use 802.11x authentication. Enable with 'yes'. 
+WPA_CONF (required for an AUTH8021X of 'yes' only)
+:   Path to wpa_supplicant configuration. Defaults to '/etc/wpa_supplicant.conf'
+WPA_OPTS (optional for an AUTH8021X of 'yes')
+:   Extra arguments for wpa_supplicant not specified otherwise. Any option here must specify wpa_supplicant driver. Defaults to '-Dwired'. 
+
+## Examples
+### Using ADDR and GATEWAY to set static IP and gateway
+
+    IP="static"
+    ADDR="192.168.1.23"
+    GATEWAY="192.168.1.1"
+ 
+### Using IPCFG to set a static IP and gateway with custom DNS
+
+    IP="static"
+    IPCFG=("addr add dev eth0 192.168.1.23/24 brd +" "route add default via 192.168.1.1")
+    DNS=("208.67.222.222" "208.67.220.220")
diff --git a/doc/wireless b/doc/wireless
new file mode 100644
index 0000000..20ced91
--- /dev/null
+++ b/doc/wireless
@@ -0,0 +1,33 @@
+% WIRELESS netcfg manuals 
+% Arch Linux
+%
+
+# 'wireless' Connection manual
+## Description
+This connection method uses wireless_tools and wpa_supplicant to configure a wireless network connection. 
+
+The new 'wireless-dbus' connection method is preferred over this 
+
+This connection uses the 'ethernet' connection after successful association and thus supports all of it's options. 
+
+## Options
+INTERFACE (required)
+:   The wireless interface to configure
+SECURITY (required for security of 'wep', 'wpa' or 'wpa-config')
+:   One of 'wpa', 'wep', 'none' or 'wpa-config'. Defaults to 'none'
+KEY (required for SECURITY of 'wpa' or 'wep' only)
+:   Wireless encryption key. 
+ESSID (required)
+:   Name of network to connect to.
+TIMEOUT (optional)
+:   Time to wait for association. Defaults to 15 seconds. 
+SCAN (optional)
+:   Scan for a wireless network rather than blindly attempting to connect. Hidden SSID networks do not appear in a scan. Enable with 'yes'. Defaults to 'no'.
+IWCONFIG (optional)
+:   Arguments to pass to iwconfig before attempting to configure the connection. For example, BSSID.
+
+### WPA options  
+WPA_CONF (for SECURITY of 'wpa-config' only)
+:   Path to wpa_supplicant configuration. Defaults to '/etc/wpa_supplicant.conf'
+WPA_OPTS 
+:   Extra arguments for wpa_supplicant not specified otherwise. Any option here must specify wpa_supplicant driver. Defaults to '-Dwext'. 
diff --git a/doc/wireless-dbus b/doc/wireless-dbus
new file mode 100644
index 0000000..918256d
--- /dev/null
+++ b/doc/wireless-dbus
@@ -0,0 +1,29 @@
+% WIRELESS-DBUS netcfg manuals 
+% Arch Linux
+%
+
+# 'wireless-dbus' Connection manual 
+## Description
+This connection method uses wpa_supplicant's dbus interface to configure a wireless network connection.
+
+This connection uses the 'ethernet-iproute' connection after successful association and thus supports all of it's options. 
+
+## Options
+INTERFACE (required)
+:   The wireless interface to configure
+SECURITY (required)
+:   One of 'wpa', 'wep', 'none' or 'wpa-config'
+KEY (required for SECURITY of 'wpa' or 'wep' only)
+:   Wireless encryption key. 
+ESSID (required)
+:   Name of network to connect to.
+TIMEOUT 
+:   Time to wait for association. Defaults to 15 seconds. 
+
+### WPA options
+WPA_CONF (for SECURITY of 'wpa-config' only)
+:   Path to wpa_supplicant configuration. Defaults to '/etc/wpa_supplicant.conf'
+WPA_DRIVER 
+:   wpa_supplicant driver to be used. Defaults to 'wext' 
+WPA_OPTS 
+:   Extra arguments for wpa_supplicant not specified otherwise.