|
|
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,
|
|
|
70d847 |
nodes, etc.). This option should be used whenever a document
|
|
|
70d847 |
structure changes (e.g., when documentation entries are added,
|
|
|
70d847 |
copied, renamed, deleted, etc.). This option grantees the
|
|
|
70d847 |
document integrity and should be run before the
|
|
|
70d847 |
<option>--update-output</option> option.
|
|
|
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>
|
|
|
e03c3c |
"<replaceable>manual:part:chapter:section-1</replaceable>" "<replaceable>manual:part:chapter:section-2</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
e03c3c |
Duplicates <replaceable>section-1</replaceable> as
|
|
|
e03c3c |
<replaceable>section-2</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>
|
|
|
e03c3c |
"<replaceable>manual:part:chapter-1:</replaceable>" "<replaceable>manual:part:chapter-2:</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
e03c3c |
Duplicates <replaceable>chapter-1</replaceable> as
|
|
|
e03c3c |
<replaceable>chapter-2</replaceable> inside the same
|
|
|
e03c3c |
<replaceable>part</replaceable> and
|
|
|
e03c3c |
<replaceable>manual</replaceable>.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
</listitem>
|
|
|
e03c3c |
</varlistentry>
|
|
|
e03c3c |
|
|
|
e03c3c |
<varlistentry>
|
|
|
e03c3c |
<term>
|
|
|
e03c3c |
"<replaceable>manual:part-1::</replaceable>" "<replaceable>manual:part-2::</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
e03c3c |
Duplicates <replaceable>part-1</replaceable> as
|
|
|
e03c3c |
<replaceable>part-2</replaceable> inside the same
|
|
|
e03c3c |
<replaceable>manual</replaceable>.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
</listitem>
|
|
|
e03c3c |
</varlistentry>
|
|
|
e03c3c |
|
|
|
e03c3c |
<varlistentry>
|
|
|
e03c3c |
<term>
|
|
|
e03c3c |
"<replaceable>manual-1:::</replaceable>" "<replaceable>manual-2:::</replaceable>"</term>
|
|
|
e03c3c |
<listitem>
|
|
|
e03c3c |
<para>
|
|
|
e03c3c |
Duplicates <replaceable>manual-1</replaceable> as
|
|
|
e03c3c |
<replaceable>manual-2</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
|
|
|
e11434 |
source section belongs to. The same applies to chapters, and
|
|
|
e11434 |
parts.
|
|
|
e03c3c |
</para>
|
|
|
e03c3c |
|
|
|
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>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
e68d9f |
|
|
|
d2638e |
<varlistentry>
|
|
|
d2638e |
<term><option>--rename</option></term>
|
|
|
d2638e |
<listitem>
|
|
|
d2638e |
<para>
|
|
|
d2638e |
Rename documentation entries inside the working copy.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
<para>
|
|
|
d2638e |
When documentation entries are renamed, 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
|
|
|
d2638e |
target location must point to a directory under the working
|
|
|
d2638e |
copy.
|
|
|
d2638e |
</para>
|
|
|
d2638e |
</listitem>
|
|
|
d2638e |
</varlistentry>
|
|
|
d2638e |
</variablelist>
|
|
|
e68d9f |
|
|
|
d2638e |
<para>
|
|
|
d2638e |
When documentation entries are removed (e.g., through
|
|
|
d2638e |
<option>--delete</option> or <option>--rename</option>
|
|
|
d2638e |
options), the <function>help</function> functionality takes
|
|
|
b65bb1 |
care of updating nodes, menus and cross refentrys related to
|
|
|
d2638e |
documentation entries in order to keep the manual structure in
|
|
|
89114c |
a consistent state.
|
|
|
d2638e |
</para>
|
|
|
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
|
|
|
a3f3a7 |
provide the <option>--edit</option> option and 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:
|
|
|
a3f3a7 |
--> 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
|
|
|
beca32 |
Enter manual's subtitle: Maintenance reference
|
|
|
beca32 |
Enter manual's abstract: This manual relates pets' maintenance tasks.
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.conf
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-index.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-menu.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-nodes.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Licenses/chapter-menu.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Licenses/chapter-nodes.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Licenses/chapter.texinfo
|
|
|
a3f3a7 |
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.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
|
|
|
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:
|
|
|
a3f3a7 |
--> 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
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter-menu.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter-nodes.texinfo
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter.texinfo
|
|
|
a3f3a7 |
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-menu.texinfo
|
|
|
a3f3a7 |
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-nodes.texinfo
|
|
|
a3f3a7 |
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter.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
|
|
|
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:
|
|
|
a3f3a7 |
--> trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.texinfo
|
|
|
beca32 |
Do you want to create it now? [yes/no]: yes
|
|
|
a3f3a7 |
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.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
|
|
|
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
|
|
|
a3f3a7 |
the target location. This need can be covered with the
|
|
|
a3f3a7 |
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/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 |
|
|
|
a3f3a7 |
<warning>
|
|
|
70d847 |
<para>
|
|
|
a3f3a7 |
In order to copy documentation entries successfully, the
|
|
|
a3f3a7 |
source documentation entry must not contain any pending
|
|
|
0883fa |
change. Otherwise, the target section won't be created and the
|
|
|
0883fa |
script will immediatly stop its execution with a <quote>The
|
|
|
0883fa |
source location has pending changes.</quote> error message.
|
|
|
70d847 |
</para>
|
|
|
a3f3a7 |
</warning>
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
70d847 |
<refsection id="scripts-bash-help-description-delete">
|
|
|
55c005 |
<title>Deleting Document Structures</title>
|
|
|
70d847 |
<para>
|
|
|
70d847 |
To delete one documentation entry, use the following command:
|
|
|
70d847 |
</para>
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
e03c3c |
<command>centos-art help --delete --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
70d847 |
<para>
|
|
|
70d847 |
...
|
|
|
70d847 |
</para>
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
70d847 |
<refsection id="scripts-bash-help-description-rename">
|
|
|
55c005 |
<title>Renaming Document Structures</title>
|
|
|
2b4826 |
<para>
|
|
|
70d847 |
To rename one documentation entry, use the following command:
|
|
|
2b4826 |
</para>
|
|
|
70d847 |
|
|
|
70d847 |
<cmdsynopsis>
|
|
|
e03c3c |
<command>centos-art help --copy --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>" "<replaceable>manual:part:chapter:section</replaceable>"</command>
|
|
|
70d847 |
</cmdsynopsis>
|
|
|
55c005 |
|
|
|
55c005 |
<para>
|
|
|
55c005 |
...
|
|
|
55c005 |
</para>
|
|
|
70d847 |
</refsection>
|
|
|
70d847 |
|
|
|
b65bb1 |
</refsection>
|
|
|
2b4826 |
|
|
|
b65bb1 |
<refsection id="scripts-bash-help-bugs">
|
|
|
b65bb1 |
<title>Bugs</title>
|
|
|
2b4826 |
<para>
|
|
|
2b4826 |
...
|
|
|
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>
|