help Standardize constructions tasks inside &TCAR; help Standardize documentation tasks inside &TCAR;. centos-art help --help --quiet --answer-yes --sync-changes --search="KEYWORD" --edit --read --update-output --update-structure --copy --delete --rename MANUAL:PART:CHAPTER:SECTION LOCATION Description The help functionality exists to create and maintain documentation manuals inside &TCAR;. Documentation Entries The documentation entry identifies the specific file you want to work with inside a documentation manual. The help functionality recognizes documentation entries in the following two formats: Path style This format uses paths to represent the documentation entries you want to work with. This format assumes you are using the first path component as chapter and the rest of the path as section identifier both inside tcar-fs documentation manual as parent documentation structure. The field related to the part sectioning structure in the documentation entry (the second field) is assumed empty, as well. For example, if you want to document the directory trunk/Scripts/Bash/Functions/Help, then you can do it with the following command: centos-art help --edit trunk/Scripts/Bash/Functions/Help Colon style This format uses colons to represent the documentation entries you want to work with. In this format, the whole documentation entry is divided in fields using colon as separator character. Documentation entries written this way use each field to specify manual, part, chapter and section identifiers (in this order). The section identifier can use a path style or hyphen style to separate components. For example, if you want to document the directory trunk/Scripts/Bash/Functions/Help, then you can do it with any of the following commands: centos-art help --edit tcar-fs::trunk:Scripts/Bash/Functions/Help centos-art help --edit tcar-fs::trunk:scripts-bash-functions-help The documentation manual name specified in the first field of a colon style documentation entry, must match the name the name of the directory where the documentation manual is stored in. By default documentation manuals are written in trunk/Documentation/Models/Texinfo or trunk/Documentation/Models/Docbook directories, based on whether they are written in Texinfo or Docbook documentation format. The match relation between the manual name you provide in the documentation entry and the related directory name inside &TCAR; is case insensitive. The same is true for all other documentation entry fields. From these documentation entry formats, the colon style provides more flexibility than path style does. You can use documentation entries written in colon style to create and maintain different documentation manuals, including the tcar-fs documentation manual. This is something you cannot do with documentation entries written in path style because they confine all documentation actions to tcar-fs documentation manual. Supported Documentation Formats The help functionality provides support for the following documentation formats: Texinfo, as described in . Options The centos-art help command accepts common options described in and the following specific options: Assume yes to all confirmation requests. Synchronizes available changes between the working copy and the central repository. This option looks for KEYWORD inside the documentation entry you provide and displays the related information for you to read. Edit documentation entry. The documentation entry must point to any directory inside the working copy. When more than one documentation entry is passed as non-option arguments to the centos-art.sh script command-line, they are queued for further edition. The edition itself takes place through your default text editor (e.g., the one you specified in the EDITOR environment variable) and the text editor opens one file at time (i.e., the queue of files to edit is not loaded in the text editor.). Read documentation entry. This option is used internally by centos-art.sh script to refer documentation based on errors, so you can know more about them and the causes that could have provoked them. Update output files rexporting them from the specified backend source files. Update document structure (e.g., cross references, menus, nodes, etc.). This option should be used whenever a document structure changes (e.g., when documentation entries are added, copied, renamed, deleted, etc.). This option grantees the document integrity and should be run before the option. Duplicate documentation entries inside the working copy. When documentation entries are copied, it is required to pass two non-option parameters in the command-line. The first non-option parameter is considered the source location and the second one the target location. Both source location and target location must point to a directory under the working copy. Delete documentation entries. It is possible to delete more than one documentation entry by specifying several documentation entries in the command line. Rename documentation entries inside the working copy. When documentation entries are renamed, it is required to pass only two non-option parameters to the command-line. The first non-option parameter is considered the source location and the second one the target location. Both source location and target location must point to a directory under the working copy. When documentation entries are removed (e.g., through or options), the help functionality takes care of updating nodes, menus and cross refentrys related to documentation entries in order to keep the manual structure in a consistent state. Examples New Document Structures To create new documentation manuals inside &TCAR; use the following command: centos-art help --edit "manual" The first time you execute this command, you will be prompted to enter manual specific information like document format, document title, document subtitle, document author, etc. Once this information has been collected the help functionality performs some repository verifications and creates the manual source files inside the manual's directory name you specified as manual. Once the documentation structure has been created this way, the recently created documentation manual is ready to receive new sectioning levels (e.g., parts, chapters, sections, etc.). Editing Document Structures To edit documentation entries, use the following command: centos-art help --edit "manual:part:chapter:section" ... Copying Document Structure To copy one documentation entry, use the following command: centos-art help --copy "manual:part:chapter:section" "manual:part:chapter:section" ... Deleting Document Structure To delete one documentation entry, use the following command: centos-art help --delete "manual:part:chapter:section" ... Renaming Document Structure To rename one documentation entry, use the following command: centos-art help --copy "manual:part:chapter:section" "manual:part:chapter:section" Updating Document Structure To update the document structure of one manual, use the following command: centos-art help --update-structure "manual" Bugs ... Authors The following people have worked in this functionality: Alain Reguera Delgado <alain.reguera@gmail.com>, =COPYRIGHT_YEAR_LIST= License Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project 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.