From e3ad4eaecea712f491eb3627e82972a4e71c6bf5 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Apr 27 2011 19:51:30 +0000 Subject: Update repository documentation manual. --- diff --git a/Manual/Directories/trunk/Scripts/Functions.texi b/Manual/Directories/trunk/Scripts/Functions.texi index 01e8633..910e891 100755 --- a/Manual/Directories/trunk/Scripts/Functions.texi +++ b/Manual/Directories/trunk/Scripts/Functions.texi @@ -30,7 +30,7 @@ using the follwiing directory structure: @verbatim trunk/Scripts/Functions/Greet <-- The source location of greet function. -|-- greet_getArguments.sh <-- Defines command-line interface. +|-- greet_getOptions.sh <-- Defines command-line interface. |-- greet_sayGoodbye.sh <-- Defines specific action. |-- greet_sayHello.sh <-- Defines specific action. `-- greet.sh <-- Defines function initialization. @@ -81,7 +81,7 @@ following: function greet { # Define command-line interface. - greet_getArguments + greet_getOptions # Execute action name. if [[ $ACTIONNAM =~ "^${FUNCNAM}_[A-Za-z]+$" ]];then @@ -98,7 +98,7 @@ The first definition inside @code{greet} function is for variables that will be available along the whole execution environment of @code{greet} function. This time we didn't define any variable here so, we continued with definition of command-line interface, through -@code{greet_getArguments} function. +@code{greet_getOptions} function. The command-line interface of @code{greet} functionality defines how to interpret arguments passed from @command{centos-art.sh} script @@ -108,7 +108,7 @@ place by mean of @command{getopt} command and is written as the following code example describes: @verbatim -function greet_getArguments { +function greet_getOptions { # Define short options we want to support. local ARGSS="" @@ -139,6 +139,11 @@ function greet_getArguments { shift 2 ;; + --quiet ) + FLAG_QUIET='true' + shift 1 + ;; + -- ) # Remove the `--' argument from the list of arguments # in order for processing non-option arguments @@ -200,6 +205,7 @@ Some examples are illustrated below: Hello, World [centos@projects ~]$ centos-art greet --bye='World' Goodbye, World +[centos@projects ~]$ centos-art greet --bye='World' --quiet [centos@projects ~]$ @end verbatim @@ -248,6 +254,9 @@ two commands: @verbatim centos-art locale --update trunk/Scripts +@end verbatim + +@verbatim centos-art locale --edit trunk/Scripts @end verbatim diff --git a/Manual/Directories/trunk/Scripts/Functions/Prepare.texi b/Manual/Directories/trunk/Scripts/Functions/Prepare.texi index e8a8333..18b563a 100644 --- a/Manual/Directories/trunk/Scripts/Functions/Prepare.texi +++ b/Manual/Directories/trunk/Scripts/Functions/Prepare.texi @@ -2,15 +2,14 @@ This section describes the @code{prepare} functionality of @command{centos-art.sh} script and the preliminar steps you need to -follow in order to get your workstation ready for using the CentOS -Artwork Repository. +follow in order to get your workstation ready for using a working copy +of CentOS Artwork Repository. @subheading Description The @code{prepare} functionality of @command{centos-art.sh} script -verifies all the information required by the working copy of CentOS -Artwork Repository (e.g., packages of software, symbolic links, etc.) -does exist in your workstation. +provides the standard way of configuring the workstation you plan to +use for storing the working copy of CentOS Artwork Repository. The @code{prepare} functionality of @command{centos-art.sh} script is part of the CentOS Artwork Repository. So, in order to execute the @@ -19,16 +18,15 @@ need to have access to a working copy of CentOS Artwork Repository, first. Working copies of CentOS Artwork Repository are downloaded from the source repository and made available to you by mean of workstations. A workstation is a computer that you install and -configure (prepare) to do something. In this case, you pick a computer -and prepare it for working on the CentOS Artwork Repository. +configure (prepare) to do something. In this case, you pick up a +computer and prepare it for working on the CentOS Artwork Repository. @subsubheading Installing the workstation -Installing the workstation is the first step you need to perform for -using the CentOS Artwork Repository. In this step you make your -computer functional through an operating system. In this case, The -Community Enterprise Operating System; which is also know as The -CentOS Distribution or just CentOS, for short. +Installing the workstation is the first step you need to do. In this +step you make your computer functional through an operating system. In +this case, The Community Enterprise Operating System; which is also +know as The CentOS Distribution or just CentOS, for short. To install The CentOS Distribution you need to have the installation media somehow (e.g., CDs, DVDs, Pendrives, etc.). There are several @@ -56,17 +54,15 @@ password for it. This is the username you must use for everyday work inside your working copy of the CentOS Artwork Repository. @quotation -@strong{Caution} Do not use ever the @samp{root} username for your -everyday work inside the working copy of CentOS Artwork Repository. -It is dangerous and might provoke unreversable damages on your -workstation. +@strong{Caution} Do not use the @samp{root} username for your everyday +work inside the working copy of CentOS Artwork Repository. It is +dangerous and might provoke unreversable damages on your workstation. @end quotation -Once you've created the username for everyday work, there are some -environment variables that you can customize to fit your personal -needs (e.g., the text editor you'll use, the language the automation -scripts will use to print and translate output messages, the time -correction for your location, etc.). To customize these variables you +Once you've created the username for your everyday work, there are +some environment variables that you can customize to fit your personal +needs (e.g., default text editor, default locale information, default +time zone representation, etc.). To customize these variables you need to edit your profile file (i.e., @file{~/.bash_profile}) and set the redefinition there. Notice that you may need to logout and then do login again in order for the new variable values to take effect. @@ -197,9 +193,10 @@ once. This is specially useful to keep the link information syncronized. For example, considering you've added new brushes to or removed old brushes from your working copy of CentOS Artwork Repository, the link information related to those files need to be -updated in the @file{~/.gimp-2.2/brushes} directory too, in a way that -reflect the addition/deletion change that took place in your working -copy. The same is true for fonts, patterns and palettes components. +updated in the @file{~/.gimp-2.2/brushes} directory too, in a way the +addition/deletion change that took place in your working copy can be +reflected there, as well. The same is true for other similar +components like fonts, patterns and palettes components. @subheading Usage @@ -212,23 +209,30 @@ copy. The same is true for fonts, patterns and palettes components. @table @option @item --packages -Verify existence of software packages and install them if they aren't -installed yet. +Install/update software packages required by the working copy of +CentOS Artwork Repository. + +The process of software installation takes place through @command{sudo +yum} and the repository configuration currently set in your +workstation. + +Most of the software packages required by the working copy of CentOS +Artwork Repository are available on The CentOS Distribution and can be +installed using The CentOS Distribution installation media. The only +exception is Inkscape, the program used to manipulate +@acronym{SVG,Scalable Vector Graphics} files in the working copy. -This option provides the software required to manipulate files inside -the repository (e.g., image files, documentation files, translation -files, script files, etc.). Most of the software packages required by -the CentOS Artwork Repository are available on The CentOS Distribution -and can be installed using The CentOS Distribution installation media. -The only exception is the @file{inkscape}, the package you use to -manipulate @acronym{SVG,Scalable Vector Graphics} files. The -@file{inkscape} package isn't inside The CentOS Distribution or any of -The CentOS Project repositories neither, so you need to install it from -a third party repositories like @samp{RPMForge} or @samp{EPEL}. +The @file{inkscape} package isn't inside The CentOS Distribution or +any of The CentOS Project repositories neither, so you need to install +it from a third party repository like @samp{RPMForge} or @samp{EPEL}. +See page +@url{http://wiki.centos.org/AdditionalResources/Repositories/,The +CentOS Repositories}, to know how to configure third party +repositories in The CentOS Distribution. @item --link -Update connection between working copy and workstation through +Install/update connection between working copy and workstation through symbolic links. This option creates the @command{centos-art} command-line interface of @@ -273,8 +277,4 @@ Assume @samp{yes} to all confirmation questions. @item @ref{Directories trunk Scripts Functions} @item @ref{Directories trunk Scripts} @item @ref{Directories trunk} -@item -@url{http://wiki.centos.org/AdditionalResources/Repositories/,The -CentOS Repositories}, to know how to configure third party -repositories inside The CentOS Distribution. @end itemize diff --git a/Manual/Directories/trunk/Scripts/Functions/Tuneup.texi b/Manual/Directories/trunk/Scripts/Functions/Tuneup.texi index 889f183..e90de39 100755 --- a/Manual/Directories/trunk/Scripts/Functions/Tuneup.texi +++ b/Manual/Directories/trunk/Scripts/Functions/Tuneup.texi @@ -1,27 +1,41 @@ @subheading Goals -@itemize -@item ... -@end itemize +This section describes the @code{tuneup} functionality of +@command{centos-art.sh} script and general examples about file +maintainance inside a working copy of CentOS Artwork Repository. @subheading Description -@subsubheading Shell Script Files - -The @code{shell} functionality of @file{centos-art.sh} script helps -you to maintain bash scripts inside repository. For example, suppose -you've created many functionalities for @file{centos-art.sh} script, -and you want to use a common copyright and license note for -consistency in all your script files. If you have a bunch of files, -doing this one by one wouldn't be a big deal. In contrast, if the -amount of files grows, updating the copyright and license note for all -of them would be a task rather tedious. The @code{shell} functionality -exists to solve maintainance tasks just as the one previously -mentioned. - -When you use @code{shell} functionality to update copyright inside -script files, it is required that your script files contain (at least) -the following top commentary structure: +The @code{tuneup} functionality of @command{centos-art.sh} script +provides the standard way of maintaining files inside your working +copy of CentOS Artwork Repository. + +Tasks related to file maintainance are repetitive. You might find +yourself doing them time after time inside the working copy of CentOS +Artwork Repository. Some of these maintainance tasks are updating top +comments on shell scripts, creating table of contents for web pages, +updating metadata related to design models and remove unused +definitions on design models. + +The maintainance tasks are associated to file extensions. This way, +the @code{tuneup} functionality know what maintainance tasks should be +applied to what files inside the working copy of CentOS Artwork +Repository. For example, when you execute the @code{tuneup} +functionality, it makes a list of files based on supported extensions +(e.g., @file{.sh}, @file{.svg} and @file{.xhtml}) and apply +maintainance tasks file by file accordingly to its file extension. + +@subsubheading Maintaining @file{.sh} files + +If shell scripts are found, the @code{tuneup} functionality reads a +comment template +(@file{trunk/Scripts/Functions/Prepare/Config/shell_topcomment.sed}) +and applies it to the shell scripts, one by one. As result, all shell +scripts will end up having the same copyright and license information +the comment template does. + +In order for the comment template to be applied correctly, the shell +script you write must have the following structure: @verbatim 1| #!/bin/bash @@ -41,182 +55,100 @@ the following top commentary structure: 15| } @end verbatim -Relevant lines in the above structure are lines from 5 to 9. -Everything else in the file is left immutable. - -When you are updating copyright through @code{shell} -functionality, the @file{centos-art.sh} script replaces everything -in-between line 5 ---the first one matching @samp{^# Copyright .+$} -string--- and line 9---the first long dash separator matching @samp{^# --+$}--- with the content of copyright template instance. - -@quotation -@strong{Caution} Be sure to add the long dash separator that matches -@samp{^# -+$} regular expression @emph{before} the function -definition. Otherwise, if the @samp{Copyright} line is present but no -long dash separator exists, @file{centos-art.sh} will remove anything -in-between the @samp{Copyright} line and the end of file. This way you -may lost your function definitions entirely. -@end quotation - -The copyright template instance is created from one copyright template -stored in the @file{Config/tpl_forCopyright.sed} file. The template -instance is created once, and later removed when no longer needed. At -this moment, when template instance is created, the -@file{centos-art.sh} script takes advantage of automation in order to -set copyright full name and date dynamically. - -When you use @code{shell} functionality to update copyright, the first -thing @file{shell} functionality does is requesting copyright -information to user, and later, if values were left empty (i.e., no -value was typed before pressing @key{RET} key), the @file{shell} -functionality uses its own default values. - -When @code{shell} functionality uses its own default values, the final -copyright note looks like the following: +The comment template replaces all the lines between the +@samp{Copyright} line (e.g., line 5) and the first separator line +(e.g., line 9). Everything else in the file will remain immutable. -@verbatim - 1| #!/bin/bash - 2| # - 3| # doSomthing.sh -- The function description goes here. - 4| # - 5| # Copyright (C) 2003, 2010 The CentOS Project - 6| # - 7| # This program is free software; you can redistribute it and/or modify - 8| # it under the terms of the GNU General Public License as published by - 9| # the Free Software Foundation; either version 2 of the License, or -10| # (at your option) any later version. -11| # -12| # This program is distributed in the hope that it will be useful, but -13| # WITHOUT ANY WARRANTY; without even the implied warranty of -14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -15| # General Public License for more details. -16| # -17| # You should have received a copy of the GNU General Public License -18| # along with this program; if not, write to the Free Software -19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -20| # USA. -21| # -22| # ---------------------------------------------------------------------- -23| # $Id$ -24| # ---------------------------------------------------------------------- -25| -26| function doSomething { -27| -28| } -@end verbatim +From time to time, we use the @code{tuneup} functionality on the +`trunk/Scripts' directory structure to update the copyright and +license notice of all the shell scripts we have therein. -Relevant lines in the above structure are lines from 5 to 22. Pay -attention how the copyright line was built, and how the license was -added into the top comment where previously was just three dots. -Everything else in the file was left immutable. +@subsubheading Maintaining @file{.svg} files -To change copyright information (i.e., full name or year information), -run the @code{shell} functionality over the root directory containing -the script files you want to update copyright in and enter the -appropriate information when it be requested. You can run the -@code{shell} functionality as many times as you need to. +If scalable vector graphics are found, the @code{tuneup} functionality +reads a metadata template +(@file{trunk/Scripts/Functions/Tuneup/Config/svg_metadata.sed}) and +applies it to all files found, one by one. Immediatly after the +metadata template has been applied and, before passing to next file, +all unused definition are removed from file, too. -To change copyright license (i.e., the text in-between lines 7 and -20), you need to edit the @file{Config/tpl_forCopyright.sed} file, set -the appropriate information, and run the @code{shell} functionality -once again for changes to take effect over the files you specify. +The metadata we apply from the metadata template is created dynamicaly +using the file found absolute path, the workstation time information +and the @command{centos-art.sh} script copyright information as +reference. Additionally, the @emph{Creative Common +Distribution-ShareAlike 3.0 License} is also set in the metadata. -@quotation -@strong{Important} The @file{centos-art.sh} script is released as: +The elimination of unused definitions inside SVG files takes place +through the @option{--vacuum-defs} option of @command{inkscape} +command-line interface. -@verbatim -GNU GENERAL PUBLIC LICENSE -Version 2, June 1991 +Frequently, we use the @code{tuneup} functionality on the +@file{trunk/Identity/Models} and @file{trunk/Identity/Themes/Models} +directory structure to update metadata and remove unused definitions +from design models therein. + +@subsubheading Maintaining @file{.xhtml} files + +If web pages are found, the @code{tuneup} functionality transforms web +page headings to make them accessible through a table of contents. +The table of contents is expanded in place, wherever the @code{
} piece of code be in the page. -Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 675 Mass Ave, Cambridge, MA 02139, USA +Once the @code{
} piece of code has be expanded, +there is no need to put anything else in the page. You can run the +@code{tuneup} functionality everytime you update the heading +information so as to update the table of contents, too. + +In order for the @code{tuneup} functionality to transform headings, +you need to put headings in just one line using one of the following +forms: + +@verbatim +

Title

+

Title

+

Title

@end verbatim -Do not change the license information under which @file{centos-art.sh} -script is released. Instead, if you think a different license must be -used, please share your reasons at @email{centos-devel@@centos-art.sh} -mailing list. - -See file -@url{file:///home/centos/artwork/trunk/Scripts/COPYING,trunk/Scripts/COPYING}, -for a complete license description. -@end quotation - -@subsubheading SVG Files - -The @code{svg} functionality of @file{centos-art.sh} script helps you -to maintain scalable vector graphics (SVG) inside repository. For -example, suppose you've been working in CentOS default design models -under @file{trunk/Identity/Themes/Models/}, and you want to set common -metadata to all of them, and later remove all unused SVG defintions -from @samp{*.svg} files. Doing so file by file may be a tedious task, -so the @file{centos-art.sh} script provides the @code{svg} -functionality to aid you maintain such actions. - -The metadata used is defined by Inkscape 0.46 using the SVG standard -markup. The @file{centos-art.sh} script replaces everything -in-between @code{} tags with a -predefined metadata template we've set for this purpose. - -The metadata template was created using the metadata information of a -file which, using Inkscape 0.46, all metadata fields were set. This -created a complete markup representation of how SVG metadata would -look like. Later, we replaced every single static value with a -translation marker in the form @samp{=SOMETEXT=}, where -@code{SOMETEXT} is the name of its main opening tag. Later, we -transform the metadata template into a sed replacement set of commads -escaping new lines at the end of each line. - -With metadata template in place, the @file{centos-art.sh} script uses -it to create a metadata template instance for the file being processed -currently. The metadata template instance contains the metadata -portion of sed replacement commands with translation markers already -traduced. In this action, instance creation, is where we take -advantage of automation and generate metadata values like title, date, -keywords, source, identifier, and relation dynamically, based on the -file path @file{centos-art.sh} script is currently creating metadata -information for. - -With metadata template instance in place, the @file{centos-art.sh} -script uses it to replace real values inside all @samp{.svg} files -under the current location you're running the @file{centos-art.sh} -script on. Default behaviour is to ask user to enter each metadatum -required, one by one. If user leaves metadatum empty, by pressing -@key{RET} key, @file{centos-art.sh} uses its default value. - -Many of the no-longer-used gradients, patterns, and markers (more -precisely, those which you edited manually) remain in the -corresponding palettes and can be reused for new objects. However if -you want to optimize your document, use the @samp{Vacuum Defs} command -in @samp{File} menu. It will remove any gradients, patterns, or -markers which are not used by anything in the document, making the -file smaller. - -If you have one or two couple of files, removing unused definitions -using the graphical interface may be enough to you. In contrast, if -you have dozens or even houndreds of scalable vector graphics files to -maintain it is not a fun task to use the graphical interface to remove -unused definitions editing those files one by one. - -To remove unused definitions from several scalable vector graphics -files, the @file{centos-art.sh} script uses Inkscape command-line -interface, specifically with the @option{--vaccum-defs} option. - -@subsubheading XHTML Files +In the example above, h1 can vary from h1 to h6. Closing tag must be +present and also match the openning tag. The value of @option{name} +and @option{href} options from the anchor element are set dynamically +using the md5sum output of combining the page location, the +@code{head-} string and the heading string. If any of the components +used to build the heading reference changes, you need to run the the +@code{tuneup} functionality in order for the anchor elements to use +the correct information. -@itemize -@item ... -@end itemize +Frequently, we use the @code{tuneup} functionality on the +@file{trunk/Identity/Webenv/App/Home} directory structure to update +the heading information and the related table of contents of web pages +therein. @subheading Usage -@itemize -@item ... -@end itemize +@subsubheading Synopsis + +@command{centos-art tuneup [OPTIONS] path/to/dir} + +@subsubheading Options + +@table @option +@item --quiet +Supress all output messages, including confirmation question. Use this +option with care. +@item --filter='regex' +Reduce the amount of files to process using @samp{regex} as pattern. +@item --answer-yes +Assume `yes' to all confirmation questions. +@item --dont-commit-changes +Supress all @code{commit} and @code{update} actions realized over +files already processed, before and after the action itself had took +place in the working copy. +@end table @subheading See also @itemize -@item ... +@item @ref{Directories trunk Scripts Functions} +@item @ref{Directories trunk Scripts} +@item @ref{Directories trunk} @end itemize diff --git a/Manual/repository.info.bz2 b/Manual/repository.info.bz2 index 9e2cc0f..8c2d572 100644 Binary files a/Manual/repository.info.bz2 and b/Manual/repository.info.bz2 differ diff --git a/Manual/repository.pdf b/Manual/repository.pdf index a6e0fbc..23ceb31 100644 Binary files a/Manual/repository.pdf and b/Manual/repository.pdf differ diff --git a/Manual/repository.txt.bz2 b/Manual/repository.txt.bz2 index 67e06a8..dbca17b 100644 Binary files a/Manual/repository.txt.bz2 and b/Manual/repository.txt.bz2 differ diff --git a/Manual/repository.xhtml.tar.bz2 b/Manual/repository.xhtml.tar.bz2 index 3bfff52..ed1aa13 100644 Binary files a/Manual/repository.xhtml.tar.bz2 and b/Manual/repository.xhtml.tar.bz2 differ diff --git a/Manual/repository.xml b/Manual/repository.xml index fe4854e..188d782 100644 --- a/Manual/repository.xml +++ b/Manual/repository.xml @@ -38,6 +38,11 @@ + Licenses + Licenses + + + Index Index @@ -157,7 +162,6 @@ Authors AuthorsThis section records authoring information of CentOS Artwork Repository along the years: Graphic Design - Work line: Directories trunk Identity • @@ -171,7 +175,6 @@ Documentation - Work line: Directories trunk Manual • @@ -182,7 +185,6 @@ Localization - Work line: Directories trunk Locales • @@ -190,7 +192,6 @@ Automation - Work line: Directories trunk Scripts • @@ -226,15 +227,23 @@ Introduction
Copying Conditions - Copying conditionsInside the CentOS Artwork Repository you can find content branded by The CentOS Project and content not branded at all. Contents branded by The CentOS Project contain either The CentOS Trademark, The CentOS Logo or The CentOS Symbol. Content branded by The CentOS Project cannot be redistributed without previous conversation with The CentOS Project. However, you can study and modify both content branded by The CentOS Project and content not branded at all in the sake of proposing improvements to The CentOS Project corporate visual identity. - If you are using the CentOS Artwork Repository for producing your own corporate visual identity, you should remove all The CentOS Trademarks from your contents and rename the repository to something different from CentOS Artwork Repository. + Copying conditions + + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. + Preamble The CentOS Artwork Repository organizes files in a very specific way to implement The CentOS Project corporate visual identity. This very specific organization of files is part of centos-art.sh script, a bash script that automates most of the frequent tasks inside the repository. - The centos-art.sh script The centos-art.sh script and the organization of files it needs to work are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of this program that they might get from you. Specifically, we want to make sure that you have the right to give away copies of centos-art.sh script, that you receive source code or else can get it if you want it, that you can change this program or use pieces of it in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the centos-art.sh script, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the centos-art.sh script. If this program is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. - The precise conditions of the license for the centos-art.sh script are found in the General Public Licenses that accompany it (see file file:///home/centos/artwork/trunk/Scripts/COPYINGtrunk/Scripts/COPYING). This manual specifically is covered by the GNU Free Documentation License. + The centos-art.sh script is released as a GPL work. Individual packages used by centos-art.sh script include their own licenses and the centos-art.sh script license applies to all packages that it does not clash with. If there is a clash between the centos-art.sh script license and individual package licenses, the individual package license applies instead. + The precise conditions of the license for the centos-art.sh script are found in the General Public Licenses (see GNU General Public License). This manual specifically is covered by the GNU Free Documentation License (see GNU Free Documentation License). + 1. The CentOS Brand + The CentOS Brand (see Directories trunk Identity Models Brands) is the main visual manifestaion of The CentOS Project. The CentOS Project uses The CentOS Brand to connect all its visual manifestions (e.g., GNU/Linux Distributions, Websites, Stationery, etc.) and, this way, provide recognition among other similar projects. + Both The CentOS Brand and all the visual manifestations that derivate from it are available for you to be able to study and improve them around a good citizen's will inside The CentOS Community environment, but you are not allowed to redistribute them elsewhere, without the given permission of The CentOS Project. + If you need to redistribute either The CentOS Brand or any the visual manifestatinos that derivate from it, write your intentions to the centos-devel@centos.org mailing list.
@@ -332,7 +341,7 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh Once you've received access to commit your changes, there is no need for you to request permission again to commit other changes from your working copy to CentOS Artwork Repository as long as you behave as a good community citizen. As a good community citizen one understand of a person who respects the work already done for others and share ideas with authors before changing relevant parts of their work, specially in situations when the access required to realize the changes has been granted already. Of course, there is a time when conversation has taken place, the paths has been traced and changing the work is so obvious that there is no need for you to talk about it; that's because you already did, you already built the trust to keep going. Anyway, the mailing list mentioned above is available for sharing ideas in a way that good relationship between community citizens could be constantly balanced. The relationship between community citizens is monitored by repository administrators. Repository administrators are responsible of granting everything goes the way it needs to go in order for the CentOS Artwork Repository to comply its mission which is: to provide a colaborative tool for The CentOS Community where The CentOS Project Corporate Identity is built and maintained from The CentOS Community itself. - It is also important to remember that all source files inside CentOS Artwork Repository should comply the terms of GNU General Public License in order for them to remain inside the repository. See file file:///home/centos/artwork/trunk/Scripts/COPYINGtrunk/Scripts/COPYING, for a complete license description. + It is also important to remember that all source files inside CentOS Artwork Repository should comply the terms of GNU General Public License (see GNU General Public License) in order for them to remain inside the repository. @@ -526,13 +535,13 @@ centos-art help --read turnk/Identity/Themes/Motifs/TreeFlower/3 Introduction
Send in Your Feedback - FeedbackIf you find an error in the CentOS Artwork Repository Manual, or if you have thought of a way to make this manual better, we would like to hear from you! Create a new ticket in The CentOS Artwork SIG web site (https://projects.centos.org/trac/artwork/). - If you have a suggestion for improving the documentation, try to be as specific as possible. If you have found an error, include the section number and some of the surrounding text so we can find it easily. + FeedbackIf you find an error in the CentOS Artwork Repository, or if you have thought of a way to make this manual better, we would like to hear from you! Share your suggestions in the appropriate mailing list (http://lists.centos.org/) and/or bug tracker (http://bugs.centos.org/). + When you make suggestion, try to be as specific as possible. For example, if you have found an error in the manual, include the section number and some of the surrounding text so we can find it easily.
Directories - Index + Licenses Introduction Top @@ -2446,7 +2455,7 @@ priority=10 . . +---v--------------------------------------v---+ . . . . . | function | . . . . . . +---v------------------------------v---+ . . . - . . . . | function_getArguments | . . . . + . . . . | function_getOptions | . . . . . . . . | function_doSomething | . . . . . . . . +------------------------------+ . . . . . . . . . . . . @@ -2517,7 +2526,7 @@ centos-art funcnam path/to/dir --filter='regex' --quiet To better understand how to design specific functions for centos-art.sh script, let's create the greet functionality which only goal is to print out different kind of greetings to your screen. The greet functionality will be set using the follwiing directory structure: - The first definition inside greet function is for variables that will be available along the whole execution environment of greet function. This time we didn't define any variable here so, we continued with definition of command-line interface, through greet_getArguments function. + The first definition inside greet function is for variables that will be available along the whole execution environment of greet function. This time we didn't define any variable here so, we continued with definition of command-line interface, through greet_getOptions function. The command-line interface of greet functionality defines how to interpret arguments passed from centos-art.sh script command-line. Inside centos-art.sh script, the interpretation of arguments passed through its command-line takes place by mean of getopt command and is written as the following code example describes: The word World in the examples above can be anything. Likewise, if you need to change the way either the hello or goodbye messages are printed out, you can modifie the functions greet_sayHello and greet_sayGoodbye, respectively. @@ -2658,6 +2673,8 @@ centos-art help --edit trunk/Scripts/Functions/Greet As the greet functionality added new translatable strings to the centos-art.sh script, it is required to update the translation messages firstly, to add the new translatable strings from greet functionality to centos-art.sh script translation messages and then, edit the translation messages of centos-art.sh script to localize the new translatable strings that have been added. To achieve this, execute the following two commands: + @@ -2811,20 +2828,20 @@ centos-art locale --edit trunk/Scripts The <file>trunk/Scripts/Functions/Prepare</file> Directory Directories trunk Scripts Functions Prepare Goals - This section describes the prepare functionality of centos-art.sh script and the preliminar steps you need to follow in order to get your workstation ready for using the CentOS Artwork Repository. + This section describes the prepare functionality of centos-art.sh script and the preliminar steps you need to follow in order to get your workstation ready for using a working copy of CentOS Artwork Repository. Description - The prepare functionality of centos-art.sh script verifies all the information required by the working copy of CentOS Artwork Repository (e.g., packages of software, symbolic links, etc.) does exist in your workstation. - The prepare functionality of centos-art.sh script is part of the CentOS Artwork Repository. So, in order to execute the prepare functionality of centos-art.sh script you need to have access to a working copy of CentOS Artwork Repository, first. Working copies of CentOS Artwork Repository are downloaded from the source repository and made available to you by mean of workstations. A workstation is a computer that you install and configure (prepare) to do something. In this case, you pick a computer and prepare it for working on the CentOS Artwork Repository. + The prepare functionality of centos-art.sh script provides the standard way of configuring the workstation you plan to use for storing the working copy of CentOS Artwork Repository. + The prepare functionality of centos-art.sh script is part of the CentOS Artwork Repository. So, in order to execute the prepare functionality of centos-art.sh script you need to have access to a working copy of CentOS Artwork Repository, first. Working copies of CentOS Artwork Repository are downloaded from the source repository and made available to you by mean of workstations. A workstation is a computer that you install and configure (prepare) to do something. In this case, you pick up a computer and prepare it for working on the CentOS Artwork Repository. Installing the workstation - Installing the workstation is the first step you need to perform for using the CentOS Artwork Repository. In this step you make your computer functional through an operating system. In this case, The Community Enterprise Operating System; which is also know as The CentOS Distribution or just CentOS, for short. + Installing the workstation is the first step you need to do. In this step you make your computer functional through an operating system. In this case, The Community Enterprise Operating System; which is also know as The CentOS Distribution or just CentOS, for short. To install The CentOS Distribution you need to have the installation media somehow (e.g., CDs, DVDs, Pendrives, etc.). There are several different ways to perform the installation process of CentOS distribution, but generally, you put the installation media in your media reader, boot the computer from it, and follow the installer intructions. That simple. If you don't have the installation media of CentOS distribution, you need to download the ISO files related to the media you plan to use (e.g., CD or DVD) and then create the installation media by yourself. The CentOS Distribution ISO files can be downloaded from http://mirrors.centos.org/ and, if you chosen CD or DVD as your prefered installation medium, you can burn the ISO files using the K3B application to create the installation media you'll use. Of course, in order to download the ISO files and create the installation media, you need to have an already installed CentOS workstation where you can realized all the work. Configuring the workstation Once you've installed the workstation and it is up and running, login as root user, create a username (e.g., centos) and set a password for it. This is the username you must use for everyday work inside your working copy of the CentOS Artwork Repository. - Caution Do not use ever the root username for your everyday work inside the working copy of CentOS Artwork Repository. It is dangerous and might provoke unreversable damages on your workstation. + Caution Do not use the root username for your everyday work inside the working copy of CentOS Artwork Repository. It is dangerous and might provoke unreversable damages on your workstation. - Once you've created the username for everyday work, there are some environment variables that you can customize to fit your personal needs (e.g., the text editor you'll use, the language the automation scripts will use to print and translate output messages, the time correction for your location, etc.). To customize these variables you need to edit your profile file (i.e., ~/.bash_profile) and set the redefinition there. Notice that you may need to logout and then do login again in order for the new variable values to take effect. + Once you've created the username for your everyday work, there are some environment variables that you can customize to fit your personal needs (e.g., default text editor, default locale information, default time zone representation, etc.). To customize these variables you need to edit your profile file (i.e., ~/.bash_profile) and set the redefinition there. Notice that you may need to logout and then do login again in order for the new variable values to take effect. Default text editor: @@ -2885,7 +2902,7 @@ sudo yum install subversion - Notice that you can execute the prepare functionality more than once. This is specially useful to keep the link information syncronized. For example, considering you've added new brushes to or removed old brushes from your working copy of CentOS Artwork Repository, the link information related to those files need to be updated in the ~/.gimp-2.2/brushes directory too, in a way that reflect the addition/deletion change that took place in your working copy. The same is true for fonts, patterns and palettes components. + Notice that you can execute the prepare functionality more than once. This is specially useful to keep the link information syncronized. For example, considering you've added new brushes to or removed old brushes from your working copy of CentOS Artwork Repository, the link information related to those files need to be updated in the ~/.gimp-2.2/brushes directory too, in a way the addition/deletion change that took place in your working copy can be reflected there, as well. The same is true for other similar components like fonts, patterns and palettes components. Usage Synopsis centos-art prepare [OPTIONS] @@ -2894,14 +2911,16 @@ centos-art.sh prepare [OPTIONS] - Verify existence of software packages and install them if they aren't installed yet. - This option provides the software required to manipulate files inside the repository (e.g., image files, documentation files, translation files, script files, etc.). Most of the software packages required by the CentOS Artwork Repository are available on The CentOS Distribution and can be installed using The CentOS Distribution installation media. The only exception is the inkscape, the package you use to manipulate SVGScalable Vector Graphics files. The inkscape package isn't inside The CentOS Distribution or any of The CentOS Project repositories neither, so you need to install it from a third party repositories like RPMForge or EPEL. + Install/update software packages required by the working copy of CentOS Artwork Repository. + The process of software installation takes place through sudo yum and the repository configuration currently set in your workstation. + Most of the software packages required by the working copy of CentOS Artwork Repository are available on The CentOS Distribution and can be installed using The CentOS Distribution installation media. The only exception is Inkscape, the program used to manipulate SVGScalable Vector Graphics files in the working copy. + The inkscape package isn't inside The CentOS Distribution or any of The CentOS Project repositories neither, so you need to install it from a third party repository like RPMForge or EPEL. See page http://wiki.centos.org/AdditionalResources/Repositories/The CentOS Repositories, to know how to configure third party repositories in The CentOS Distribution. - Update connection between working copy and workstation through symbolic links. + Install/update connection between working copy and workstation through symbolic links. This option creates the centos-art command-line interface of centos-art.sh script through a symbolic link. There is no need for you to type the full path to centos-art.sh script each time you need to execute it. Instead, you use the centos-art command which is much shorter and faster to type. This option connects design compenents like fonts, brushes, patterns and palettes inside your working copy of CentOS Artwork Repository with programs like GIMPGNU Image Manipulation Program and Inkscape outside it. This way, all your modifications on these components will take place inside the repository and will be shared to all other working copies the next time you commit the changes up to source repository. This option standardizes width, tabulation, indentation, and line numbering for text editors in your workstation. The configuration file where these definitions are set, is versioned inside your working copy and linked from the appropriate place in the workstation to make it valid to your default text editor. @@ -2916,7 +2935,13 @@ centos-art.sh prepare [OPTIONS] - Supress all output messages except errors. This option assumes an affirmative response to all questions so, take care when using it. + Supress all output messages, including confirmation question. Use this option with care. + + + + + + Assume yes to all confirmation questions.
@@ -2932,9 +2957,6 @@ centos-art.sh prepare [OPTIONS] Directories trunk - - http://wiki.centos.org/AdditionalResources/Repositories/The CentOS Repositories, to know how to configure third party repositories inside The CentOS Distribution. - @@ -3298,16 +3320,14 @@ function render_loadConfig { The <file>trunk/Scripts/Functions/Tuneup</file> Directory Directories trunk Scripts Functions Tuneup Goals - - • - - ... - - + This section describes the tuneup functionality of centos-art.sh script and general examples about file maintainance inside a working copy of CentOS Artwork Repository. Description - Shell Script Files - The shell functionality of centos-art.sh script helps you to maintain bash scripts inside repository. For example, suppose you've created many functionalities for centos-art.sh script, and you want to use a common copyright and license note for consistency in all your script files. If you have a bunch of files, doing this one by one wouldn't be a big deal. In contrast, if the amount of files grows, updating the copyright and license note for all of them would be a task rather tedious. The shell functionality exists to solve maintainance tasks just as the one previously mentioned. - When you use shell functionality to update copyright inside script files, it is required that your script files contain (at least) the following top commentary structure: + The tuneup functionality of centos-art.sh script provides the standard way of maintaining files inside your working copy of CentOS Artwork Repository. + Tasks related to file maintainance are repetitive. You might find yourself doing them time after time inside the working copy of CentOS Artwork Repository. Some of these maintainance tasks are updating top comments on shell scripts, creating table of contents for web pages, updating metadata related to design models and remove unused definitions on design models. + The maintainance tasks are associated to file extensions. This way, the tuneup functionality know what maintainance tasks should be applied to what files inside the working copy of CentOS Artwork Repository. For example, when you execute the tuneup functionality, it makes a list of files based on supported extensions (e.g., .sh, .svg and .xhtml) and apply maintainance tasks file by file accordingly to its file extension. + Maintaining .sh files + If shell scripts are found, the tuneup functionality reads a comment template (trunk/Scripts/Functions/Prepare/Config/shell_topcomment.sed) and applies it to the shell scripts, one by one. As result, all shell scripts will end up having the same copyright and license information the comment template does. + In order for the comment template to be applied correctly, the shell script you write must have the following structure: - Relevant lines in the above structure are lines from 5 to 9. Everything else in the file is left immutable. - When you are updating copyright through shell functionality, the centos-art.sh script replaces everything in-between line 5 —the first one matching ^# Copyright .+$ string— and line 9—the first long dash separator matching ^# -+$— with the content of copyright template instance. - - Caution Be sure to add the long dash separator that matches ^# -+$ regular expression before the function definition. Otherwise, if the Copyright line is present but no long dash separator exists, centos-art.sh will remove anything in-between the Copyright line and the end of file. This way you may lost your function definitions entirely. - - The copyright template instance is created from one copyright template stored in the Config/tpl_forCopyright.sed file. The template instance is created once, and later removed when no longer needed. At this moment, when template instance is created, the centos-art.sh script takes advantage of automation in order to set copyright full name and date dynamically. - When you use shell functionality to update copyright, the first thing shell functionality does is requesting copyright information to user, and later, if values were left empty (i.e., no value was typed before pressing RET key), the shell functionality uses its own default values. - When shell functionality uses its own default values, the final copyright note looks like the following: + The comment template replaces all the lines between the Copyright line (e.g., line 5) and the first separator line (e.g., line 9). Everything else in the file will remain immutable. + From time to time, we use the tuneup functionality on the `trunk/Scripts' directory structure to update the copyright and license notice of all the shell scripts we have therein. + Maintaining .svg files + If scalable vector graphics are found, the tuneup functionality reads a metadata template (trunk/Scripts/Functions/Tuneup/Config/svg_metadata.sed) and applies it to all files found, one by one. Immediatly after the metadata template has been applied and, before passing to next file, all unused definition are removed from file, too. + The metadata we apply from the metadata template is created dynamicaly using the file found absolute path, the workstation time information and the centos-art.sh script copyright information as reference. Additionally, the Creative Common Distribution-ShareAlike 3.0 License is also set in the metadata. + The elimination of unused definitions inside SVG files takes place through the option of inkscape command-line interface. + Frequently, we use the tuneup functionality on the trunk/Identity/Models and trunk/Identity/Themes/Models directory structure to update metadata and remove unused definitions from design models therein. + Maintaining .xhtml files + If web pages are found, the tuneup functionality transforms web page headings to make them accessible through a table of contents. The table of contents is expanded in place, wherever the <div class="toc"></div> piece of code be in the page. + Once the <div class="toc"></div> piece of code has be expanded, there is no need to put anything else in the page. You can run the tuneup functionality everytime you update the heading information so as to update the table of contents, too. + In order for the tuneup functionality to transform headings, you need to put headings in just one line using one of the following forms: - Relevant lines in the above structure are lines from 5 to 22. Pay attention how the copyright line was built, and how the license was added into the top comment where previously was just three dots. Everything else in the file was left immutable. - To change copyright information (i.e., full name or year information), run the shell functionality over the root directory containing the script files you want to update copyright in and enter the appropriate information when it be requested. You can run the shell functionality as many times as you need to. - To change copyright license (i.e., the text in-between lines 7 and 20), you need to edit the Config/tpl_forCopyright.sed file, set the appropriate information, and run the shell functionality once again for changes to take effect over the files you specify. - - Important The centos-art.sh script is released as: - Title +

Title

+

Title

]]> - Do not change the license information under which centos-art.sh script is released. Instead, if you think a different license must be used, please share your reasons at centos-devel@centos-art.sh mailing list. - See file file:///home/centos/artwork/trunk/Scripts/COPYINGtrunk/Scripts/COPYING, for a complete license description. - - SVG Files - The svg functionality of centos-art.sh script helps you to maintain scalable vector graphics (SVG) inside repository. For example, suppose you've been working in CentOS default design models under trunk/Identity/Themes/Models/, and you want to set common metadata to all of them, and later remove all unused SVG defintions from *.svg files. Doing so file by file may be a tedious task, so the centos-art.sh script provides the svg functionality to aid you maintain such actions. - The metadata used is defined by Inkscape 0.46 using the SVG standard markup. The centos-art.sh script replaces everything in-between <metadata and </metadata> tags with a predefined metadata template we've set for this purpose. - The metadata template was created using the metadata information of a file which, using Inkscape 0.46, all metadata fields were set. This created a complete markup representation of how SVG metadata would look like. Later, we replaced every single static value with a translation marker in the form =SOMETEXT=, where SOMETEXT is the name of its main opening tag. Later, we transform the metadata template into a sed replacement set of commads escaping new lines at the end of each line. - With metadata template in place, the centos-art.sh script uses it to create a metadata template instance for the file being processed currently. The metadata template instance contains the metadata portion of sed replacement commands with translation markers already traduced. In this action, instance creation, is where we take advantage of automation and generate metadata values like title, date, keywords, source, identifier, and relation dynamically, based on the file path centos-art.sh script is currently creating metadata information for. - With metadata template instance in place, the centos-art.sh script uses it to replace real values inside all .svg files under the current location you're running the centos-art.sh script on. Default behaviour is to ask user to enter each metadatum required, one by one. If user leaves metadatum empty, by pressing RET key, centos-art.sh uses its default value. - Many of the no-longer-used gradients, patterns, and markers (more precisely, those which you edited manually) remain in the corresponding palettes and can be reused for new objects. However if you want to optimize your document, use the Vacuum Defs command in File menu. It will remove any gradients, patterns, or markers which are not used by anything in the document, making the file smaller. - If you have one or two couple of files, removing unused definitions using the graphical interface may be enough to you. In contrast, if you have dozens or even houndreds of scalable vector graphics files to maintain it is not a fun task to use the graphical interface to remove unused definitions editing those files one by one. - To remove unused definitions from several scalable vector graphics files, the centos-art.sh script uses Inkscape command-line interface, specifically with the option. - XHTML Files + In the example above, h1 can vary from h1 to h6. Closing tag must be present and also match the openning tag. The value of and options from the anchor element are set dynamically using the md5sum output of combining the page location, the head- string and the heading string. If any of the components used to build the heading reference changes, you need to run the the tuneup functionality in order for the anchor elements to use the correct information. + Frequently, we use the tuneup functionality on the trunk/Identity/Webenv/App/Home directory structure to update the heading information and the related table of contents of web pages therein. + Usage + Synopsis + centos-art tuneup [OPTIONS] path/to/dir + Options + + + + + Supress all output messages, including confirmation question. Use this option with care. + + + + + + Reduce the amount of files to process using regex as pattern. + + + + + + Assume `yes' to all confirmation questions. + + + + + + Supress all commit and update actions realized over files already processed, before and after the action itself had took place in the working copy. + + +
+ See also • - ... + Directories trunk Scripts Functions - - Usage - - • - ... + Directories trunk Scripts - - See also - - • - ... + Directories trunk + + + + Licenses + Index + Directories + Top + + Licenses + Licenses + + + GNU General Public License + GNU General Public License + + + + GNU Free Documentation License + GNU Free Documentation License + + + + + + + GNU General Public License + GNU Free Documentation License + Licenses +
+ GNU General Public License + GNU General Public LicenseVersion 2, June 1991 + + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. + Preamble + The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software–to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. + When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. + To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. + For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. + We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. + Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. + Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. + The precise terms and conditions for copying, distribution and modification follow. + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification”.) Each licensee is addressed as “you”. + Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. + 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. + You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. + 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: + a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. + b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. + c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) + These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. + Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. + In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. + 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: + a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, + b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, + c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) + The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. + If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. + 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. + 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. + 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. + 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. + If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. + It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. + This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. + 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. + 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. + Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. + 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. + NO WARRANTY + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + END OF TERMS AND CONDITIONS + Appendix: How to Apply These Terms to Your New Programs + If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. + To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found. + + Copyright (C) 19yy + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +]]> + Also add information on how to contact you by electronic and paper mail. + If the program is interactive, make it output a short notice like this when it starts in an interactive mode: + + The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items–whatever suits your program. + You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names: + , 1 April 1989 + Ty Coon, President of Vice +]]> + This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License. +
+ + + GNU Free Documentation License + GNU General Public License + Licenses +
+ GNU Free Documentation License + GNU Free Documentation LicenseVersion 1.2, November 2002 + + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. + Preamble + The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. + This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. + We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. + 1. APPLICABILITY AND DEFINITIONS + This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. + A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. + A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. + The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. + The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. + A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”. + Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. + The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. + A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition. + The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. + 2. VERBATIM COPYING + You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. COPYING IN QUANTITY. + You may also lend copies, under the same conditions stated above, and you may publicly display copies. + 3. COPYING IN QUANTITY + If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. + If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. + If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. + It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. + 4. MODIFICATIONS + You may copy and distribute a Modified Version of the Document under the conditions of sections 2. VERBATIM COPYING and 3. COPYING IN QUANTITY above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: + A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. + B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. + C. State on the Title page the name of the publisher of the Modified Version, as the publisher. + D. Preserve all the copyright notices of the Document. + E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. + F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. + G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. + H. Include an unaltered copy of this License. + I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. + J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. + K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. + L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. + M. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version. + N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section. + O. Preserve any Warranty Disclaimers. + If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. + You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties–for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. + You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. + The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. + 5. COMBINING DOCUMENTS + You may combine the Document with other documents released under this License, under the terms defined in section 4. MODIFICATIONS above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. + The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. + In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”. + 6. COLLECTIONS OF DOCUMENTS + You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. + You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. + 7. AGGREGATION WITH IDENPENDENT WORKS + A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. + If the Cover Text requirement of section 3. COPYING IN QUANTITY is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. + 8. TRANSLATIONS + Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. MODIFICATIONS. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. + If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4. MODIFICATIONS) to Preserve its Title (section 1. APPLICABILITY AND DEFINITIONS) will typically require changing the actual title. + 9. TERMINATION + You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. + Appendix 1. Future Revisions of this License + The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. + Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. + Appendix 2. How to use this License for your documents + To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: + + If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts”. line with this: + + If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. + If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Index List of Figures - Directories + Licenses Top Index