From 9bfa661111a51f4bbc2e17c67ae8afeae06c4ce0 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jun 08 2011 15:38:29 +0000 Subject: Update `trunk/Manuals/Docbook' directory structure. --- diff --git a/Manuals/Docbook/repository-parts.docbook b/Manuals/Docbook/repository-parts.docbook new file mode 100644 index 0000000..b0a2794 --- /dev/null +++ b/Manuals/Docbook/repository-parts.docbook @@ -0,0 +1,12 @@ + + + Repository + &intro; + &directories; + + + + Licenses + &licenses-gpl; + &licenses-gfdl; + diff --git a/Manuals/Docbook/repository-parts/Directories.docbook b/Manuals/Docbook/repository-parts/Directories.docbook new file mode 100644 index 0000000..0b20104 --- /dev/null +++ b/Manuals/Docbook/repository-parts/Directories.docbook @@ -0,0 +1,18 @@ + + + + Directories + + The CentOS Artwork Repository uses directories to organize + files and describe conceptual idea about corporate identity. Such + conceptual ideas are explained in each directory related + documentation entry. + + In this chapter you'll learn what each directory inside The + CentOS Artwork Repository is for and so, how you can make use of + them. For that purpose, the following list of directories is + available for you to explore: + + &directories-trunk; + + diff --git a/Manuals/Docbook/repository-parts/Introduction.docbook b/Manuals/Docbook/repository-parts/Introduction.docbook index fad872e..47daa93 100644 --- a/Manuals/Docbook/repository-parts/Introduction.docbook +++ b/Manuals/Docbook/repository-parts/Introduction.docbook @@ -7,16 +7,16 @@ Manual. The CentOS Artwork Repository Manual describes how The - CentOS Project Corporate Visual Identity is organized and produced + CentOS Project corporate visual identity is organized and produced inside the CentOS Artwork Repository (). If you are looking for a comprehensive, task-oriented guide for understanding - how The CentOS Project Corporate Visual Identity is produced, this + how The CentOS Project corporate visual identity is produced, this is the manual for you. This guide assumes you have a basic understanding of The CentOS Distribution. If you need help with CentOS, refer to the - help page on the CentOS Wiki () for a list of different places you can find help. diff --git a/Manuals/Docbook/repository-parts/Introduction/copying.docbook b/Manuals/Docbook/repository-parts/Introduction/copying.docbook new file mode 100644 index 0000000..9b3ff50 --- /dev/null +++ b/Manuals/Docbook/repository-parts/Introduction/copying.docbook @@ -0,0 +1,92 @@ + + + + Copying conditions + + Copyright © 2009, 2010, 2011 The CentOS Project + 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 must be + considered part of centos-art.sh script, a bash + script that automate most of the frequent tasks inside the + repository. + + 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 and + the organization of files it needs to work, 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 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 . This manual specifically is + covered by the . + + + + + The CentOS Brand + + The CentOS Brand () 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, it + provides recognition among other similar projects available on the + Internet. + + Both The CentOS Brand and all the visual manifestations that + derivate from it are available for you to study and propose + improvement around a good citizen's will at 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 + visual manifestation derived from it, write your intentions to the + The CentOS Developers mailing list + (centos-devel@centos.org). + + + + + diff --git a/Manuals/Docbook/repository-parts/Introduction/history.docbook b/Manuals/Docbook/repository-parts/Introduction/history.docbook index 47e55be..cd6ff4d 100644 --- a/Manuals/Docbook/repository-parts/Introduction/history.docbook +++ b/Manuals/Docbook/repository-parts/Introduction/history.docbook @@ -3,11 +3,11 @@ History - The CentOS Artwork Repository started around 2008, at CentOS - Developers mailing list (centos-devel@centos.org) during a - discussion about how to automate the slide images of Anaconda. In - such discussion, Ralph Angenendt rose up his hand to ask: Do you - have something to show? + The CentOS Artwork Repository started around 2008 during a + discussion about how to automate the slide images of Anaconda, at + CentOS Developers mailing list (centos-devel@centos.org). In such + discussion, Ralph Angenendt rose up his hand to ask —Do you have + something to show?—. To answer the question, I suggested a bash script which combined SVG and SED files in order to produce PNG images in @@ -62,34 +62,37 @@ structure, based on the mission and the release schema of The CentOS Project. - The directory structures started to be documented inside the - repository using text files without markup. Later, documentation - in flat text files was moved to LaTeX format and this way - The CentOS Artwork Repository Manual started to - take form. + The repository directory structures began to be documented + inside by mean of flat text files. Later, documentation in flat + text files was moved onto LaTeX format and this way The + CentOS Artwork Repository Manual is initiated. Around 2010, the rendition script changed its name from render.sh to centos-art.sh and became a collection of functionalities where rendition was just one among others (e.g., documenting and localizing). - The centos-art.sh was created to organize - automation of most frequent tasks inside the repository. There - was no need to have links all around the repository if a - command-line interface could be created (through symbolic links, - in the ~/bin directory) and - be called anywhere inside the repository as it would be a regular - command. - - Inside centos-art.sh, functionalities - started to get identified and separated one another. For example, - when images were rendered, there was no need to load - functionalities related to documentation manual. This layout moved - us onto common functionalities and specific functionalities inside - centos-art.sh script. Common functionalities - are loaded when centos-art.sh script is - initiated and are available to specific functionalities. + The centos-art.sh was initialy conceived + to organize automation of most frequent tasks inside the + repository based in the conceptual idea of Unix toolbox: + create small and specialized tools that do one thing + well. This way, functionalities inside + centos-art.sh were identified and separated one + another. For example, when images were rendered, there was no need + to load functionalities related to documentation manual. This + layout moved us onto common functionalities and specific + functionalities inside centos-art.sh script. + Common functionalities are loaded when + centos-art.sh script is initiated and are + available to specific functionalities. + There was no need to have links all around the + repository if a command-line interface could be created (through + symbolic links, in the ~/bin directory) and be called + anywhere inside the repository as it would be a regular + command. + The centos-art.sh script was redesigned to handle command-line options trough getopt option parser. @@ -124,9 +127,9 @@ translators and programmers to produce localized content. The SED files are no longer used to handle translations. - Consolidate the render, help and - locale functionalities as the most frequent tasks - performed inside the repository. Additionally, the + The render, help and + locale functionalities were consolidated as the most + frequent tasks performed inside the repository. Additionally, the prepare and tuneup functionalities are maintained as useful tasks. diff --git a/Manuals/Docbook/repository-parts/Introduction/usage.docbook b/Manuals/Docbook/repository-parts/Introduction/usage.docbook new file mode 100644 index 0000000..c281a12 --- /dev/null +++ b/Manuals/Docbook/repository-parts/Introduction/usage.docbook @@ -0,0 +1,370 @@ + + + + Usage convenctions + + The CentOS Artwork Repository is supported by Subversion + (http://subversion.tigris.org/), a version control system which + allows you to keep old versions of files and directories (usually + source code), keep a log of who, when, and why changes occurred, + etc., like CVS, RCS or SCCS. + + When using Subversion there is one "source repository" and + many "working copies" of that source repository. The working + copies are independent one another, can be distributed all around + the world and provide a local place for designers, documentors, + translators and programmers to perform their work in a + descentralized way. The source repository, on the other hand, + provides a central place for all independent working copies to + interchange data and provides the information required to permit + extracting previous versions of files at any time. + + + + Policy + + The CentOS Artwork Repository is a collaborative tool + that anyone can have access to. However, changing that tool in + any form is something that should be requested in the CentOS + Developers mailing list (centos-devel@centos.org). Generally, + people download working copies from CentOS Artwork Repository, + study the repository organization, make some changes in their + working copies, make some tests to verify such changes do work + the way expected and finally request access to commit them up + to the CentOS Artwork Repository (i.e., the source repository) + for others to benefit from them. + + 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 + cooperating citizen. Otherwise, your rights to + commit changes might be temporarly revoked or permanently + banished. + + As a good cooperating citizen one understand of a person + who respects the work already done by 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 that everything goes the way it needs + to go in order for the CentOS Artwork Repository to accomplish + its mission which is: to provide a colaborative tool for The + CentOS Community where The CentOS Project corporate visual + identity is built and maintained by The CentOS Community + itself. + + It is also important to remember that all the program + and documentation source files inside CentOS Artwork + Repository must comply the terms of and + respectively in order for them to remain inside the + repository. + + + + + + Work lines + + Content production inside the repository is organized by + work lines. There are three major work + lines of production inside The CentOS Artwork Repository, + which are: Graphic design, + Documentation and + Localization. The specific way of + producing content inside each specific work line is + standardized by mean of centos-art.sh + script (which in turn, can be considered a work line by itself + [e.g., the Automation work line]). The + centos-art.sh script provides one specific + functionality for automating each major work line of content + production (e.g., render for producing images, + help for manage documentation, and + locale for localizing contents). + + The graphic design work line exists to cover brand + design, typography design and themes design mainly. + Additionally, some auxiliar areas like icon design, + illustration design, brushes design, patterns designs and + palettes of colors are also included here for completeness. + The graphic design work line is organized in the trunk/Identity directory. + + The documentation work line exists to describe what each + directory inside the CentOS Artwork Repository is for, the + conceptual ideas behind them and, if possible, how automation + scripts make use of them. The documentation work line is + organized in the trunk/Manuals directory. + + The localization work line exists to provide the + translation messages required to produce content in different + languages. Translation messages inside the repository are + stored as portable objects (e.g., .po, .pot) and machine + objects (.mo). The localization work line is organized in the + trunk/Locales + directory. + + The automation work line exists to standardize content + production inside the working copies of CentOS Artwork + Repository. Here is developed the + centos-art.sh script, a bash script + specially designed to automate most frequent tasks (e.g., + rendition, documentation and localization) inside the + repository. There is no need to type several tasks, time + after time, if they can be programmed into just one executable + script. The automation work line is organized in the + trunk/Scripts + directory. + + + + + + Relation between directories + + In order for automation scripts to produce content inside a + working copy of CentOS Artwork Repository, it is required that all + work lines be related somehow. The relation is used by automation + scripts to know where to retrive the information they need to work + with (e.g., design model, translation messages, output locations, + etc.). This kind of relation is built using two path + constructions named master paths and + auxiliar paths. + + The master path points only to directories that contain + source files (e.g., SVG files) required to produce output base + content (e.g., PNG files) through automation scripts. Each master + path inside the repository may have several auxiliar paths + associated, but auxiliar paths can only have one master path + associated. + + Master paths used for producing images through SVG rendition + are organized under trunk/Identity/Models directory + structure and the auxiliar paths under trunk/Identity/Images, trunk/Locales and trunk/Manuals directory + structures. + + Auxiliar paths can point either to directories or files. + When an auxiliar path points to a directory, that directory + contains information that modifies somehow the content produced + from master paths (e.g., translation messages) or provides the + output information required to know where the content produced + from the master path should be stored. When an auxiliar path + points to a file, that file has no other purpose but to document + the master path it refers to. + + Auxiliar paths should never be modified under any reason but + to satisfy the relationship with the master path. Liberal change + of auxiliar paths may suppress the conceptual idea they were + initially created for; and certainly, automation scripts may stop + working as expected. + + The relationship between auxiliar paths and master paths is + built by combining the master path and the second level directory + structures of the repository. The master path is considered the + path identifier and the repository second level directory + structure is considered the common part of the path where the path + identifier is appended to. So, if we have the master path + trunk/Identity/Models/Brands, we'll + end up having, at least, the trunk/Identity/Images/Brands auxiliar + path for storing output files and, optionally, one path under + trunk/Manuals for storing + documentation and one path under trunk/Locales for storing + localizations. + + + + + + Syncronizing paths + + Once both master paths and their auxiliar paths have been + set, they shouldn't be changed. Assuming one master path must be + changed it is required that all related auxiliar paths be changed, + too. This is required in order for master paths to retain their + relation with auxiliar paths. This process of keeping relation + between master paths and auxiliar paths is known as path + syncronization. + + Path syncronization is required for automation scripts to + know where to store final output, where to retrive translation + messages, documentation, and any information that might be + desired. If the relation between master paths and auxiliar paths + is lost, there is no way for centos-art.sh + script to know where to retrive the information it needs to work + with. Path syncronization is the way we use to organize and + extend the information stored in the repository. + + Path syncronization may imply both movement of files and + replacement of content inside files. Movement of files is related + to actions like renaming files and directories inside the + repository. Replacement of content inside files is related to + actions like replacing information (e.g., paths information) + inside files in order to keep file contents and file locations + consistent one another. + + The order followed to syncronize path information is very + important because the versioned nature of the repository files we + are working with. When a renaming action must be performed, we + avoid making replacements inside files first and file movements + later. This would require two commit actions: one for the files' + internal changes and another for the file movement itself. + Otherwise, we prefer to perform file movements first and file + internal replacements later. This way it is possible to commit + both changes as if they were just one. + + There is no support for URLs actions inside + centos-art.sh script. The + centos-art.sh script is designed to work with + local files inside the working copy only. If you need to perform + URL actions directly, use Subversion commands + instead. + + At this moment there is no full implementation of path + syncronization process inside centos-art.sh + script except by texinfo backend of + help functionality which provides a restricted + implementation of path syncronization to this specific area of + documentation through the , + and options. + The plan for a full implementation of path syncronization would be + to create individual restricted implementations like this one for + other areas that demand it and then, create a higher implmentation + that combines all restricted implementations as needed. This way, + if we try to rename a repository directory the higer action will + define which are all the restricted actions that should be + performed in order for make a full path syncronization. For + example, if the directory we are renaming is part of graphic + design work line, it is required to syncronize related paths in + documentation and localization work lines. Likewise, if the + directory we are renaming is in documentation work line, it is + required to syncronize related paths in graphic design and + localization work lines. In all these cases, the direction used + for syncronizing paths must be from master path to auxiliar path + and never the opposite (i.e., rename the master path first and + auxiliar paths later). + + A practical example, through which you can notice the + usefulness of path syncronization process, is what happen when + documentation entries are renamed (see section ...). + + + + + + Extending repository organization + + Occasionly, you may find that new components of The + CentOS Project corporate visual identity need to be added to + the repository in order to work them out. If that is the case, + the first question we need to ask ourselves, before start to + create directories blindly all over, is: What is the + right place to store it? + + The best place to find answers is in The CentOS + Community (see page http://wiki.centos.org/Help), but going + there with hands empty is not good idea. It may give the + impression you don't really care about. Instead, consider the + following suggestions to find your own comprehension in order + to make your own propositions based on it. + + When extending respository structure it is very useful + to bear in mind The CentOS Project corporate visual identity + structure, The CentOS Mission and The CentOS Release Schema. + The rest is a matter of choosing appropriate names. It is also + worth to know that each directory in the repository responds + to a conceptual idea that justifies its existence. + + To build a directory structure inside the repository, + you need to define the conceptual idea first and later create + the directory, remembering that there are locations inside the + repository that define conceptual ideas you probably would + prefer to reuse. For example, the trunk/Identity/Images/Themes + directory stores theme artistic motifs, the trunk/Identity/Models/Themes + directory stores theme design models, the trunk/Manuals directory stores + documentation files, the trunk/Locales stores translation + messages, and the trunk/Scripts stores automation + scripts. + + To better illustrate this desition process, you can + consider to examin the trunk/Identity/Images/Themes/TreeFlower/3 + directory structure as example. This directory can be read + as: the theme development line of version 3 of + TreeFlower artistic motif. Additional, we can + say that TreeFlower artistic motif is part of + themes, as themes are part of The CentOS Project corporate + visual identity. + + The relationship between conceptual ideas can be + stablished by reading each repository documentation entry + individually, from trunk directory to a deeper + directory in the path. For reading repository documentation + entries we use the help functionality of + centos-art.sh script. + + + + + + File names convenction + + Inside the CentOS Artwork Repository, generally, file + names are all written in lowercase (e.g., + 01-welcome.png, + splash.png, + anaconda_header.png, etc.) and directory + names are all written capitalized (e.g., Identity, Themes, Motifs) and sometimes in cammel + case (e.g., TreeFlower, + etc.). + + In the very specific case of repository documentation + entries, file names follow the directory naming convenction. + This is because they are documenting directories and that is + something we want to remark. So, to better describe what we + are documenting, documentation entries follow the name + convenction used by the item they document. + + + + + + Repository layout + + The CentOS Artwork Repository is organized through a + convenctional trunk, branches + and tags layout. Explanation of each directory + inside the repository can be found in the chapter. + + + + diff --git a/Manuals/Docbook/repository-preamble.docbook b/Manuals/Docbook/repository-preamble.docbook new file mode 100644 index 0000000..30ed14d --- /dev/null +++ b/Manuals/Docbook/repository-preamble.docbook @@ -0,0 +1,42 @@ + + + + The CentOS Artwork Repository Manual + + + + Alain + Reguera Delgado + + + + + + 2009 + 2010 + 2011 + The CentOS Artwork SIG + + + + Permission is granted to copy, distribute and/or modify + this document under the terms of the GNU Free Documentation + License, Version 1.2 or any later version published by the + Free Software Foundation; with no Invariant Sections, no + Front-Cover Texts, and no Back-Cover Texts. A copy of the + license is included in the section entitled . + + + May, 2011 + + + This manuals documents relevant information regarding + the deployment, organization, and administration of CentOS + Artwork Repository. + + +