conf/documentation:

    -Punctuation fixes. A sentence ends with a full stop.
    -Introduce some more groups
    -Start writing the synopsis of a group as GROUP_name[doc] = "synopsis"
    -Fix quotes of variables

1 files changed, 57 insertions, 43 deletions

diff --git a/conf/documentation.conf b/conf/documentation.conf
index e0868eefe4..320361398e 100644
--- a/conf/documentation.conf
+++ b/conf/documentation.conf
@@ -1,39 +1,42 @@
-# this file holds documentation for known keys, possible values and their meaning
-# feel free to send updates and corrections to oe@handhelds.org
+# this file holds documentation for known keys, possible values and
+# their meaning. Please update, correct and extend this documentation.
+# Mail your changes to oe@handhelds.org
 
 # conf/bitbake.conf
-PREFERRED_VERSION[doc] = "Normally use it as PREFERRED_VERSION_package-name = \"\" to set the preferred \
-version of more than one version for the package-name is available."
+PREFERRED_VERSION[doc] = 'Normally use it as PREFERRED_VERSION_package-name = "" to set the preferred \
+version of more than one version for the package-name is available.'
 
-BUILD_ARCH[doc] = "The name of the building architecture. For example i686"
-BUILD_OS[doc] = "The operating system (in lower case) of the building architecture. For example \
-linux"
+BUILD_ARCH[doc] = "The name of the building architecture. E.g. i686."
+BUILD_OS[doc] = "The operating system (in lower case) of the building architecture. E.g \
+linux."
 BUILD_VENDOR[doc] = "FIXME"
 BUILD_SYS[doc] = "FIXME"
 BUILD_PREFIX[doc] = "FIXME"
 BUILD_CC_ARCH[doc] = "FIXME"
 
-HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH @see TARGET_ARCH @group base"
-HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS \
+HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH. @see TARGET_ARCH @group base"
+HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS. \
 @see TARGET_OS @group base"
-HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR @see TARGET_VENDOR"
+HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR. @see TARGET_VENDOR"
 HOST_SYS[doc] = "FIXME"
-HOST_PREFIX[doc] = "Normally same as the TARGET_PREFIX @see TARGET_PREFIX @group base"
-HOST_CC_ARCH[doc] = "Normally same as the TARGET_CC_ARCH @see TARGET_CC_ARCH @group base"
-HOST_NONSYSV[doc] = "Setable flag in local.conf to override SysV specific compiles when needed. 1 or 0 are usable values. See fakeroot-native for example."
-
-TARGET_ARCH[doc] = "Build for which architecture. Examples are arm, i686, sh3, mips, powerpc"
-TARGET_OS[doc]   = "Build for which Operating System. Currently possible values are \
-linux and linux-uclibc. When using linux-uclibc you might want to set USE_NLS_gcc-cross to \"no\"."
+HOST_PREFIX[doc] = "Normally same as the TARGET_PREFIX. @see TARGET_PREFIX @group base"
+HOST_CC_ARCH[doc] = "Normally same as the TARGET_CC_ARCH. @see TARGET_CC_ARCH @group base"
+HOST_NONSYSV[doc] = 'This flag can be set to "1" if the host system is not SysV compatible. E.g.\
+fakeroot-native will be build with tcp as IPC implementation.'
+
+TARGET_ARCH[doc] = "Build for which architecture. Examples are arm, i686, sh3, mips, powerpc."
+TARGET_OS[doc]   = 'Build for which Operating System. Currently possible values are \
+linux and linux-uclibc. When using linux-uclibc you might want to set USE_NLS_gcc-cross to "no".'
 TARGET_VENDOR[doc] = "FIXME"
-TARGET_SYS[doc] = "The target system is composed out of TARGET_ARCH,TARGET_VENDOR and TARGET_OS"
-TARGET_PREFIX[doc] = "The prefix for the cross compile toolchain. For example arm-linux-"
+TARGET_SYS[doc] = "The target system is composed out of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
+TARGET_PREFIX[doc] = "The prefix for the cross compile toolchain. E.g arm-linux- ."
 TARGET_CC_ARCH[doc] = "FIXME"
-TARGET_FPU[doc] = "Floating point option (mostly for FPU-less systems), can be 'soft' or empty" 
+TARGET_FPU[doc] = "Floating point option (mostly for FPU-less systems), can be 'soft' or empty \
+for hardware floating point instructions."
 
-PACKAGE_ARCH[doc] = "The architecture needed for using a resulting package. If you have \
+PACKAGE_ARCH[doc] = 'The architecture needed for using a resulting package. If you have \
 machine dependant configuration options in your bitbake file add a \
-PACKAGE_ARCH  = \"${MACHINE_ARCH}\" to the file"
+PACKAGE_ARCH  = "${MACHINE_ARCH}" to the file.'
 
 
 DATE[doc] = "The date the build was started Ymd"
@@ -42,37 +45,48 @@ DATETIME[doc] = "The date and time the build was started at"
 
 PN[doc] = "PN holds the name of the package (Package Name). It is gathered from the bitbake-file filename"
 PV[doc] = "PV holds the version of the package (Package Version). The default value is 1.0, it is \
-retrieved from the bitbake-file filename."
-PR[doc] = "PR is the revision of the package (Package Revision). By default it is set to r0"
+retrieved from the bitbake-file filename but can be changed."
+PR[doc] = "PR is the revision of the package (Package Revision). By default it is set to r0."
 PF[doc] = "Package name - Package version - Package revision (PN-PV-PR)"
 P[doc]  = "Package name - Package version (PN-PF)"
-S[doc] = "Directory that holds the sources to build, WORKDIR/PN-PV by default. The 'make' or equivalent command is run from here"
+S[doc] = "Directory that holds the sources to build, WORKDIR/PN-PV by default. The 'make' or equivalent command is run from this directory."
 SECTION[doc]  = "Section of the packages e.g. console/networking"
-PRIORITY[doc] = "Importance of package, default values are 'optional' or 'needed'"
-DESCRIPTION[doc] = "A small description of the package"
+PRIORITY[doc] = "Importance of package, default values are 'optional' or 'needed'."
+DESCRIPTION[doc] = "A small description of the package."
 LICENSE[doc] = "The license of the resulting package e.g. GPL"
-AUTHOR[doc] = "The author of the stuff contained in the package"
-MAINTAINER[doc] = "Maintainer of the .bb and the resulting package"
-HOMEPAGE[doc] = "Homepage of the package e.g. http://www.project.net"
+AUTHOR[doc] = "The author of the files installed."
+MAINTAINER[doc] = "Maintainer of the .bb file and the resulting package."
+HOMEPAGE[doc] = "Homepage of the package e.g. http://www.project.net."
+
+
+# dependencies
+GROUP_dependencies[doc] = "The keys in this group influence the dependency handling of BitBake \
+and the resulting packages."
+DEPENDS[doc]  = "Build time dependencies, things needed to build the package. @group dependencies"
+RDEPENDS[doc] = "Run time dependencies, things needed for a given package to run. @group dependencies"
+PROVIDES[doc] = "Names for additional dependencies that this package will provide. @group dependencies"
 
 
-DEPENDS[doc]  = "Build time dependencies, things needed to build the package"
-RDEPENDS[doc] = "Run time dependencies, things needed for a given package to run"
-PROVIDES[doc] = "Names for additional dependencies that this package will provide"
+# packaging
+GROUP_packaging[doc] = "The keys in this group influence the package building process. They influence \
+which packages will be generated and which files will be present in the generated packages."
+PACKAGES[doc] = "Names of packages to be generated. @group packaging"
+FILES[doc]    = "Files/Directories belonging to the package. @group packaging"
 
 
-PACKAGES[doc] = "Names of packages to be generated"
-FILES[doc]    = "Files/Directories belonging to the package"
 
+TMPDIR[doc] = "The temporary directory of openembedded holding work-, deploy, staging- and other directories."
+CACHE[doc]  = "The directory holding the cache of the metadata."
 
+GROUP_fetcher[doc] = "The key highly influence the fetcher implementations."
+DL_DIR[doc] = "The directory where tarballs will be stored. @group fetcher"
+CVSDIR[doc] = "The directory where cvs checkouts will be stored in. @group fetcher"
+GITDIR[doc] = "The directory where git clones will be stored. @group fetcher"
 
-TMPDIR[doc] = "The temporary directory of openembedded holding work-, deploy, staging- and some more dirs"
-CACHE[doc]  = "The directory holding the parsing cache."
-DL_DIR[doc] = "The directory where tarballs will be downloaded."
-CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
+STAMP[doc]   = "The directory that holds files to keep track of what was built."
+WORKDIR[doc] = "The directory where a concrete package will be unpacked and built."
+T[doc]       = "Temporary directory within the WORKDIR."
 
-STAMP[doc]   = "The directory that holds files to keep track of what was built"
-WORKDIR[doc] = "The directory where a concrete package will be unpacked and built"
-T[doc]       = "Temporary directory within the WORKDIR"
-ENABLE_BINARY_LOCALE_GENERATION[doc] = "Enable the use of qemu to generate locale information during build time on the host instead of runtime on the target. IF you have trouble with qemu you should make this an empty var"
+GROUP_locale[doc] = "Locale generation of the GNU libc implementation"
+ENABLE_BINARY_LOCALE_GENERATION[doc] = "Enable the use of qemu to generate locale information during build time on the host instead of runtime on the target. If you have trouble with qemu-native you should make this an empty var. @group locale"