help Standardize constructions tasks inside &TCAR; help Standardize documentation tasks inside &TCAR;. centos-art help -h|--help -q|--quiet --answer-yes --synchronize --format="KEYWORD" --search="KEYWORD" --edit --read --update-output --update-structure --copy --delete --rename MANUAL:PART:CHAPTER:SECTION LOCATION The help functionality exists to create and maintain documentation manuals inside &TCAR;. 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 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 Scripts/Bash/Functions/Help, then you can do it with the following command: centos-art help --edit 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 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 Documentation/Models/Texinfo or 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. The centos-art help command accepts common options described in and the following specific options: --answer-yes Assume yes to all confirmation requests. --synchronize Synchronizes available changes between the working copy and the central repository. --format="KEYWORD" Specifies the format of documentation entry source file. This information is used as reference to build the absolute path of documentation entry, so you always have to provide it in order to reach the documentation entry you want to work with. Possible values for this option are shown in . When none of these values is passed as format, Texinfo is used as default format. Keyword Description Supported texinfo Yes docbook No latex No linuxdoc ... No --search="KEYWORD" Looks for documentation entries that match the KEYWORD specified as value and display them one by one in the order they were found. The way each documentation entry is presented to you depends on the documentation format the related documentation manual was written on. --edit Edit the documentation entry provided as argument. The edition itself takes place through your default text editor (e.g., the one you specified in the EDITOR environment variable) one file at a time (i.e., the queue of files to edit is not loaded in the text editor.). When parent components inside documentation entries doesn't exist (e.g., you try to create a section for a documentation manual that doesn't exist), the help functionality will create all documentation parent structures considering the documentation format constraints and the following document structure hierarchy order: documentation manual first, parts second, chapters third and sections lastly. --read Read the documentation entry provided as argument. 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 Update output files rexporting them from the specified backend source files. --update-structure Update document structure (e.g., cross references, menus, nodes, etc.) and should be passed with a section as documentation entry. This option should be used whenever a document structure changes (e.g., documentation entries are added, copied, renamed, deleted, etc.). This option grantees the document integrity and should be run before updating documentation manual final output files. --copy Duplicate documentation entries inside the working copy using version control. When you duplicate documentation entries through this option, you should pass only two documentation entries in the command line. The first one is considered the source location and should point to a file under version control inside the working copy. The second one is considered the target location and should point either to the same structural level the source points to or a direct parent level based on source location, as described below. "manual:part:chapter:section1" "manual:part:chapter:section2" Duplicates section1 as section2 inside the same chapter, part and manual. "manual:part:chapter1:" "manual:part:chapter2:" Duplicates chapter1 as chapter2 inside the same part and manual. "manual:part1::" "manual:part2::" Duplicates part1 as part2 inside the same manual. "manual1:::" "manual2:::" Duplicates manual1 as manual2 inside Documentation/Models/${FLAG_FORMAT}/ directory, where ${FLAG_FORMAT} is the name of the format passed as option with the first letter in uppercase and the rest in lowercase. When you copy documentation entries through this option, all structuring sections inside the one copied will be also copied. For example, if you copy a documentation manual that is made of parts, chapters and sections, the duplicated manual will contain all those parts, chapters and sections, as well. The same is true for lower sectioning structures. Thus, you can be more specific in the documentation entry by reducing the amount of content to duplicate. When you copy documentation entries through this option, you do it using documentation entries in the same structural level only. This option doesn't support copying documentation entries from differnet structural levels. For example, you cannot copy one section to a chapter different from that the source section you specified belongs to. The same applies to chapters, and parts. When you copy documentation entries through this option, the source documentation entry you specify must not contain pending changes. Otherwise, the target section won't be created and the script will immediatly stop its execution with a The source location has pending changes. error message. --delete Delete documentation entries. It is possible to delete more than one documentation entry by specifying several documentation entries in the command line. When you delete documentation entries, you can pass any number of documentation entries as argument. The documentation entries you provide will be processed one by one. When you delete a documentation entry from a documentation manual, all cross references pointing to the deleted documentation entry will be transformed into something different to point out the fact that the related documentation entry has been removed from the documentation manual and restored back if you create the deleted section again. The purpose of this is to keep the documentation manual structure in a consistent state. --rename Rename documentation entries inside the working copy. This option copies the source documentation entry to its target location, removes the source documentation entry, and restores removed cross references renaming them to point the specified target documentation entry. When you rename documentation entries, 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 version control inside the working copy. This section describes, using examples, the procedure you should follow to manage documentation manuals through help functionality inside &TCAR;. To better understand the procedure to follow, it describes a hypothetical documentation scenario and the related commands and outputs you may go through in order to complete specific documentation tasks successfully. To create new documentation manuals inside &TCAR; you need to provide both --edit and --format options as well as a documentation entry in the form manual::: to the help functionality. For example, consider a scenario where you need to create a documentation manual in texinfo format to describe different maintenance tasks you need to realized in order to keep your pets happy. We'll name such manual My Zoo. It will use chapters to organize each different kind of pets you have. Inside chapters, sections will have the pet's name as their own name to describe each pet's requirements, schedules, and so on. To create such documentation manual, run the following command: centos-art help --edit --format="texinfo" "myzoo:::" In case such documentation manual doesn't exist in the Docuementation/Models/Texinfo/ directory, this command will produce the following output: The following documentation manual doesn't exist: --> Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo Do you want to create it now? [yes/no]: yes Enter manual's title: My Zoo Enter manual's subtitle: Reference Enter manual's abstract: This manual describes my zoo maintenance tasks. Creating Documentation/Models/Texinfo/Myzoo Creating Documentation/Models/Texinfo/Myzoo/en_US Creating Documentation/Models/Texinfo/Myzoo/en_US/myzoo.conf Creating Documentation/Models/Texinfo/Myzoo/en_US/myzoo-index.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/myzoo-menu.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/myzoo-nodes.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter-menu.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter-nodes.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter.texinfo Updating Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo Creating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2 Creating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2 Creating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml Creating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook Creating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf Creating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2 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.). For example, to create a new chapter named Turtles inside My Zoo documentation manual, run the following command: centos-art help --edit --format="texinfo" "myzoo::turtles:" The following documentation chapter doesn't exist: --> Documentation/Models/Texinfo/Myzoo/en_US/Turtles Do you want to create it now? [yes/no]: yes Enter chapter's title: Turtles Creating Documentation/Models/Texinfo/Myzoo/en_US/Turtles Creating Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter-menu.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter-nodes.texinfo Creating Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter.texinfo Updating Documentation/Models/Texinfo/Myzoo/en_US/myzoo-menu.texinfo Updating Documentation/Models/Texinfo/Myzoo/en_US/myzoo-nodes.texinfo Updating Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter.texinfo Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2 Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2 Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2 Once chapters have been created it is possible to create sections inside them. For example, if you want to create a section for describing the life of a turtle named Longneck, run the following command: centos-art help --edit --format="texinfo" "myzoo::turtles:longneck" The following documentation section doesn't exist: --> Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo Do you want to create it now? [yes/no]: yes Creating Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2 Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2 Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2 To edit documentation entries you can follow the same procedure described above. Just keep in mind the following rules: When the entry you want to edit already exist it will be edited. When the entry you want to edit doesn't exist it will be created first and edited later. Consider a new turtle named Slowfeet has arrived to your home and you want to duplicate Longneck's section for it (they both are turtles and have similar requirements, squedules, etc.). To copy documentation entries you use the --copy option with two documentation entries, where the first one is the source location and the second one the target location. To do this, run the following command: centos-art help --copy --format="texinfo" "myzoo::turtles:longneck" "myzoo::turtles:slowfeet" Creating Documentation/Models/Texinfo/Myzoo/en_US/Turtles/slowfeet.texinfo Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2 Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2 Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf Updating Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2 Consider you've created the section of Longneck turtle using the following documentation entry format myzoo::turtles:longnek, but you didn't notice the typo in it. You've made cross references to the misspelled section in a few pages inside the My Zoo documentation manual and some time later you realize the section name has a spelling problem. To fix such a problem you can rename the misspelled section with the correct one running the following command: centos-art help --rename --format="texinfo" "myzoo::turtles:longnek" "myzoo::turtles:longneck" Creating Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.texinfo Deleting Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longnek.texinfo Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2 Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2 Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2 ... Consider you gift the turtle named Longneck to a friend and you want to delete its section from the My Zoo documentation manual. To do so, run the following command: centos-art help --delete --format="texinfo" "myzoo::turtles:longneck" Deleting Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2 Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2 Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf Updating Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2 To report bugs related to this function, please create a new ticket here refering the specific problems you found in it. For example, it would be useful if you copy and paste any error output from centos-art.sh script. The following people have worked in this functionality: Alain Reguera Delgado <alain.reguera@gmail.com>, =COPYRIGHT_YEAR_LIST= Copyright © =COPYRIGHT_YEAR_LIST= =COPYRIGHT_HOLDER= 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.