diff options
author | Ulrich Müller <ulm@gentoo.org> | 2009-09-20 19:51:43 +0000 |
---|---|---|
committer | Ulrich Müller <ulm@gentoo.org> | 2009-09-20 19:51:43 +0000 |
commit | 64d530753717a3af369aa0b0b463019886d36281 (patch) | |
tree | 8fa9daa2c5876ca0df92b3a5329075428712040e /doc | |
parent | Fix order of sections. (diff) | |
download | eselect-64d530753717a3af369aa0b0b463019886d36281.tar.gz eselect-64d530753717a3af369aa0b0b463019886d36281.tar.bz2 eselect-64d530753717a3af369aa0b0b463019886d36281.zip |
Reformat documentation; add a local variables block for Emacs.
Remove overview.txt since it is redundant with user-guide.txt.
svn path=/trunk/; revision=671
Diffstat (limited to 'doc')
-rw-r--r-- | doc/developer-guide.txt | 330 | ||||
-rw-r--r-- | doc/overview.txt | 83 | ||||
-rw-r--r-- | doc/release-guide.txt | 20 | ||||
-rw-r--r-- | doc/user-guide.txt | 133 |
4 files changed, 262 insertions, 304 deletions
diff --git a/doc/developer-guide.txt b/doc/developer-guide.txt index b347b3e..76a8865 100644 --- a/doc/developer-guide.txt +++ b/doc/developer-guide.txt @@ -8,9 +8,10 @@ Introduction About eselect -------------- -eselect is a framework for simplifying and introducing consistency to the -various Gentoo ``foo-config`` and ``update-blah`` tools. It is an option for -developers who don't like reinventing the wheel, not a mandatory tool. +eselect is a framework for simplifying and introducing consistency to +the various Gentoo ``foo-config`` and ``update-blah`` tools. It is an +option for developers who don't like reinventing the wheel, not a +mandatory tool. Getting Started =============== @@ -18,19 +19,19 @@ Getting Started Introduction ------------ -When porting your application to use the eselect framework, you will generally -need to create a module. Often this can be heavily based upon an existing -module, so check to see whether there is something that does almost what you -need first (symlink handling is a good example of something that can be copied -rather than reinvented). +When porting your application to use the eselect framework, you will +generally need to create a module. Often this can be heavily based upon +an existing module, so check to see whether there is something that does +almost what you need first (symlink handling is a good example of +something that can be copied rather than reinvented). A Simple Module --------------- It's easiest to illustrate by example. Here's a simple module, named -``cow.eselect``. It has two actions, ``moo`` and ``think``, plus the standard -``help``, ``usage`` and ``version`` actions, and is installed to -``$(datadir)/eselect/modules/`` :: +``cow.eselect``. It has two actions, ``moo`` and ``think``, plus the +standard ``help``, ``usage`` and ``version`` actions, and is installed +to ``$(datadir)/eselect/modules/`` :: # Copyright 1999-2005 Gentoo Foundation @@ -108,22 +109,25 @@ It's easiest to illustrate by example. Here's a simple module, named echo "${@:-Am I a cow?}" | cowthink ${params} } -As you can see, the format is fairly similar to that of an ebuild -- it is a -bash script which is run in a special environment. This is intentional. There -are ``DESCRIPTION`` and ``VERSION`` variables globally which are used by -``eselect`` and some of the default action handlers, and a series of functions. - -.. Warning:: In ebuilds, global scope code can cause problems. In eselect - modules, global scope code is **absolutely forbidden**. Your module *will* be - sourced for tasks other than running your actions. For example, if - ``eselect modules list`` is executed, your module will be sourced to obtain - the description. Any code being run here would be a very bad thing. - -Unlike ebuilds, the function names are not fixed. Any function whose name starts -with ``do_`` is considered to be an action implementation. It is conventional to -have a ``describe_`` function for every ``do_`` function that gives a short -description of the function -- this is used for ``eselect modulename help``, -for example. The ``describe_action_options`` and ``describe_action_parameters`` +As you can see, the format is fairly similar to that of an ebuild -- it +is a bash script which is run in a special environment. This is +intentional. There are ``DESCRIPTION`` and ``VERSION`` variables +globally which are used by ``eselect`` and some of the default action +handlers, and a series of functions. + +.. Warning:: In ebuilds, global scope code can cause problems. + In eselect modules, global scope code is **absolutely forbidden**. + Your module *will* be sourced for tasks other than running your + actions. For example, if ``eselect modules list`` is executed, your + module will be sourced to obtain the description. Any code being run + here would be a very bad thing. + +Unlike ebuilds, the function names are not fixed. Any function whose +name starts with ``do_`` is considered to be an action implementation. +It is conventional to have a ``describe_`` function for every ``do_`` +function that gives a short description of the function -- this is +used for ``eselect modulename help``, for example. +The ``describe_action_options`` and ``describe_action_parameters`` functions are optional. .. Note:: If eselect is invoked as ``cow-config`` or ``cow-update`` (for @@ -132,49 +136,50 @@ functions are optional. Standard Action Names --------------------- -The following list contains suggested allowed names for actions. If there is no -suitable name on the list for your task, it is best to ask for the list to be -updated -- for consistency, it would be nice to have a standardised list of -action names. (The cow module, being a silly demonstration module, is exempt.) +The following list contains suggested allowed names for actions. +If there is no suitable name on the list for your task, it is best to +ask for the list to be updated -- for consistency, it would be nice to +have a standardised list of action names. (The cow module, being a silly +demonstration module, is exempt.) help - Display a help message. Automatic. + Display a help message. Automatic. usage - Display a usage message. Automatic. + Display a usage message. Automatic. version - Display the current version. Automatic. + Display the current version. Automatic. show - Used to display the current provider of a symlink, or the currently - installed module, or the current status. + Used to display the current provider of a symlink, or the currently + installed module, or the current status. list - Used to display all available providers of a symlink, or all available - modules. + Used to display all available providers of a symlink, or all + available modules. set - Used to set a new provider or a symlink. + Used to set a new provider or a symlink. enable - Used to enable an optional feature. + Used to enable an optional feature. disable - Used to disable an optional feature. + Used to disable an optional feature. scan - Read information off the current filesystem. + Read information off the current filesystem. update - Used to automatically select a new provider for a symlink (as opposed to - ``set``, which generally takes a parameter manually selecting the - provider) or to gather system information that is vital to further - actions. + Used to automatically select a new provider for a symlink (as + opposed to ``set``, which generally takes a parameter manually + selecting the provider) or to gather system information that is + vital to further actions. -.. Note:: You can override the ``help``, ``usage`` and ``version`` actions. They - are provided by default by ``lib/default.eselect``. You should only do this - with a good reason. Removing them is not a good idea, ``eselect`` assumes - that they exist. +.. Note:: You can override the ``help``, ``usage`` and ``version`` + actions. They are provided by default by ``lib/default.eselect``. + You should only do this with a good reason. Removing them is not + a good idea, ``eselect`` assumes that they exist. Utility Functions ================= -eselect provides many utility functions. These are useful for standardised -output formatting. Where possible, these should be used, especially for output. -If a standard function is not available for the output format required, consider -implementing one. +eselect provides many utility functions. These are useful for +standardised output formatting. Where possible, these should be used, +especially for output. If a standard function is not available for the +output format required, consider implementing one. The following categories of function are available by default: @@ -198,32 +203,33 @@ These are implemented in ``libs/core.bash``. The ``die`` Function ,,,,,,,,,,,,,,,,,,,, -The ``die`` function (which, unlike its ebuild counterpart, *can* be called from -within subshells) is used to exit with a fatal error. It should be invoked as -``die -q "Message to display"``. If the ``-q`` is not provided, a stacktrace -will be displayed -- this should never happen because of user input error, only -abnormal conditions. +The ``die`` function (which, unlike its ebuild counterpart, *can* be +called from within subshells) is used to exit with a fatal error. It +should be invoked as ``die -q "Message to display"``. If the ``-q`` is +not provided, a stacktrace will be displayed -- this should never happen +because of user input error, only abnormal conditions. The ``check_do`` Function ,,,,,,,,,,,,,,,,,,,,,,,,, -The ``check_do`` utility function checks that the first parameter is a function, -and then calls it with any additional parameters as its arguments. If the -function does not exist, ``die`` is called. Again, this is mostly internal. +The ``check_do`` utility function checks that the first parameter is +a function, and then calls it with any additional parameters as its +arguments. If the function does not exist, ``die`` is called. Again, +this is mostly internal. The ``do_action`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``do_action`` utility function is the correct way to call a utility function -which is defined in another module. The first parameter is the action, -additional parameters are passed as arguments. +The ``do_action`` utility function is the correct way to call a utility +function which is defined in another module. The first parameter is the +action, additional parameters are passed as arguments. The ``inherit`` Function ,,,,,,,,,,,,,,,,,,,,,,,, -The ``inherit`` function sources eselect library files based on their name. In -order to source the file ``libs/foo.bash`` you have to add ``inherit foo`` in -global scope of your module. +The ``inherit`` function sources eselect library files based on their +name. In order to source the file ``libs/foo.bash`` you have to add +``inherit foo`` in global scope of your module. The ``sed`` Function ,,,,,,,,,,,,,,,,,,,, @@ -238,63 +244,65 @@ These are implemented in ``libs/output.bash``. The ``write_error_msg`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``write_error_msg`` function displays an error message in the standard -format. It is similar to ``eerror``. +The ``write_error_msg`` function displays an error message in the +standard format. It is similar to ``eerror``. The ``write_warning_msg`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``write_warning_msg`` function displays a warning message in the standard -format. It is similar to ``ewarn``. +The ``write_warning_msg`` function displays a warning message in the +standard format. It is similar to ``ewarn``. The ``write_list_`` Functions ,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -To display a list, the ``write_list_`` family of functions should be used. Lists -should always start with a header, which can be displayed using -``write_list_start The Header``. +To display a list, the ``write_list_`` family of functions should be +used. Lists should always start with a header, which can be displayed +using ``write_list_start The Header``. -To display a numbered list, the ``write_numbered_list_entry`` function should be -used for each item. The first parameter is the list item number, the second is -the list item text (remember to quote this). +To display a numbered list, the ``write_numbered_list_entry`` function +should be used for each item. The first parameter is the list item +number, the second is the list item text (remember to quote this). -To display a keyword/value list, the ``write_kv_list_entry`` function should be -used. The first parameter is the key, the second the value. +To display a keyword/value list, the ``write_kv_list_entry`` function +should be used. The first parameter is the key, the second the value. The ``write_numbered_list`` function is a wrapper around -``write_numbered_list_entry`` that handles the numbering automatically. Each -parameter passed is displayed as a numbered list item, the first with index 1, -the second with index 2 and so on. The -m option can be used to specify a -negative report message that is output for an empty list. +``write_numbered_list_entry`` that handles the numbering automatically. +Each parameter passed is displayed as a numbered list item, the first +with index 1, the second with index 2 and so on. The -m option can be +used to specify a negative report message that is output for an empty +list. -If -p is passed as the first argument to these functions, 'plain' highlighting -is used. +If -p is passed as the first argument to these functions, 'plain' +highlighting is used. The ``highlight`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``highlight`` utility function can be used to emphasise some text which is -to be displayed by any of the above functions. A typical invocation might look -like: :: +The ``highlight`` utility function can be used to emphasise some text +which is to be displayed by any of the above functions. A typical +invocation might look like: :: write_list_start "This is $(highlight list) example" - write_kv_list_entry "First" "This is the first" - write_kv_list_entry "$(highlight Second)" "This is the $(highlight second) entry" + write_kv_list_entry "First" "This is the first entry" + write_kv_list_entry \ + "$(highlight Second)" "This is the $(highlight second) entry" write_kv_list_entry "Third" "$(highlight The end)" The ``highlight_warning`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``highlight_warning`` function is like ``highlight``, but for warnings. It -displays the text in question in red. +The ``highlight_warning`` function is like ``highlight``, but for +warnings. It displays the text in question in red. The ``highlight_marker`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -To mark a list entry as active/selected, the ``highlight_marker`` function -should be used. First argument is the list entry. The function places a -highlighted star (or its second argument instead, if set) behind the entry. -A typical invocation might look like: :: +To mark a list entry as active/selected, the ``highlight_marker`` +function should be used. First argument is the list entry. The function +places a highlighted star (or its second argument instead, if set) +behind the entry. A typical invocation might look like: :: for (( i = 0; i < ${#targets[@]}; i++ )); do [[ test_if_target_is_active ]] \ @@ -304,8 +312,8 @@ A typical invocation might look like: :: The ``space`` Function ,,,,,,,,,,,,,,,,,,,,,, -The ``space`` utility function takes a single integer parameter. It displays -that many space characters. +The ``space`` utility function takes a single integer parameter. +It displays that many space characters. Test Functions -------------- @@ -315,15 +323,16 @@ These are implemented in ``libs/tests.bash``. The ``has`` Function ,,,,,,,,,,,,,,,,,,,, -The ``has`` utility function is like Portage's ``hasq``. It returns true if and -only if the first parameter is equal to any of the remaining parameters. +The ``has`` utility function is like Portage's ``hasq``. It returns true +if and only if the first parameter is equal to any of the remaining +parameters. The ``is_function`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``is_function`` utility function returns true if and only if its parameter -exists and is a function. This is mostly used internally, but may have some use -for modules. +The ``is_function`` utility function returns true if and only if its +parameter exists and is a function. This is mostly used internally, but +may have some use for modules. The ``is_number`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,, @@ -338,14 +347,14 @@ These are implemented in ``libs/path-manipulation``. The ``basename`` Function ,,,,,,,,,,,,,,,,,,,,,,,,, -The ``basename`` function is a transparent bash-only replacement for the external -``basename`` application. +The ``basename`` function is a transparent bash-only replacement for the +external ``basename`` application. The ``dirname`` Function ,,,,,,,,,,,,,,,,,,,,,,,, -The ``dirname`` function is a transparent bash-only replacement for the external -``dirname`` application. +The ``dirname`` function is a transparent bash-only replacement for the +external ``dirname`` application. The ``canonicalise`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,, @@ -361,9 +370,9 @@ These are implemented in ``libs/manip.bash``. The ``svn_date_to_version`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``svn_date_to_version`` function can be used instead of manually keeping -track of ``VERSION``. It is safe to use in global scope. The canonical usage is -as follows: :: +The ``svn_date_to_version`` function can be used instead of manually +keeping track of ``VERSION``. It is safe to use in global scope. +The canonical usage is as follows: :: SVN_DATE='$Date: $' VERSION=$(svn_date_to_version "${SVN_DATE}" ) @@ -381,10 +390,11 @@ The ``store_config`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,, The ``store_config`` function saves a key/value pair in a given -configuration file which is passed as first argument. This file -is a bash script consisting only of key/value pairs and should not be altered -manually. Comments in the file will be deleted each time ``store_config`` is -called. The function is invoked as ``store_config filename key value``. +configuration file which is passed as first argument. This file is +a bash script consisting only of key/value pairs and should not be +altered manually. Comments in the file will be deleted each time +``store_config`` is called. The function is invoked as +``store_config filename key value``. The ``load_config`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,, @@ -396,10 +406,11 @@ and prints the associated value. The ``append_config`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``append_config`` function appends an item to an already stored value in the -modules configuration file. It uses ``load_config`` / ``store_config`` -internally and should be invoked as ``append_config filename key item``. Note that -the item will not be appended if it occurs in the key's value already. +The ``append_config`` function appends an item to an already stored +value in the modules configuration file. It uses ``load_config`` / +``store_config`` internally and should be invoked as +``append_config filename key item``. Note that the item will not be +appended if it occurs in the key's value already. Multilib Functions ------------------ @@ -409,10 +420,10 @@ These are implemented in ``libs/multilib.bash``. The ``list_libdirs`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``list_libdirs`` function returns a set of valid libdirs for the used -architecture. By default it uses /etc/ld.so.conf to obtain all valid libdirs. If -this fails due to a missing or broken file, this function uses ``uname`` to -determine the architecture. +The ``list_libdirs`` function returns a set of valid libdirs for the +used architecture. By default it uses /etc/ld.so.conf to obtain all +valid libdirs. If this fails due to a missing or broken file, this +function uses ``uname`` to determine the architecture. Package-Manager Functions ------------------------- @@ -422,63 +433,72 @@ These are implemented in ``libs/package-manager.bash``. The ``arch`` Function ,,,,,,,,,,,,,,,,,,,,, -The ``arch`` function returns the correct value of ${ARCH} for the current -system. If the package manager cannot provide this information, ``arch`` falls -back to a ``uname -m`` and ``uname -s`` based lookup-table. +The ``arch`` function returns the correct value of ${ARCH} for the +current system. If the package manager cannot provide this information, +``arch`` falls back to a ``uname -m`` and ``uname -s`` based +lookup-table. The ``envvar`` Function ,,,,,,,,,,,,,,,,,,,,,,,,, -The ``envvar`` function retrieves the contents of a configuration-environment -variable for a given package. The syntax is ``envvar ${package-name} -${var-name}``. +The ``envvar`` function retrieves the contents of a +configuration-environment variable for a given package. The syntax is +``envvar ${package-name} ${var-name}``. The ``best_version`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``best_version`` function returns the highest available version for a -given package dep atom. +The ``best_version`` function returns the highest available version for +a given package dep atom. The ``has_version`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``has_version`` function checks whether a given versioned package dep atom -is installed. +The ``has_version`` function checks whether a given versioned package +dep atom is installed. The ``get_repositories`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``get_repositories`` function returns a list of repositories known to the -package manager. +The ``get_repositories`` function returns a list of repositories known +to the package manager. The ``get_repo_news_dir`` Function ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -The ``get_repo_news_dir`` function returns the directory where to find GLEP 42 -news items for a given repository. +The ``get_repo_news_dir`` function returns the directory where to find +GLEP 42 news items for a given repository. A Basic Skeleton Library ======================== -The ``libs/skel.bash`` library provides for a simple eselect module to switch -between implementations of anything that installs to a ``lib*`` directory -(i.e., lib, lib32, lib64). This will satisfy the requirements for most cases in -which one must switch between providers of a certain library or any package -installing a library. +The ``libs/skel.bash`` library provides for a simple eselect module to +switch between implementations of anything that installs to a ``lib*`` +directory (i.e., lib, lib32, lib64). This will satisfy the requirements +for most cases in which one must switch between providers of a certain +library or any package installing a library. Creating a simple module ------------------------ -To use this library, all you need to do is create an eselect module containing -settings for the MODULE and IFACE variables. The MODULE variable is the name -used to refer to the implementations being switched in help text. The IFACE -variable indicates the subdirectory of /etc/env.d/ in which eselect files for -these implementations will be stored. - -Each package must install a symlink map using the ``add`` action. The map must -use relative symlinks, one source-destination mapping per line in the form -``source destination``. The source must be relative to the destination, not -absolute. Instead of using ``lib`` or ``lib64`` etc., you must use @LIBDIR@. -The ``libs/skel.bash`` library detects the proper library directory at runtime. - -.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. +To use this library, all you need to do is create an eselect module +containing settings for the MODULE and IFACE variables. The MODULE +variable is the name used to refer to the implementations being switched +in help text. The IFACE variable indicates the subdirectory of +/etc/env.d/ in which eselect files for these implementations will be +stored. + +Each package must install a symlink map using the ``add`` action. The +map must use relative symlinks, one source-destination mapping per line +in the form ``source destination``. The source must be relative to the +destination, not absolute. Instead of using ``lib`` or ``lib64`` etc., +you must use @LIBDIR@. The ``libs/skel.bash`` library detects the proper +library directory at runtime. + +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. indent-tabs-mode: nil +.. End: + +.. vim: set ft=glep tw=72 sw=4 et spell spelllang=en : diff --git a/doc/overview.txt b/doc/overview.txt deleted file mode 100644 index b45f7b3..0000000 --- a/doc/overview.txt +++ /dev/null @@ -1,83 +0,0 @@ -A Brief Overview of eselect -============================ - -eselect is a modular framework for writing configuration utilities. It consists -of: - -* A main program named ``eselect``. -* Various modules (``*.eselect`` files) which carry out different tasks. -* Several libraries which help ensure consistent behaviour and simplify the - creation of new modules. - -A module provides several actions. Actions typically either display some -information (``list`` and ``show`` actions are common) or update the system -somehow (for example, ``set`` and ``update``). Each module also provides -``help`` and ``usage`` actions which explains how to use the module. - -eselect is invoked as ``eselect <module> <action>``. Some actions take -additional arguments -- these are added to the commandline. - -Some modules install symlinks to the main program. eselect handles these -intelligently -- for example, it realises that ``profile-config list`` should be -treated as if the user had run ``eselect profile list``. - -Advantages for End Users and System Administrators --------------------------------------------------- - -For system administrators and end users, tools written as eselect modules offer -several advantages over the traditional 'write each tool from scratch' approach: - -Consistent user interface - eselect modules provide a consistent user interface. Thanks to eselect's - action framework, there is no longer any need to remember or look up dozens - of ``-x`` style switches for each tool. The output format used by modules is - also standardised. - -Consistent help format - All eselect modules provide easily accessible help documentation via the - ``help`` and ``usage`` actions. - -Consistent tool naming - There is no need to remember dozens of ``foo-config`` and ``update-blah`` - names. To see a list of available tools, simply run ``eselect`` with no - arguments. Of course, the ``foo-config`` style names are still available - (via symlinks) if you prefer. - -Guaranteed Support for ``$ROOT`` - For those of you using ``$ROOT``, you will not have to worry about whether a - particular tool can handle it. Support for ``$ROOT`` is required for all - eselect modules. - -Advantages for Developers and Package Maintainers -------------------------------------------------- - -Writing your tool as an eselect module rather than starting from scratch gives -you various benefits: - -Faster Development Time - Much of the work is already done for you. eselect provides a series of - libraries for common tasks, and the main ``eselect`` program handles most - of the hard work for you. All you need to do is provide the actions and any - domain-specific functions you require. - -Automatic Actions - The ``help`` and ``usage`` actions are automatically generated from your - actions, so there's no need to spend time worrying about keeping these - written and up to date. - -Easy Consistent Behaviour - Because most of the input, output and commandline handling is split off into - library functions, writing a 'standard' module which behaves consistently - with other tools is very simple. - -Familiar Format - For Gentoo developers, the eselect module format will be very familiar -- - it is a ``bash`` file with similar structure to ebuilds. - -Further Documentation ---------------------- - -Further user and developer documentation is included with the main eselect -distribution. - -.. vim: set ft=glep tw=80 sw=4 sts=4 et spell spelllang=en : .. diff --git a/doc/release-guide.txt b/doc/release-guide.txt index 40a1da7..9e37520 100644 --- a/doc/release-guide.txt +++ b/doc/release-guide.txt @@ -1,16 +1,16 @@ eselect Release Guide ====================== -.. Note:: This guide is intended for people who do ``eselect`` releases. It is - probably of no interest to the rest of you. +.. Note:: This guide is intended for people who do ``eselect`` releases. + It is probably of no interest to the rest of you. Update version in configure.ac. -Make sure ChangeLog is tidy. Add ChangeLog entry for updating configure.ac -and tagging the release. +Make sure ChangeLog is tidy. Add ChangeLog entry for updating +configure.ac and tagging the release. -Update NEWS file with a summary of changes mentioned in ChangeLog since the -last release. +Update NEWS file with a summary of changes mentioned in ChangeLog since +the last release. Do a test run in trunk/. :: @@ -43,4 +43,10 @@ Sign it (there may be a dist-sign target in the future). :: $ gpg --armor --detach-sign ${P}.tar.bz2 -.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. indent-tabs-mode: nil +.. End: + +.. vim: set ft=glep tw=72 sw=4 et spell spelllang=en : diff --git a/doc/user-guide.txt b/doc/user-guide.txt index dd19e05..5df9a9f 100644 --- a/doc/user-guide.txt +++ b/doc/user-guide.txt @@ -8,71 +8,80 @@ A Brief Overview Introduction ------------ -eselect is a tool for administration and configuration on Gentoo systems. It -_will_ modify the system's behaviour and should be used with care by the system -administrator. eselect is a modular framework for writing configuration -utilities. It consists of: +eselect is a tool for administration and configuration on Gentoo +systems. It _will_ modify the system's behaviour and should be used with +care by the system administrator. eselect is a modular framework for +writing configuration utilities. It consists of: * A main program named ``eselect``. * Various modules (``*.eselect`` files) which carry out different tasks. -* Several libraries which help ensure consistent behaviour and simplify the - creation of new modules. +* Several libraries which help ensure consistent behaviour and simplify + the creation of new modules. A module provides several actions. Actions typically either display some -information (``list`` and ``show`` actions are common) or update the system -somehow (for example, ``set`` and ``update``). Each module also provides -``help`` and ``usage`` actions which explain how to use the module. +information (``list`` and ``show`` actions are common) or update the +system somehow (for example, ``set`` and ``update``). Each module also +provides ``help`` and ``usage`` actions which explain how to use the +module. Some modules install symlinks to the main program. eselect handles these -intelligently -- for example, it realises that ``profile-config list`` should be -treated as if the user had run ``eselect profile list``. +intelligently -- for example, it realises that ``profile-config list`` +should be treated as if the user had run ``eselect profile list``. Advantages for End Users and System Administrators -------------------------------------------------- -For system administrators and end users, tools written as eselect modules offer -several advantages over the traditional 'write each tool from scratch' approach: +For system administrators and end users, tools written as eselect +modules offer several advantages over the traditional 'write each tool +from scratch' approach: + +Consistent user interface + eselect modules provide a consistent user interface. Thanks to + eselect's action framework, there is no longer any need to remember + or look up dozens of ``-x`` style switches for each tool. The output + format used by modules is also standardised. -Consistent UI - eselect modules provide a consistent user interface. Thanks - to eselect's action framework, there is no longer any need to remember or - look up dozens of ``-x`` style switches for each tool. The output format - used by modules is also standardised. Consistent help format - All eselect modules provide easily accessible help documentation via the - ``help`` and ``usage`` actions. + All eselect modules provide easily accessible help documentation via + the ``help`` and ``usage`` actions. + Consistent tool naming - There is no need to remember dozens of ``foo-config`` and ``update-blah`` - names. To see a list of available tools, simply run ``eselect`` with no - arguments. Of course the foo-config style are still available (via symlinks) - if you prefer them. + There is no need to remember dozens of ``foo-config`` and + ``update-blah`` names. To see a list of available tools, simply run + ``eselect`` with no arguments. Of course, the ``foo-config`` style + names are still available (via symlinks) if you prefer them. + Guaranteed support for ``$ROOT`` - For those of you using $ROOT, you will not have to worry about whether a - particular tool can handle it. Support for ``$ROOT`` is required for all - eselect modules. + For those of you using ``$ROOT``, you will not have to worry about + whether a particular tool can handle it. Support for ``$ROOT`` is + required for all eselect modules. Advantages for Developers and Package Maintainers ------------------------------------------------- -Writing your tool as an eselect module rather than starting from scratch gives -you various benefits: +Writing your tool as an eselect module rather than starting from scratch +gives you various benefits: Faster development time - Much of the work has already been done for you. eselect provides a series - of libraries for common tasks, and the main ``eselect`` program handles - most of the hard work for you. All you need to do is provide the actions and - any domain specific functions you require. + Much of the work has already been done for you. eselect provides a + series of libraries for common tasks, and the main ``eselect`` + program handles most of the hard work for you. All you need to do is + provide the actions and any domain-specific functions you require. + Automatic actions - The ``help`` and ``usage`` actions are automatically generated from your - actions, so there is no need to spend time worrying about keeping these - written up to date. + The ``help`` and ``usage`` actions are automatically generated from + your actions, so there is no need to spend time worrying about + keeping these written up to date. + Easy, consistent behaviour - Because most of the input, output and command line handling is split off - into library functions, writing a 'standard' module which behaves - consistently with other tools is very simple. + Because most of the input, output and command line handling is split + off into library functions, writing a 'standard' module which + behaves consistently with other tools is very simple. + Familiar format - For Gentoo developers, the eselect module format will be very familiar -- it - is a ``bash`` file with a structure that is quite similar to ebuilds. + For Gentoo developers, the eselect module format will be very + familiar -- it is a ``bash`` file with a structure that is quite + similar to ebuilds. Using eselect ============= @@ -82,35 +91,35 @@ Usage eselect should be called as shown below: :: - eselect [<global-options>] <module> <action> <options> + eselect [<global-options>] <module> <action> <options> -eselect features consistently named actions among most of its modules. There -is only one global option as of now; --no-colour, which asks eselect to stop -showing colored output. The following are standard action names -- each module -may provide a subset of these actions: +eselect features consistently named actions among most of its modules. +There is only one global option as of now; --no-colour, which asks +eselect to stop showing colored output. The following are standard +action names -- each module may provide a subset of these actions: help - Print the modules help screen. + Print the modules help screen. usage - Print information on how to invoke the modules actions. + Print information on how to invoke the modules actions. version - Print the modules version and other useful information. + Print the modules version and other useful information. list - Prints a set of selectable options. + Print a set of selectable options. show - Prints the currently active configuration(s). + Print the currently active configuration(s). set - Select one of the options offered by ``list``. + Select one of the options offered by ``list``. enable - Enable one of the module specific features. + Enable one of the module specific features. disable - Disable one of the module specific features. + Disable one of the module specific features. update - Like ``set``, but automatically selects an option rather than taking a - parameter. + Like ``set``, but automatically selects an option rather than taking + a parameter. scan - Gather information about the system and store it for future usage by the - module. + Gather information about the system and store it for future usage by + the module. A typical session will look like the following for most modules: :: @@ -126,4 +135,10 @@ A typical session will look like the following for most modules: :: You can usually set items either by name or by number. -.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. indent-tabs-mode: nil +.. End: + +.. vim: set ft=glep tw=72 sw=4 et spell spelllang=en : |