diff options
| author |   Sérgio Almeida <mephx.x@gmail.com> | 2009-09-04 21:46:55 +0100 |
|---|---|---|
| committer | Sérgio Almeida <mephx.x@gmail.com> | 2009-09-04 21:46:55 +0100 |
| commit | 0eb5725274342598dccdc2b1e1dacaaa51bc20f8 (patch) | |
| tree | bd8d329b99c453286777a6adf14e147452e3fea0 | |
| parent | Added beta bash completion module (diff) | |
| download | uselect.tar.gz uselect.tar.bz2 uselect.zip | |
Started Documentation in GuideXMLuselect
| -rw-r--r-- | uselect.xml | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/uselect.xml b/uselect.xml new file mode 100644 index 0000000..fdd9d1a --- /dev/null +++ b/uselect.xml @@ -0,0 +1,412 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide> + <title>Universal Select Tool</title> + <author title="Author"> + <mail link="mephx.x@gmail.com">Sérgio Almeida</mail> + </author> + <author title="Editor"> + <mail link="bicatali@gentoo.org">Sébastien Fabbro</mail> + </author> + <abstract> + This document is a complete reference guide for the end user of the + Universal Select Tool. + </abstract> + <chapter> + <title>Introduction</title> + <body> + <p> + The Universal Select Tool is an administration, configuration + and profiling tool for Gentoo systems. It's similar to the + already existing eselect tool but besides beeing written in + python it supports both user and system environment + capabilities. Besides beeing a lot faster than it's previous + bash implementation, python also makes it a lot easier to expand + it's code base with already implemented general action types. + </p> + <p> + The Universal Select Tool consists of two tools, the + selection tool 'uselect' and the profiling tool 'uprofile'. + </p> + </body> + </chapter> + <chapter> + <title>Selection Tool - uselect</title> + + <section> + <title>Overview</title> + <body> + <p> + The Selection Tool can be used to change system configuration + according to specially crafted Modules. This tool consists of + 3 components: + </p> + <ul> + <li>uselect tool</li> + <li>uselect modules</li> + <li>uselect module's actions</li> + </ul> + </body> + </section> + <section> + <title>Uselect Tool</title> + <body> + <p> + The uselect tool is a command line interface to use the uselect modules. + It features a very similar interface to the eselect's current interface. + It's quite faster to use because (of course) it's written in python and + because list and set arguments were thrown away. We will see more as + explained in Usage below. + </p> + </body> + <section> + <title>Usage</title> + <body> + <p>The uselect tool should be called with the below usage:</p> + <pre> + Options: + -v (*) Verbose Mode + -nc (*) No Colors + -version (*) Version Information + + Modules: + python (*) Python Version Switcher + bash (*) Bash Environment Utility + gcc (*) Python GCC Version Switcher + </pre> + </body> + </section> + <section> + <title>Wideness</title> + <body> + <p> + When running uselect as a regular user only the user's + settings will be changed. The Selection Tool makes use of a + new environment folder called '.uselect' localted in the + user's $HOME. The '.uselect/' folder structure is + automatically created, setup and maintained by uselect. + </p> + <p>'~/.uselect' sample folder structure:</p> + <pre> +.uselect/ + etc/ + completion.d/ + env.d/ + usr/ + bin/ + python -> /usr/bin/python2.6 + gcc -> /usr/bin/gcc-4.3 + bin/ + </pre> + <p>When running uselect as root the -global option will show up.</p> + <pre> + Options: + -v (*) Verbose Mode + -nc (*) No Colors + -version (*) Version Information + -global (*) Set Globally + </pre> + <p> + When this option is specified, changes done by actions are + set globally instead of changing root user's profile. + </p> + </body> + </section> + </section> + <section> + <title>Uselect Modules</title> + <body> + <p> + Modules are nothing more than groups of actions that help + change the system/user environment. When a module is specified + to uselect but no action is specified, an action list for the + specified module is shown as below: + </p> + <pre> + Module python: + Author: mephx.x@gmail.com Version: 0.1 + + Actions: + bin Change Python's Version + test Test Python Environment + env Some env test + </pre> + <p> + At this point Modules are still written in python. The goal is + to give module developers the ability to create modules in a + very easy way without knowing any specific language. When + 'enough' Action diversity is created, modules can be written + by using a markup language like XML or JSON. + </p> + </body> + </section> + <section> + <title>Uselect Actions</title> + <body> + <p> + When both a module and an action are specified, the action + lists it's available targets/option and it's usage. + </p> + <pre> + + Change Python's Version + + 0 - /usr/bin/python2.6 - (>) (*) + 1 - /usr/bin/python2.6-config - (>) (*) + 2 - /usr/bin/python2.5-config - (!) + 3 - /usr/bin/python2.5 - (!) + 4 - /usr/bin/python2.6-config - (>) (*) + 5 - /usr/bin/python2.5-config - (!) + + </pre> + <p> + Legend: + + <ul> + <li>(>) System's currently selected option</li> + <li>(*) User's currently selected option</li> + <li>(!) Unset Option</li> + </ul> + </p> + <p> + As you can notice, this python module's action has levels in + it's available targets. When you choose a nested target, + uselect automatically activates all superior levels of the + tree. + </p> + <p> + Example: + </p> + <pre> +$ uselect python bin + + Change Python's Version + + 0 - /usr/bin/python2.6 - (>) (*) + 1 - /usr/bin/python2.6-config - (>) (*) + 2 - /usr/bin/python2.5-config - (!) + +$ uselect python bin 1 +Setting /usr/bin/python2.6-config success! +Setting /usr/bin/python2.6 success! + </pre> + <p> + Targets can be specified either by it's index or by it's + complete name. + </p> + <p> + Example: + </p> + <pre> +$ uselect python bin 0 +Setting /usr/bin/python2.6 success! +$ uselect python bin /usr/bin/python2.6 +Setting /usr/bin/python2.6 success! + </pre> + </body> + </section> + </chapter> + <chapter> + <title>Profiling Tool - uprofile</title> + <section> + <title>Overview</title> + <body> + <p> + The Profiling tool can be used to create, set and change user + profiles. This tool is still in a PoC state and therefore few + options are still available. + </p> + <p> + The Profiling Tool consists of 2 components: + <ul> + <li>uprofile Tool</li> + <li>uprofile Profiles</li> + </ul> + </p> + </body> + </section> + <section> + <title>Uprofile Tool</title> + <body> + <p> + The uprofile tool is a command line interface to manage the + current folder's user profile. Uprofile features a similar + interface to uselect's one as can be seen in the Usage below. + </p> + </body> + <section> + <title>Usage</title> + <body> + <p> + <pre> +$ uprofile -help -list +Usage: uprofile [options] [profile] [action] + + Options: + -v (*) Verbose Mode + -nc (*) No Colors + -help (*) See this screen + -list (*) List Profiles + -version (*) Version Information + + Usage Examples: + uprofile (*) Activates Folder Profile. Fallback to user profile. + uprofile [profile] (*) See Details on [profile] + + Profiles: + folder (*) Sample Profile. + + </pre> + </p> + <p> + When called with no arguments, uprofile will activate the + current's folder profile. + </p> + <p> + When there exist mode than one profile in current folder, + uprofile can be used to switch between them. + </p> + <pre> +$ uprofile debug +Usage: uprofile [options] debug [action] + + Profile debug: + Author: mephx Version: 0.1 + Description: Sample Profile + + Actions: + activate Set this profile for this folder. + default Set this profile the default profile. + + </pre> + </body> + </section> + <section> + <title></title> + <body> + <p> + Profiles are set in a per-folder basis beeing each folder's + profile set by a '.uprofile/' directory similar to the + previously introduced '~/.uselect/' folder. Child folder's + behaviour is yet to be defined. Profile definition is done + in JSON. The default folder profile is set by + '.uprofile/folder.json'. Every '.json' file inside + '.uprofile/' directory is considered a profile. + </p> + <p> + Example Profile: + </p> + <pre> +{"profile": { + "description": "Sample Profile.", + "author": "mephx", + "version": "0.1", + "modules": { + "python": { + "actions": { + "bin": [ + "/usr/bin/python2.6", + "/usr/bin/python2.6-config" + ] + } + } + } +}} + </pre> + </body> + </section> + </section> + </chapter> + <chapter> + <title>Module Developing</title> + <section> + <title>Modules</title> + <body> + <p>This is an example of a simple module with no actions.</p> + <pre> +from umodule import * + +module = Module(name = "python", description = "Empty Module", version = "0.1", author ="foo@bar.com") + </pre> + </body> + </section> + <section> + <title>Actions</title> + <body> + <p> + Actions as in modules are created in the same way. Prior to the + action instantiation you have to add the Action to the Module + by using the "module.add_action(action)" function. + </p> + <pre> +action = Action (name = 'action', description = "Example Action", type = "sym") + +module.add_action(action) + </pre> + </body> + <section> + <title>Action Types</title> + <body> + <p> + Actions can have different types. Types are pre-defined and + pre-implemented action templates. Up to now only 3 types + are implemented. + </p> + </body> + <section> + <title>Runnable</title> + <body> + <p> + The Runnable type is a simple API so you can have actions + coded in any interpreted language. + </p> + <p> + add_parameter(String) + Add parameter to be displayed in the argument's usage. + <pre> action.add_parameter('[target]')</pre> + </p> + <p> + add_usage(String) + Add code to be evaluated when no arguments are specified. + <pre>test.add_usage("""#!/usr/bin/python +print "Usage can be multi-line!" +print 5 * "And can have dynamic options! You Choose!\n"""") + </pre> + </p> + <p> + add_code(String) + Add the action's main code. + <pre> +test.add_code("""#!/usr/bin/python +print "Test Action In Python!" +""") + </pre> + </p> + <p>Example Runnable Action:</p> + <pre> +test = Action (name = 'test', description = 'Runnable Action Test', type = 'runnable') + +test.add_parameter('[argument]') + +test.add_usage("""#!/usr/bin/python +print "Usage can be multi-line!" +print 5 * "And can have dynamic options! You Choose!\n" +""") + +test.add_code("""#!/usr/bin/python +print "Test Action In Python!" +""") + </pre> + </body> + </section> + <section> + <title>Sym</title> + </section> + <section> + <title>Env</title> + </section> + </section> + </section> + </chapter> + <date>2009-09-03</date> + <version>1</version> +</guide> |