|
|
b65bb1 |
<refentry id="scripts-bash-help">
|
|
|
e68d9f |
|
|
|
b65bb1 |
<refmeta>
|
|
|
b65bb1 |
<refentrytitle>help</refentrytitle>
|
|
|
b65bb1 |
<indexterm type="common-function">
|
|
|
b65bb1 |
<primary>Standardize constructions tasks inside &TCAR;</primary>
|
|
|
b65bb1 |
</indexterm>
|
|
|
b65bb1 |
</refmeta>
|
|
|
b65bb1 |
|
|
|
b65bb1 |
<refnamediv>
|
|
|
b65bb1 |
<refname>help</refname>
|
|
|
b65bb1 |
<refpurpose>Standardize documentation tasks inside &TCAR;.</refpurpose>
|
|
|
b65bb1 |
</refnamediv>
|
|
|
b65bb1 |
|
|
|
b65bb1 |
<refsynopsisdiv>
|
|
|
b65bb1 |
<cmdsynopsis>
|
|
|
16c0de |
<command>centos-art help</command>
|
|
|
b65bb1 |
<arg choice="opt">
|
|
|
b65bb1 |
<arg>--help</arg>
|
|
|
b65bb1 |
<arg>--quiet</arg>
|
|
|
b65bb1 |
<arg>--answer-yes</arg>
|
|
|
b65bb1 |
<arg>--sync-changes</arg>
|
|
|
55c005 |
<arg>--format="<replaceable>KEYWORD</replaceable>"</arg>
|
|
|
b65bb1 |
<arg>--search="<replaceable>KEYWORD</replaceable>"</arg>
|
|
|
b65bb1 |
<arg>--edit</arg>
|
|
|
b65bb1 |
<arg>--read</arg>
|
|
|
70d847 |
<arg>--update-output</arg>
|
|
|
70d847 |
<arg>--update-structure</arg>
|
|
|
b65bb1 |
<arg>--copy</arg>
|
|
|
b65bb1 |
<arg>--delete</arg>
|
|
|
b65bb1 |
<arg>--rename</arg>
|
|
|
b65bb1 |
</arg>
|
|
|
b65bb1 |
<group choice="req">
|
|
|
b65bb1 |
<arg rep="repeat"><replaceable>MANUAL</replaceable>:<replaceable>PART</replaceable>:<replaceable>CHAPTER</replaceable>:<replaceable>SECTION</replaceable></arg>
|
|
|
b65bb1 |
<arg rep="repeat"><replaceable>LOCATION</replaceable></arg>
|
|
|
b65bb1 |
</group>
|
|
|
b65bb1 |
</cmdsynopsis>
|
|
|
b65bb1 |
|
|
|
b65bb1 |
</refsynopsisdiv>
|
|
|
b65bb1 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-description">
|
|
|
b65bb1 |
<title>Description</title>
|
|
|
e68d9f |
|
|
|
e68d9f |
<para>
|
|
|
b65bb1 |
The <function>help</function> functionality exists to create
|
|
|
70d847 |
and maintain documentation manuals inside &TCAR;.
|
|
|
e68d9f |
</para>
|
|
|
e68d9f |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-description-docentry">
|
|
|
16c0de |
<title>Documentation Entries</title>
|
|
|
b65bb1 |
<para>
|
|
|
16c0de |
The documentation entry identifies the specific file you want
|
|
|
16c0de |
to work with inside a documentation manual. The help
|
|
|
16c0de |
functionality recognizes documentation entries in the
|
|
|
55c005 |
following formats:
|
|
|
16c0de |
</para>
|
|
|
16c0de |
<variablelist>
|
|
|
16c0de |
<varlistentry>
|
|
|
16c0de |
<term>Path style</term>
|
|
|
16c0de |
<listitem>
|
|
|
16c0de |
<para>
|
|
|
16c0de |
This format uses paths to represent the documentation entries
|
|
|
16c0de |
you want to work with. This format assumes you are using the
|
|
|
16c0de |
first path component as chapter and the rest of the path as
|
|
|
16c0de |
section identifier both inside <quote>tcar-fs</quote>
|
|
|
16c0de |
documentation manual as parent documentation structure. The
|
|
|
16c0de |
field related to the part sectioning structure in the
|
|
|
16c0de |
documentation entry (the second field) is assumed empty, as
|
|
|
16c0de |
well. For example, if you want to document the directory
|
|
|
16c0de |
<quote>
|
|
|
16c0de |
class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
|
|
|
16c0de |
then you can do it with the following command:
|
|
|
16c0de |
</para>
|
|
|
16c0de |
|
|
|
16c0de |
<cmdsynopsis>
|
|
|
16c0de |
<command>centos-art help --edit trunk/Scripts/Bash/Functions/Help</command>
|
|
|
16c0de |
</cmdsynopsis>
|
|
|
16c0de |
</listitem>
|
|
|
16c0de |
</varlistentry>
|
|
|
16c0de |
|
|
|
16c0de |
<varlistentry>
|
|
|
16c0de |
<term>Colon style</term>
|
|
|
16c0de |
<listitem>
|
|
|
16c0de |
<para>
|
|
|
16c0de |
This format uses colons to represent the documentation entries
|
|
|
16c0de |
you want to work with. In this format, the whole documentation
|
|
|
16c0de |
entry is divided in fields using colon as separator character.
|
|
|
16c0de |
Documentation entries written this way use each field to
|
|
|
16c0de |
specify manual, part, chapter and section identifiers (in this
|
|
|
16c0de |
order). The section identifier can use a path style or hyphen
|
|
|
16c0de |
style to separate
|
|
|
16c0de |
components. For example, if you want to document the directory
|
|
|
16c0de |
<quote>
|
|
|
16c0de |
class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
|
|
|
16c0de |
then you can do it with any of the following commands:
|
|
|
16c0de |
</para>
|
|
|
16c0de |
|
|
|
16c0de |
<cmdsynopsis>
|
|
|
16c0de |
<command>centos-art help --edit tcar-fs::trunk:Scripts/Bash/Functions/Help</command>
|
|
|
16c0de |
<command>centos-art help --edit tcar-fs::trunk:scripts-bash-functions-help</command>
|
|
|
16c0de |
</cmdsynopsis>
|
|
|
16c0de |
|
|
|
16c0de |
<para>
|
|
|
16c0de |
The documentation manual name specified in the first field of
|
|
|
16c0de |
a colon style documentation entry, must match the name the
|
|
|
16c0de |
name of the directory where the documentation manual is stored
|
|
|
16c0de |
in. By default documentation manuals are written in
|
|
|
16c0de |
trunk/Documentation/Models/Texinfo or
|
|
|
16c0de |
trunk/Documentation/Models/Docbook directories, based on
|
|
|
16c0de |
whether they are written in Texinfo or Docbook documentation
|
|
|
16c0de |
format.
|
|
|
16c0de |
</para>
|
|
|
16c0de |
<para>
|
|
|
16c0de |
The match relation between the manual name you provide in the
|
|
|
16c0de |
documentation entry and the related directory name inside
|
|
|
16c0de |
&TCAR; is case insensitive. The same is true for all other
|
|
|
16c0de |
documentation entry fields.
|
|
|
b65bb1 |
</para>
|
|
|
16c0de |
|
|
|
16c0de |
</listitem>
|
|
|
16c0de |
</varlistentry>
|
|
|
16c0de |
</variablelist>
|
|
|
16c0de |
|
|
|
16c0de |
<para>
|
|
|
16c0de |
From these documentation entry formats, the colon style
|
|
|
16c0de |
provides more flexibility than path style does. You can use
|
|
|
16c0de |
documentation entries written in colon style to create and
|
|
|
16c0de |
maintain different documentation manuals, including the
|
|
|
16c0de |
<quote>tcar-fs</quote> documentation manual. This is something
|
|
|
16c0de |
you cannot do with documentation entries written in path style
|
|
|
16c0de |
because they confine all documentation actions to
|
|
|
16c0de |
<quote>tcar-fs</quote> documentation manual.
|
|
|
16c0de |
</para>
|
|
|
16c0de |
</refsection>
|
|
|
16c0de |
|
|
|
b65bb1 |
</refsection>
|
|
|
b65bb1 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-options">
|
|
|
b65bb1 |
<title>Options</title>
|
|
|
b65bb1 |
<para>
|
|
|
b65bb1 |
The <command>centos-art help</command> command accepts common
|
|
|
b65bb1 |
options described in
|
|
|
b65bb1 |
linkend="scripts-bash-cli-commonoptions" /> and the following
|
|
|
b65bb1 |
specific options:
|
|
|
b65bb1 |
</para>
|
|
|
b65bb1 |
|
|
|
b65bb1 |
<variablelist>
|
|
|
d2638e |
<varlistentry>
|
|
|
d2638e |
<term><option>--answer-yes</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
d2638e |
Assume <emphasis>yes</emphasis> to all confirmation requests.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
7f526e |
<term><option>--sync-changes</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
7f526e |
Synchronizes available changes between the working copy and
|
|
|
7f526e |
the central repository.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
55c005 |
<term><option>--format="<replaceable>KEYWORD</replaceable>"</option></term>
|
|
|
55c005 |
<listitem>
|
|
|
55c005 |
<para>
|
|
|
55c005 |
Specifies the format of documentation entry source file. This
|
|
|
55c005 |
information is used as reference to build the absolute path of
|
|
|
55c005 |
documentation entry, so you always have to provide it in order
|
|
|
55c005 |
to reach the documentation entry you want to work with.
|
|
|
e03c3c |
Possible values for this option are shown in
|
|
|
55c005 |
linkend="scripts-bash-help-supportedformats" />.
|
|
|
55c005 |
</para>
|
|
|
55c005 |
|
|
|
55c005 |
<title>Documentation formats</title>
|
|
|
55c005 |
<tgroup cols="3" align="left">
|
|
|
55c005 |
|
|
|
55c005 |
<row>
|
|
|
55c005 |
<entry>Keyword</entry>
|
|
|
55c005 |
<entry>Description</entry>
|
|
|
55c005 |
<entry>Supported</entry>
|
|
|
55c005 |
</row>
|
|
|
55c005 |
|
|
|
55c005 |
|
|
|
55c005 |
|
|
|
55c005 |
<row>
|
|
|
55c005 |
<entry><literal>texinfo</literal></entry>
|
|
|
55c005 |
<entry><xref linkend="manuals-formats-texinfo"/></entry>
|
|
|
55c005 |
<entry>Yes</entry>
|
|
|
55c005 |
</row>
|
|
|
55c005 |
<row>
|
|
|
55c005 |
<entry><literal>docbook</literal></entry>
|
|
|
55c005 |
<entry><xref linkend="manuals-formats-docbook"/></entry>
|
|
|
55c005 |
<entry>No</entry>
|
|
|
55c005 |
</row>
|
|
|
55c005 |
<row>
|
|
|
55c005 |
<entry><literal>latex</literal></entry>
|
|
|
55c005 |
<entry><xref linkend="manuals-formats-latex"/></entry>
|
|
|
55c005 |
<entry>No</entry>
|
|
|
55c005 |
</row>
|
|
|
55c005 |
<row>
|
|
|
55c005 |
<entry><literal>linuxdoc</literal></entry>
|
|
|
55c005 |
<entry>...</entry>
|
|
|
55c005 |
<entry>No</entry>
|
|
|
55c005 |
</row>
|
|
|
55c005 |
|
|
|
55c005 |
|
|
|
55c005 |
</tgroup>
|
|
|
55c005 |
|
|
|
55c005 |
</listitem>
|
|
|
55c005 |
</varlistentry>
|
|
|
55c005 |
|
|
|
55c005 |
<varlistentry>
|
|
|
70d847 |
<term><option>--search="<replaceable>KEYWORD</replaceable>"</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
55c005 |
Looks for documentation entries that match the
|
|
|
55c005 |
<replaceable>KEYWORD</replaceable> specified as value and
|
|
|
55c005 |
display them one by one in the order they were found. The way
|
|
|
55c005 |
each documentation entry is presented to you depends on the
|
|
|
55c005 |
documentation format the related documentation manual was
|
|
|
55c005 |
written on.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
d2638e |
<term><option>--edit</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
55c005 |
Edit the documentation entry provided as argument. The
|
|
|
55c005 |
edition itself takes place through your default text editor
|
|
|
55c005 |
(e.g., the one you specified in the <envar>EDITOR</envar>
|
|
|
55c005 |
environment variable) one file at a time (i.e., the queue of
|
|
|
55c005 |
files to edit is not loaded in the text editor.).
|
|
|
d2638e |
</para>
|
|
|
e03c3c |
<para>
|
|
|
e03c3c |
When parent components inside documentation entries doesn't
|
|
|
e03c3c |
exist (e.g., you try to create a section for a documentation
|
|
|
e03c3c |
manual that doesn't exist), the <function>help</function>
|
|
|
e03c3c |
functionality will create all documentation parent structures
|
|
|
e03c3c |
considering the documentation format constraints and the
|
|
|
e03c3c |
following document structure hierarchy order: documentation
|
|
|
e03c3c |
<quote>manual</quote> first, <quote>parts</quote> second,
|
|
|
e03c3c |
<quote>chapters</quote> third and <quote>sections</quote>
|
|
|
e03c3c |
lastly.
|
|
|
e03c3c |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
d2638e |
<term><option>--read</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
55c005 |
Read the documentation entry provided as argument. This
|
|
|
55c005 |
option is used internally by <command>centos-art.sh</command>
|
|
|
55c005 |
script to refer documentation based on errors, so you can know
|
|
|
55c005 |
more about them and the causes that could have provoked them.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
70d847 |
<term><option>--update-output</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
d2638e |
Update output files rexporting them from the specified backend
|
|
|
d2638e |
source files.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
70d847 |
<term><option>--update-structure</option></term>
|
|
|
70d847 |
<listitem>
|
|
|
70d847 |
<para>
|
|
|
70d847 |
Update document structure (e.g., cross references, menus,
|
|
|
73221e |
nodes, etc.) and should be passed with a section as
|
|
|
73221e |
documentation entry.
|
|
|
73221e |
</para>
|
|
|
73221e |
<para>
|
|
|
73221e |
This option should be used whenever a document structure
|
|
|
73221e |
changes (e.g., documentation entries are added, copied,
|
|
|
73221e |
renamed, deleted, etc.). This option grantees the document
|
|
|
73221e |
integrity and should be run before updating documentation
|
|
|
73221e |
manual final output files.
|
|
|
70d847 |
</para>
|
|
|
70d847 |
</listitem>
|
|
|
70d847 |
</varlistentry>
|
|
|
70d847 |
|
|
|
70d847 |
<varlistentry>
|
|
|
d2638e |
<term><option>--copy</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
e03c3c |
Duplicate documentation entries inside the working copy using
|
|
|
e03c3c |
version control.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
<para>
|
|
|
e03c3c |
When you duplicate documentation entries through this option,
|
|
|
e03c3c |
you should pass only two documentation entries in the command
|
|
|
e03c3c |
line. The first one is considered the source location and
|
|
|
e03c3c |
should point to a file under version control inside the
|
|
|
e03c3c |
working copy. The second one is considered the target location
|
|
|
e03c3c |
and should point either to the same structural level the
|
|
|
e03c3c |
source points to or a direct parent level based on source
|
|
|
e03c3c |
location, as described below.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
|
|
|
e03c3c |
<variablelist>
|
|
|
e03c3c |
<varlistentry>
|
|
|
e03c3c |
<term>
|
|
|
73221e |
"<replaceable>manual:part:chapter:section1</replaceable>" "<replaceable>manual:part:chapter:section2</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
73221e |
Duplicates <replaceable>section1</replaceable> as
|
|
|
73221e |
<replaceable>section2</replaceable> inside the same
|
|
|
e03c3c |
<replaceable>chapter</replaceable>,
|
|
|
e03c3c |
<replaceable>part</replaceable> and
|
|
|
e03c3c |
<replaceable>manual</replaceable>.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
e03c3c |
<term>
|
|
|
73221e |
"<replaceable>manual:part:chapter1:</replaceable>" "<replaceable>manual:part:chapter2:</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
73221e |
Duplicates <replaceable>chapter1</replaceable> as
|
|
|
73221e |
<replaceable>chapter2</replaceable> inside the same
|
|
|
e03c3c |
<replaceable>part</replaceable> and
|
|
|
e03c3c |
<replaceable>manual</replaceable>.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
</listitem>
|
|
|
e03c3c |
</varlistentry>
|
|
|
e03c3c |
|
|
|
e03c3c |
<varlistentry>
|
|
|
e03c3c |
<term>
|
|
|
73221e |
"<replaceable>manual:part1::</replaceable>" "<replaceable>manual:part2::</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
73221e |
Duplicates <replaceable>part1</replaceable> as
|
|
|
73221e |
<replaceable>part2</replaceable> inside the same
|
|
|
e03c3c |
<replaceable>manual</replaceable>.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
</listitem>
|
|
|
e03c3c |
</varlistentry>
|
|
|
e03c3c |
|
|
|
e03c3c |
<varlistentry>
|
|
|
e03c3c |
<term>
|
|
|
73221e |
"<replaceable>manual1:::</replaceable>" "<replaceable>manual2:::</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
73221e |
Duplicates <replaceable>manual1</replaceable> as
|
|
|
73221e |
<replaceable>manual2</replaceable> inside
|
|
|
e03c3c |
class="directory">trunk/Documentation/Models/${FLAG_FORMAT}/</filename>
|
|
|
e03c3c |
directory, where ${FLAG_FORMAT} is the name of the format
|
|
|
e03c3c |
passed as option with the first letter in uppercase and the
|
|
|
e03c3c |
rest in lowercase.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
</listitem>
|
|
|
e03c3c |
</varlistentry>
|
|
|
e03c3c |
</variablelist>
|
|
|
e03c3c |
|
|
|
e03c3c |
<para>
|
|
|
e03c3c |
When you copy documentation entries through this option, all
|
|
|
e03c3c |
structuring sections inside the one copied will be also
|
|
|
e03c3c |
copied. For example, if you copy a documentation manual that
|
|
|
e03c3c |
is made of parts, chapters and sections, the duplicated manual
|
|
|
e03c3c |
will contain all those parts, chapters and sections, as well.
|
|
|
e03c3c |
The same is true for lower sectioning structures. Thus, you
|
|
|
6449af |
can be more specific in the documentation entry by reducing
|
|
|
6449af |
the amount of content to duplicate.
|
|
|
6449af |
</para>
|
|
|
6449af |
|
|
|
6449af |
<para>
|
|
|
6449af |
When you copy documentation entries through this option, you
|
|
|
e11434 |
do it using documentation entries in the same structural level
|
|
|
e11434 |
only. This option doesn't support copying documentation
|
|
|
e11434 |
entries from differnet structural levels. For example, you
|
|
|
e11434 |
cannot copy one section to a chapter different from that the
|
|
|
bc6d1b |
source section you specified belongs to. The same applies to
|
|
|
bc6d1b |
chapters, and parts.
|
|
|
e03c3c |
</para>
|
|
|
73221e |
|
|
|
73221e |
<para>
|
|
|
73221e |
When you copy documentation entries through this option, the
|
|
|
73221e |
source documentation entry you specify must not contain
|
|
|
73221e |
pending changes. Otherwise, the target section won't be
|
|
|
73221e |
created and the script will immediatly stop its execution with
|
|
|
73221e |
a <quote>The source location has pending changes.</quote>
|
|
|
73221e |
error message.
|
|
|
73221e |
</para>
|
|
|
73221e |
|
|
|
e03c3c |
</listitem>
|
|
|
e03c3c |
</varlistentry>
|
|
|
e03c3c |
|
|
|
e03c3c |
<varlistentry>
|
|
|
d2638e |
<term><option>--delete</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
70d847 |
Delete documentation entries. It is possible to delete more
|
|
|
70d847 |
than one documentation entry by specifying several
|
|
|
70d847 |
documentation entries in the command line.
|
|
|
d2638e |
</para>
|
|
|
73221e |
<para>
|
|
|
73221e |
When you delete documentation entries, you can pass any number
|
|
|
73221e |
of documentation entries as argument. The documentation
|
|
|
73221e |
entries you provide will be processed one by one.
|
|
|
73221e |
</para>
|
|
|
73221e |
<para>
|
|
|
73221e |
When you delete a documentation entry from a documentation
|
|
|
73221e |
manual, all cross references pointing to the deleted
|
|
|
73221e |
documentation entry will be transformed into something
|
|
|
73221e |
different to point out the fact that the related documentation
|
|
|
73221e |
entry has been removed from the documentation manual and
|
|
|
73221e |
restored back if you create the deleted section again. The
|
|
|
73221e |
purpose of this is to keep the documentation manual structure
|
|
|
73221e |
in a consistent state.
|
|
|
73221e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
d2638e |
<term><option>--rename</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
73221e |
Rename documentation entries inside the working copy. This
|
|
|
73221e |
option copies the source documentation entry to its target
|
|
|
73221e |
location, removes the source documentation entry, and restores
|
|
|
73221e |
removed cross references renaming them to point the specified
|
|
|
73221e |
target documentation entry.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
<para>
|
|
|
73221e |
When you rename documentation entries, it is required to pass
|
|
|
d2638e |
only two non-option parameters to the command-line. The first
|
|
|
d2638e |
non-option parameter is considered the source location and the
|
|
|
d2638e |
second one the target location. Both source location and
|
|
|
73221e |
target location must point to a directory under version
|
|
|
73221e |
control inside the working copy.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
d2638e |
</variablelist>
|
|
|
e68d9f |
|
|
|
b65bb1 |
</refsection>
|
|
|
2b4826 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-examples">
|
|
|
b65bb1 |
<title>Examples</title>
|
|
|
70d847 |
|
|
|
a3f3a7 |
<para>
|
|
|
a3f3a7 |
This section describes, using examples, the procedure you
|
|
|
a3f3a7 |
should follow to manage documentation manuals through
|
|
|
a3f3a7 |
<function>help</function> functionality inside &TCAR;. To
|
|
|
a3f3a7 |
better understand the procedure to follow, it describes a
|
|
|
a3f3a7 |
hypothetical documentation scenario and the related commands
|
|
|
a3f3a7 |
and outputs you may go through in order to complete specific
|
|
|
a3f3a7 |
documentation tasks successfully.
|
|
|
a3f3a7 |
</para>
|
|
|
a3f3a7 |
|
|
|
70d847 |
<refsection id="scripts-bash-help-description-create">
|
|
|
55c005 |
<title>Creating Document Structures</title>
|
|
|
70d847 |
<para>
|
|
|
a3f3a7 |
To create new documentation manuals inside &TCAR; you need to
|
|
|
73221e |
provide both <option>--edit</option> and
|
|
|
73221e |
<option>--format</option> options as well as a documentation
|
|
|
a3f3a7 |
entry in the form <quote><literal>manual:::</literal></quote>
|
|
|
a3f3a7 |
to the <function>help</function> functionality.
|
|
|
a3f3a7 |
</para>
|
|
|
a3f3a7 |
|
|
|
a3f3a7 |
<para>
|
|
|
a3f3a7 |
For example, consider a scenario where you need to create a
|
|
|
afdf95 |
documentation manual in texinfo format to describe different
|
|
|
a3f3a7 |
maintenance tasks you need to realized in order to keep your
|
|
|
a3f3a7 |
pets happy. We'll name such manual <quote>My Zoo</quote>. It
|
|
|
a3f3a7 |
will use chapters to organize each different kind of pets you
|
|
|
a3f3a7 |
have. Inside chapters, sections will have the pet's name as
|
|
|
a3f3a7 |
their own name to describe each pet's requirements, schedules,
|
|
|
a3f3a7 |
and so on. To create such documentation manual, run the
|
|
|
a3f3a7 |
following command:
|
|
|
70d847 |
</para>
|
|
|
70d847 |
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
a3f3a7 |
<command>centos-art help --edit --format="texinfo" "myzoo:::"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
70d847 |
|
|
|
70d847 |
<para>
|
|
|
afdf95 |
In case such documentation manual doesn't exist in the
|
|
|
afdf95 |
|
|
|
afdf95 |
class="directory">trunk/Docuementation/Models/Texinfo/</filename>
|
|
|
afdf95 |
directory, this command will produce the following output:
|
|
|
70d847 |
</para>
|
|
|
70d847 |
|
|
|
afdf95 |
<programlisting>
|
|
|
afdf95 |
The following documentation manual doesn't exist:
|
|
|
73221e |
--> trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo
|
|
|
afdf95 |
Do you want to create it now? [yes/no]: yes
|
|
|
afdf95 |
Enter manual's title: My Zoo
|
|
|
73221e |
Enter manual's subtitle: Reference
|
|
|
73221e |
Enter manual's abstract: This manual describes my zoo maintenance tasks.
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.conf
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-index.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-menu.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-nodes.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter-menu.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter-nodes.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
|
|
|
73221e |
Creating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
|
|
|
73221e |
Creating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
|
|
|
73221e |
Creating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
|
|
|
73221e |
Creating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
|
|
|
73221e |
Creating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
|
|
|
afdf95 |
</programlisting>
|
|
|
a3f3a7 |
|
|
|
70d847 |
<para>
|
|
|
70d847 |
Once the documentation structure has been created this way,
|
|
|
70d847 |
the recently created documentation manual is ready to receive
|
|
|
70d847 |
new sectioning levels (e.g., parts, chapters, sections, etc.).
|
|
|
afdf95 |
For example, to create a new chapter named
|
|
|
a3f3a7 |
<quote>Turtles</quote> inside <quote>My Zoo</quote>
|
|
|
afdf95 |
documentation manual, run the following command:
|
|
|
70d847 |
</para>
|
|
|
afdf95 |
|
|
|
afdf95 |
<cmdsynopsis>
|
|
|
a3f3a7 |
<command>centos-art help --edit --format="texinfo" "myzoo::turtles:"</command>
|
|
|
afdf95 |
</cmdsynopsis>
|
|
|
afdf95 |
|
|
|
afdf95 |
<programlisting>
|
|
|
afdf95 |
The following documentation chapter doesn't exist:
|
|
|
73221e |
--> trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles
|
|
|
afdf95 |
Do you want to create it now? [yes/no]: yes
|
|
|
afdf95 |
Enter chapter's title: Turtles
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter-menu.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter-nodes.texinfo
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-menu.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-nodes.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
|
|
|
afdf95 |
</programlisting>
|
|
|
afdf95 |
|
|
|
70d847 |
<para>
|
|
|
beca32 |
Once chapters have been created it is possible to create
|
|
|
a3f3a7 |
sections inside them. For example, if you want to create a
|
|
|
a3f3a7 |
section for describing the life of a turtle named Longneck,
|
|
|
a3f3a7 |
run the following command:
|
|
|
70d847 |
</para>
|
|
|
70d847 |
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
a3f3a7 |
<command>centos-art help --edit --format="texinfo" "myzoo::turtles:longneck"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
70d847 |
|
|
|
beca32 |
<programlisting>
|
|
|
beca32 |
The following documentation section doesn't exist:
|
|
|
73221e |
--> trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo
|
|
|
beca32 |
Do you want to create it now? [yes/no]: yes
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
|
|
|
beca32 |
</programlisting>
|
|
|
beca32 |
|
|
|
beca32 |
</refsection>
|
|
|
beca32 |
|
|
|
beca32 |
<refsection id="scripts-bash-help-description-edit">
|
|
|
beca32 |
<title>Editing Document Structures</title>
|
|
|
70d847 |
<para>
|
|
|
beca32 |
To edit documentation entries you can follow the same
|
|
|
a3f3a7 |
procedure described above. Just keep in mind the following
|
|
|
a3f3a7 |
rules:
|
|
|
a3f3a7 |
</para>
|
|
|
a3f3a7 |
|
|
|
a3f3a7 |
<itemizedlist>
|
|
|
a3f3a7 |
<listitem>
|
|
|
a3f3a7 |
<para>
|
|
|
a3f3a7 |
When the entry you want to edit already exist it will be
|
|
|
a3f3a7 |
edited.
|
|
|
70d847 |
</para>
|
|
|
a3f3a7 |
</listitem>
|
|
|
a3f3a7 |
|
|
|
a3f3a7 |
<listitem>
|
|
|
a3f3a7 |
<para>
|
|
|
a3f3a7 |
When the entry you want to edit doesn't exist it will be created
|
|
|
a3f3a7 |
first and edited later.
|
|
|
a3f3a7 |
</para>
|
|
|
a3f3a7 |
</listitem>
|
|
|
a3f3a7 |
|
|
|
a3f3a7 |
</itemizedlist>
|
|
|
a3f3a7 |
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
70d847 |
<refsection id="scripts-bash-help-description-copy">
|
|
|
55c005 |
<title>Copying Document Structures</title>
|
|
|
70d847 |
<para>
|
|
|
a3f3a7 |
Consider a new turtle named Slowfeet has arrived to your home
|
|
|
a3f3a7 |
and you want to duplicate Longneck's section for it (they both
|
|
|
a3f3a7 |
are turtles and have similar requirements, squedules, etc.).
|
|
|
a3f3a7 |
To copy documentation entries you use the
|
|
|
a3f3a7 |
<option>--copy</option> option with two documentation entries,
|
|
|
a3f3a7 |
where the first one is the source location and the second one
|
|
|
73221e |
the target location. To do this, run the following command:
|
|
|
70d847 |
</para>
|
|
|
70d847 |
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
a3f3a7 |
<command>centos-art help --copy --format="texinfo" "myzoo::turtles:longneck" "myzoo::turtles:slowfeet"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
70d847 |
|
|
|
a3f3a7 |
<programlisting>
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/slowfeet.texinfo
|
|
|
a3f3a7 |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
|
|
|
a3f3a7 |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
|
|
|
a3f3a7 |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
|
|
|
a3f3a7 |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
|
|
|
a3f3a7 |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
|
|
|
a3f3a7 |
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
|
|
|
a3f3a7 |
</programlisting>
|
|
|
a3f3a7 |
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
73221e |
<refsection id="scripts-bash-help-description-rename">
|
|
|
73221e |
<title>Renaming Document Structures</title>
|
|
|
70d847 |
<para>
|
|
|
73221e |
Consider you've created the section of Longneck turtle using
|
|
|
73221e |
the following documentation entry format
|
|
|
73221e |
<quote>myzoo::turtles:longnek</quote>, but you didn't notice
|
|
|
73221e |
the typo in it. You've made cross references to the misspelled
|
|
|
73221e |
section in a few pages inside the <quote>My Zoo</quote>
|
|
|
73221e |
documentation manual and some time later you realize the
|
|
|
73221e |
section name has a spelling problem. To fix such a problem
|
|
|
73221e |
you can rename the misspelled section with the correct one
|
|
|
73221e |
running the following command:
|
|
|
70d847 |
</para>
|
|
|
73221e |
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
73221e |
<command>centos-art help --rename --format="texinfo" "myzoo::turtles:longnek" "myzoo::turtles:longneck"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
73221e |
|
|
|
73221e |
<programlisting>
|
|
|
73221e |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.texinfo
|
|
|
73221e |
Deleting trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longnek.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
|
|
|
73221e |
</programlisting>
|
|
|
73221e |
|
|
|
70d847 |
<para>
|
|
|
70d847 |
...
|
|
|
70d847 |
</para>
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
73221e |
<refsection id="scripts-bash-help-description-delete">
|
|
|
73221e |
<title>Deleting Document Structures</title>
|
|
|
2b4826 |
<para>
|
|
|
73221e |
Consider you gift the turtle named Longneck to a friend and
|
|
|
73221e |
you want to delete its section from the <quote>My Zoo</quote>
|
|
|
73221e |
documentation manual. To do so, run the following command:
|
|
|
2b4826 |
</para>
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
73221e |
<command>centos-art help --delete --format="texinfo" "myzoo::turtles:longneck"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
73221e |
<programlisting>
|
|
|
73221e |
Deleting trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
|
|
|
73221e |
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
|
|
|
73221e |
</programlisting>
|
|
|
55c005 |
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
b65bb1 |
</refsection>
|
|
|
2b4826 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-bugs">
|
|
|
b65bb1 |
<title>Bugs</title>
|
|
|
2b4826 |
<para>
|
|
|
bc6d1b |
To report bugs related to this function, please create a new
|
|
|
98cbf2 |
ticket
|
|
|
98cbf2 |
url="https://projects.centos.org/trac/artwork/newticket?summary=Error%20Standardizing%20Documentation%20Tasks&component=Scripts">here</ulink>
|
|
|
98cbf2 |
refering the specific problems you found in it. For example,
|
|
|
98cbf2 |
it would be useful if you copy and paste any error output from
|
|
|
98cbf2 |
<command>centos-art.sh</command> script.
|
|
|
2b4826 |
</para>
|
|
|
b65bb1 |
</refsection>
|
|
|
2b4826 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-authors">
|
|
|
2b4826 |
<title>Authors</title>
|
|
|
2b4826 |
<para>
|
|
|
b65bb1 |
The following people have worked in this functionality:
|
|
|
2b4826 |
</para>
|
|
|
2b4826 |
<itemizedlist>
|
|
|
2b4826 |
<listitem>
|
|
|
2b4826 |
<para>
|
|
|
1542c4 |
Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=
|
|
|
2b4826 |
</para>
|
|
|
2b4826 |
</listitem>
|
|
|
2b4826 |
</itemizedlist>
|
|
|
b65bb1 |
</refsection>
|
|
|
2b4826 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-licence">
|
|
|
2b4826 |
<title>License</title>
|
|
|
1542c4 |
|
|
|
2b4826 |
<para>
|
|
|
1542c4 |
Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project
|
|
|
1542c4 |
</para>
|
|
|
2b4826 |
|
|
|
1542c4 |
<para>
|
|
|
1542c4 |
This program is free software; you can redistribute it and/or
|
|
|
1542c4 |
modify it under the terms of the GNU General Public License as
|
|
|
1542c4 |
published by the Free Software Foundation; either version 2 of
|
|
|
1542c4 |
the License, or (at your option) any later version.
|
|
|
1542c4 |
</para>
|
|
|
2b4826 |
|
|
|
1542c4 |
<para>
|
|
|
1542c4 |
This program is distributed in the hope that it will be
|
|
|
1542c4 |
useful, but WITHOUT ANY WARRANTY; without even the implied
|
|
|
1542c4 |
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
|
1542c4 |
PURPOSE. See the GNU General Public License for more details.
|
|
|
1542c4 |
</para>
|
|
|
2b4826 |
|
|
|
1542c4 |
<para>
|
|
|
1542c4 |
You should have received a copy of the GNU General Public
|
|
|
1542c4 |
License along with this program; if not, write to the Free
|
|
|
1542c4 |
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
|
|
|
1542c4 |
USA.
|
|
|
2b4826 |
</para>
|
|
|
b65bb1 |
</refsection>
|
|
|
e68d9f |
|
|
|
b65bb1 |
</refentry>
|