Breaking out documentation more

Change-Id: I79222dbb2b338e451fd8c76d06ab15911242d9e4 Reviewed-on: https://marduk.tchpc.tcd.ie:8443/124 Reviewed-by: <[email protected]> Tested-by: <[email protected]>
jcftang · Jun 30, 2011 · 3d92da7 · 3d92da7
1 parent d643ce9
commit 3d92da7
Show file tree

Hide file tree

Showing 9 changed files with 70 additions and 56 deletions.
diff --git a/doc/authors.mdwn b/doc/authors.mdwn
@@ -0,0 +1,11 @@
+## The upstream authors
+
+  - mpkg - <http://staff.e.kth.se/mpkg/index.html>
+  - cports - <http://www.caoslinux.org/> and <http://caoswiki.infiscale.org/>
+
+## The current authors
+
+ - Mainly staff from TCHPC
+   - The time is paid for by eINIS, HPCE2, OIP and maybe one or two
+     other projects that may be benefitting from the results of this
+     build/package system.
diff --git a/doc/contact.mdwn b/doc/contact.mdwn
@@ -2,3 +2,6 @@ Primary contacts for cports
 
 * Jimmy Tang <[email protected]>
 * Darach Golden <[email protected]>
+
+The primary contacts are the current [[authors]], the list of authors
+also contain a list of upstream authors.
diff --git a/doc/index.mdwn b/doc/index.mdwn
@@ -10,6 +10,18 @@
 
 """]]
 
+## About
+
+cports is a collection of Makefiles and macros for semi-automatic
+builds of various pieces of software. It also uses [[!google
+environment-modules]] to allow us to have multiple versions of software
+installed. Users can select which versions they want to use with the
+module system.
+
+cports primarily acts as documentation on how to build (some times
+pretty complicated) pieces of software, so the stack can be reproduced
+on different systems with some poking from the sysadmin.
+
 ## Why fork cports
 
  - Needed more than just one version of gcc, intel, pgi builds of
@@ -39,44 +51,17 @@
   - `MODULEFILE_CONFLICTS` (conflict package with itself)
   - `DO_RUN_TESTS` (testing of packages)
 
-## The upstream authors
-
-  - mpkg - <http://staff.e.kth.se/mpkg/index.html>
-  - cports - <http://www.caoslinux.org/> and <http://caoswiki.infiscale.org/>
-
-## The current authors
-
- - Mainly staff from TCHPC
-   - The time is paid for by eINIS, HPCE2, OIP and maybe one or two
-     other projects that may be benefitting from the results of this
-     build/package system.
-
 ##  What cports doesn't do 
 
  - It doesn't generate portable binaries
  - Provide good documentation on the modifications TCHPC has made
- - Support for people who use this :)
+ - Support for people who use this
  - Dependancy and conflict checking of the packages, the admin who is
    writing the package will need to do this
  - Work with non-gnu based tools (it's a fork and the original authors
    used and based everything on gnu make etc...)
 
-## Systems tested on
-
- - ScientificLinux 5.x (64bit)
- - ScientificLinux 5.x (32bit)
-
-### Systems that bootstrap works on, but not fully tested
-
- - ScientificLinux 4.x (32bit)
-   - not recommended to run in this environment unless necessary
-   - need to redefine F77 to use g77 instead if you need numerical packages to work
- - Debian 5.x (64bit)
-
-## Systems failed on
-
-- OSX 10.6 - doesn't have a gfortran by default, users must install
-  gfortran from a third party packaging system.
+There is also an [[old changelog]] with some of the initial changes that were made.
 
 ### Table of apps that require specific compilers 
 
@@ -103,28 +88,6 @@ gcc 4.1.2 unless otherwise stated
  - ghc
  - apache-ant
 
-## Changelog - OLD
-
-	- Fork of cports from caoslinux, which in turn is a fork of mpkg
-	- Fix up modulefile naming convention
-	- Fix up current target to add symlink to modulefile as well
-	  - reverted the linking to modulefile, it breaks things
-	  - also added uncurrent target
-	- Added open64 COMPILERS option
-	- Added F90 variables, to make sure a fortran90 compiler is selected when needed
-	- Extended the modulefile generation targets to include these variables
-	  - INCLUDE_PATH
-	  - CPLUS_INCLUDE_PATH
-	  - C_INCLUDE_PATH
-	  - LD_LIBRARY_PATH
-	  - LIBRARY_PATH
-	  - LD_RUN_PATH
-	  - PKG_CONFIG_PATH
-	  - PYTHONPATH
-	- New packages that TCHPC finds useful
-	- Added R modules in the same style the perl modules for convenience
-
-
 ## Misc Notes
 
  - [[packages]]

diff --git a/doc/install.mdwn b/doc/install.mdwn
@@ -1,6 +1,6 @@
 Once you have met the [[requirements]] continue with the following.
 
-## Installation and configuration
+### Installation and configuration
 
   - Unpack cports-?.tar.bz2 to somewhere (I usually put it into
     ${HOME}/develop/cports)
@@ -34,7 +34,7 @@ Once you have met the [[requirements]] continue with the following.
     and *make install* to get gettext and libiconv to behave
     correctly.
 
-## Proxies
+### Proxies
 
    - many people have a `http_proxy` variable set in their shell config.
      However make installs often fail on ftp download attempts. So you

diff --git a/doc/old_changelog.mdwn b/doc/old_changelog.mdwn
@@ -0,0 +1,18 @@
+- Fork of cports from caoslinux, which in turn is a fork of mpkg
+- Fix up modulefile naming convention
+- Fix up current target to add symlink to modulefile as well
+  - reverted the linking to modulefile, it breaks things
+  - also added uncurrent target
+- Added open64 COMPILERS option
+- Added F90 variables, to make sure a fortran90 compiler is selected when needed
+- Extended the modulefile generation targets to include these variables
+  - INCLUDE_PATH
+  - CPLUS_INCLUDE_PATH
+  - C_INCLUDE_PATH
+  - LD_LIBRARY_PATH
+  - LIBRARY_PATH
+  - LD_RUN_PATH
+  - PKG_CONFIG_PATH
+  - PYTHONPATH
+- New packages that TCHPC finds useful
+- Added R modules in the same style the perl modules for convenience
diff --git a/doc/requirements.mdwn b/doc/requirements.mdwn
@@ -1,4 +1,4 @@
-## Required software
+### Required software
 
  - gnu make
  - gcc, g++ and gfortran (and basic devel, compile tools etc...)
@@ -9,7 +9,7 @@
 you can do a "make check-environment" to see if you meet the basic
 requirements.
 
-## Required devel packages/software if you wish to build X11 programs
+### Required devel packages/software if you wish to build X11 programs
 
 This list was compiled from a SL55 machine
 
@@ -40,3 +40,5 @@ On a Debian 5.x system (this list isn't complete)
  - x11proto-render-dev
  - mesa-common-dev
  - freeglut3-dev
+
+cports is [[tested on systems|tested_systems]] at TCHPC.
diff --git a/doc/tested_systems.mdwn b/doc/tested_systems.mdwn
@@ -0,0 +1,16 @@
+## Systems tested on
+
+ - ScientificLinux 5.x (64bit)
+ - ScientificLinux 5.x (32bit)
+
+### Systems that bootstrap works on, but not fully tested
+
+ - ScientificLinux 4.x (32bit)
+   - not recommended to run in this environment unless necessary
+   - need to redefine F77 to use g77 instead if you need numerical packages to work
+ - Debian 5.x (64bit)
+
+## Systems failed on
+
+- OSX 10.6 - doesn't have a gfortran by default, users must install
+  gfortran from a third party packaging system.
diff --git a/doc/usage.mdwn b/doc/usage.mdwn
@@ -1,4 +1,4 @@
-## Basic Usage
+### Basic Usage
 
  - load up your cports module so that cports can see its own generated
    module files. 

diff --git a/doc/walkthrough.mdwn b/doc/walkthrough.mdwn
@@ -5,4 +5,5 @@ A walkthrough of the basic features of cports
 [[!inline feeds=no show=0 template=walkthrough pagenames="""
 	requirements
 	install
+	usage
 """]]
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,4 +5,5 @@ A walkthrough of the basic features of cports @@
     [[!inline feeds=no show=0 template=walkthrough pagenames="""
     	requirements
     	install
+    	usage
     """]]