From 70d847963c17c94428eb09e947d4d4c6210f1196 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Oct 08 2012 20:51:06 +0000 Subject: Update `Scripts/Bash/help.docbook' file. --- diff --git a/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/help.docbook b/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/help.docbook index c89a199..c2e59ee 100644 --- a/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/help.docbook +++ b/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/help.docbook @@ -23,7 +23,8 @@ --search="KEYWORD" --edit --read - --update + --update-output + --update-structure --copy --delete --rename @@ -41,11 +42,7 @@ The help functionality exists to create - and maintain documentation manuals inside &TCAR;. The - documentation structure and format implemented by - help functionality are described in - - and , respectively. + and maintain documentation manuals inside &TCAR;. @@ -146,148 +143,13 @@ - Texinfo (See ) + Texinfo, as described in . - - New Document Structures - - To create new documentation manuals inside &TCAR; use the - following command: - - - - centos-art help --edit "manual-name" - - - - 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-name. - - - - When you create new documentation manuals, take care of the - locale information you are currently using. This information - is generally set in the LANG environment - variable and is used by the help - functionality of centos-art.sh script to - define the language of new documentation manual and the - document template used to build it, as well. - - - - Once the documentation structure has been created this way, - the recently created documentation manual is ready to receive - new chapters and sections. - - - - - Editing Document Structures - - - centos-art help --edit "tcar-fs::trunk" - - - - This command edits the trunk chapter - documentation entry. Here is where you can define the chapter - introduction. This very same procedure is used to create - branches and tags chapters, just - be sure to change the chapter field accordingly. - - - - If the related manual or chapter itself don't exist in the - documentation structure, centos-art.sh script creates them in - their respective hierarchical order (i.e., the manual - structure first, and the chapter structure later). - - - - centos-art help --edit "tcar-fs::trunk:Identity" - - - - This command edits the trunk/Identity - documentation entry inside The CentOS Artwork - Repository File System documentation manual. - - - - When you edit documentation for a directory which related - chapter doesn't exist, centos-art.sh script creates the - related chapter first and then proceed to create the related - documentaiton entry. - - - - In order to document deeper directory levels, you need to - refer the directory you want to document by using a path-style - or a hyphen-style format as documentation entry. For example, - to edit the documentation related to the trunk/Identity/Models/Themes - directory, you can use any of the following documentation - entries: - - - - - tcar-fs::trunk:identity-models-themes - - - - - tcar-fs::trunk:Identity/Models/Themes - - - - - trunk/Identity/Models/Themes - - - - - - - - Copying Document Structure - - ... - - - - - Deleting Document Structure - - ... - - - - - Renaming Document Structure - - ... - - - - - Updating Document Structure - - ... - - - @@ -320,12 +182,12 @@ - + - This option looks for KEYWORD inside the - manual specified in the documentation entry and display - related information you to read. + This option looks for KEYWORD + inside the documentation entry you provide and displays the + related information for you to read. @@ -334,20 +196,18 @@ - Edit documentation entry related to path specified by - DOCENTRY parameter. + Edit documentation entry. - The DOCENTRY parameter must point to any - directory inside the working copy. When more than one - DOCENTRY are 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.). + 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.). @@ -356,17 +216,16 @@ - Read documentation entry specified by - DOCENTRY path. 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. + 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 @@ -376,6 +235,20 @@ + + + + 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. + + + + + @@ -396,11 +269,9 @@ - Delete documentation entries specified by - DOCENTRY inside the working copy. It is - possible to delete more than one documentation entry by - specifying more DOCENTRY parameters in the - command-line. + Delete documentation entries. It is possible to delete more + than one documentation entry by specifying several + documentation entries in the command line. @@ -435,9 +306,103 @@ 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 - None. + 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" + +