commit: 1d2b0dece81ad2bf9ed7d37982e291060fbe93dc
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Aug 26 07:39:45 2015 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Aug 26 07:39:45 2015 +0000
URL: https://gitweb.gentoo.org/proj/eselect.git/commit/?id=1d2b0dec
Use sentence case in documentation.
* doc/developer-guide.txt:
* doc/user-guide.txt:
* doc/release-guide.txt: Use sentence case in headings.
ChangeLog | 6 +++
doc/developer-guide.txt | 106 ++++++++++++++++++++++++------------------------
doc/release-guide.txt | 2 +-
doc/user-guide.txt | 8 ++--
4 files changed, 64 insertions(+), 58 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index da5fefd..ac3b25a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2015-08-26 Ulrich Müller <u...@gentoo.org>
+
+ * doc/developer-guide.txt:
+ * doc/user-guide.txt:
+ * doc/release-guide.txt: Use sentence case in headings.
+
2015-08-22 Ulrich Müller <u...@gentoo.org>
* configure.ac (EXTRAVERSION): Fix detection of git revision
diff --git a/doc/developer-guide.txt b/doc/developer-guide.txt
index 474437d..ddef9f7 100644
--- a/doc/developer-guide.txt
+++ b/doc/developer-guide.txt
@@ -1,5 +1,5 @@
===========================
-eselect Developer Reference
+eselect developer reference
===========================
About eselect
@@ -10,7 +10,7 @@ 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
+Getting started
===============
Introduction
@@ -22,7 +22,7 @@ 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
+A simple module
---------------
It's easiest to illustrate by example. Here's a simplified version of
@@ -164,7 +164,7 @@ All modules contributed to eselect should have a header
indicating
copyright. This must be an exact copy of the header in the above
example (except for the years, of course).
-Standard Action Names
+Standard action names
---------------------
The following list contains suggested allowed names for actions.
@@ -205,7 +205,7 @@ scan
You should only do this with a good reason. Removing them is not
a good idea, ``eselect`` assumes that they exist.
-Utility Functions
+Utility functions
=================
eselect provides many utility functions. These are useful for
@@ -215,24 +215,24 @@ output format required, consider implementing one.
The following categories of function are available by default:
-* General Utility Functions
-* Output Utility Functions
-* Test Functions
-* Path-Manipulation Functions
-* Manipulation Functions
-* Configuration Functions
-* Multilib Functions
-* Package-Manager Functions
+* General utility functions
+* Output utility functions
+* Test functions
+* Path-manipulation functions
+* Manipulation functions
+* Configuration functions
+* Multilib functions
+* Package-Manager functions
To use any of the other functions, you have first to ``inherit`` the
-corresponding library file. (cf: `The inherit Function`_)
+corresponding library file. (cf: `The inherit function`_)
-General Utility Functions
+General utility functions
-------------------------
These are implemented in ``libs/core.bash``.
-The ``die`` Function
+The ``die`` function
,,,,,,,,,,,,,,,,,,,,
The ``die`` function (which, unlike its ebuild counterpart, *can* be
@@ -241,7 +241,7 @@ 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`` function
,,,,,,,,,,,,,,,,,,,,,,,,,
The ``check_do`` utility function checks that the first parameter is
@@ -249,43 +249,43 @@ 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`` 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 ``inherit`` Function
+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 ``sed`` Function
+The ``sed`` function
,,,,,,,,,,,,,,,,,,,,
The ``sed`` function is a wrapper around GNU ``sed``.
-Output Utility Functions
+Output utility functions
------------------------
These are implemented in ``libs/output.bash``.
-The ``write_error_msg`` Function
+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_warning_msg`` Function
+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_list_`` Functions
+The ``write_list_`` functions
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
To display a list, the ``write_list_`` family of functions should be
@@ -309,7 +309,7 @@ list.
If ``-p`` is passed as the first argument to these functions, 'plain'
highlighting is used.
-The ``highlight`` Function
+The ``highlight`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``highlight`` utility function can be used to emphasise some text
@@ -322,13 +322,13 @@ invocation might look like: ::
"$(highlight Second)" "This is the $(highlight second) entry"
write_kv_list_entry "Third" "$(highlight The end)"
-The ``highlight_warning`` Function
+The ``highlight_warning`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``highlight_warning`` function is like ``highlight``, but for
warnings. It displays the text in question in red.
-The ``highlight_marker`` Function
+The ``highlight_marker`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
To mark a list entry as active/selected, the ``highlight_marker``
@@ -341,7 +341,7 @@ behind the entry. A typical invocation might look like: ::
&& targets[i]=$(highlight_marker "${targets[i]}")
done
-The ``is_output_mode`` Function
+The ``is_output_mode`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``is_output_mode`` function returns true if and only if its
@@ -349,72 +349,72 @@ parameter is equal to eselect's output mode. Currently,
only the default
and ``brief`` output modes are defined, the latter corresponding to the
``--brief`` option.
-The ``space`` Function
+The ``space`` function
,,,,,,,,,,,,,,,,,,,,,,
The ``space`` utility function takes a single integer parameter.
It displays that many space characters.
-Test Functions
+Test functions
--------------
These are implemented in ``libs/tests.bash``.
-The ``has`` Function
+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 ``is_function`` Function
+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_number`` Function
+The ``is_number`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,
Returns true if and only if the parameter is a positive whole number.
-Path-Manipulation Functions
+Path-manipulation functions
---------------------------
These are implemented in ``libs/path-manipulation``.
-The ``basename`` Function
+The ``basename`` function
,,,,,,,,,,,,,,,,,,,,,,,,,
The ``basename`` function is a transparent bash-only replacement for the
external ``basename`` application.
-The ``dirname`` Function
+The ``dirname`` function
,,,,,,,,,,,,,,,,,,,,,,,,
The ``dirname`` function is a transparent bash-only replacement for the
external ``dirname`` application.
-The ``canonicalise`` Function
+The ``canonicalise`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``canonicalise`` function is a wrapper to either GNU ``readlink -f``
or ``realpath``.
-The ``relative_name`` Function
+The ``relative_name`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``relative_name`` function converts a path name (passed as its first
argument) to be relative to a directory (second argument). This can be
used to generate a relative symlink from absolute paths.
-Manipulation Functions
+Manipulation functions
----------------------
These are implemented in ``libs/manip.bash``.
-The ``svn_date_to_version`` Function
+The ``svn_date_to_version`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
If your module is kept in a CVS or subversion repository, then the
@@ -429,12 +429,12 @@ Then turn on SVN keyword expansion for the module: ::
svn propset svn:keywords "Date" modules/foo.eselect
-Configuration Functions
+Configuration functions
-----------------------
These are implemented in ``libs/config.bash``.
-The ``store_config`` Function
+The ``store_config`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``store_config`` function saves a key/value pair in a given
@@ -444,14 +444,14 @@ 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
+The ``load_config`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``load_config`` function loads a stored value from the module's
configuration file. It is invoked as ``load_config filename key``
and prints the associated value.
-The ``append_config`` Function
+The ``append_config`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``append_config`` function appends an item to an already stored
@@ -460,12 +460,12 @@ value in the module's configuration file. It uses
``load_config`` /
``append_config filename key item``. Note that the item will not be
appended if it occurs in the key's value already.
-Multilib Functions
+Multilib functions
------------------
These are implemented in ``libs/multilib.bash``.
-The ``list_libdirs`` Function
+The ``list_libdirs`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``list_libdirs`` function returns a set of valid libdirs for the
@@ -473,12 +473,12 @@ 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
+Package-manager functions
-------------------------
These are implemented in ``libs/package-manager.bash``.
-The ``arch`` Function
+The ``arch`` function
,,,,,,,,,,,,,,,,,,,,,
The ``arch`` function returns the correct value of the ``ARCH`` variable
@@ -486,32 +486,32 @@ for the current system. If the package manager cannot
provide this
information, ``arch`` falls back to a lookup-table based on the
``HOSTTYPE`` and ``OSTYPE`` bash variables.
-The ``envvar`` Function
+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 ``best_version`` Function
+The ``best_version`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``best_version`` function returns the highest available version for
a given package dep atom.
-The ``has_version`` Function
+The ``has_version`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``has_version`` function checks whether a given versioned package
dep atom is installed.
-The ``get_repositories`` Function
+The ``get_repositories`` function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
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
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
The ``get_repo_news_dir`` function returns the directory where to find
diff --git a/doc/release-guide.txt b/doc/release-guide.txt
index 05be1d5..3e23b13 100644
--- a/doc/release-guide.txt
+++ b/doc/release-guide.txt
@@ -1,4 +1,4 @@
-eselect Release Guide
+eselect release guide
=====================
.. Note:: This guide is intended for people who do ``eselect`` releases.
diff --git a/doc/user-guide.txt b/doc/user-guide.txt
index 686757d..8ec35c4 100644
--- a/doc/user-guide.txt
+++ b/doc/user-guide.txt
@@ -1,8 +1,8 @@
==================
-eselect User Guide
+eselect user guide
==================
-A Brief Overview
+A brief overview
================
Introduction
@@ -28,7 +28,7 @@ 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
+Advantages for end users and system administrators
--------------------------------------------------
For system administrators and end users, tools written as eselect
@@ -56,7 +56,7 @@ Guaranteed support for ``$ROOT``
whether a particular tool can handle it. Support for ``$ROOT`` is
required for all eselect modules.
-Advantages for Developers and Package Maintainers
+Advantages for developers and package maintainers
-------------------------------------------------
Writing your tool as an eselect module rather than starting from scratch
