diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook index 982dbfb..c95d104 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook @@ -7,83 +7,81 @@ format is realized through the <code>help</code> functionality of <command>centos-art.sh</command> script, as described in <xref linkend="scripts-bash-help" />. To illustrate the - production cycle, we'll describe it here, using the + production cycle, we'll describe it here using the <quote>Repository File System</quote> documentation manual as reference. </para> <para> - The first step before creating a documentation manual is to - make yourself an idea of what such manual intends to document. - The <quote>Repository File System</quote> emerged with the - need of understanding what each directory inside &TCAR; is - for, how they can be used and how they connect themselves one - another, as the repository structure itself is built on. - At the very begining, explaining something that is being - conceived is a rather difficult task, there are many small - concepts floting around that need to be organized in order for - them to take sense when it seen as a whole. So, I decided to - create documentation adapting the same principales I followed - to create functionalities inside - <command>centos-art.sh</command> script, as a way to - understand what I was doing. This way, if programs should do - one thing well, each directory inside the repository should be - documented well in order to better understand what they do and - how they relate one another. Later, summing all directory - documentations would let us, hypothetically, to correct the - whole idea in a repeatable cycle of improvement that would - consolidate the final idea we try to implement. + The first step for creating a documentation manual is to make + yourself an idea of what such manual intends to document. The + <quote>Repository File System</quote> emerged with the need of + understanding what each directory inside &TCAR; was for, how + they could be used and how they connected themselves one + another, as the repository structure itself was built on. At + the very begining, explaining the whole idea of all + directories inside &TCAR; on one manual was difficult, there + were many changing concepts floting around which needed to be + considered. So, as a way to understand what I was doing, I + decided to adapt documentation to such changes through the + same principales I followed to create functionalities inside + <command>centos-art.sh</command> script. This way, if programs + should do one thing well, each directory inside the repository + should be documented well in order to better understand what + they do and how they relate one another. Later, summing all + directory documentations would let me, hypothetically, to + correct the whole idea through an improvement cycle that would + consolidate the final idea I try to implement. </para> <para> Once you've make yourself an idea of what the documentation - manual is for, it is time to define the manual title and the - directory name where the manual will be sotred in. The manual - title describes, in few words, what the documentation manual - is about. The manual directory name must be a word or several - words separated by minus sign. As convenction, to set the - manual directory name, it would be useful to use acronyms or - abbreviations directly related to manual's title. In our - example, the documentation manual was initially titled - <quote>The CentOS Artwork Repository File System</quote> but - it was too long, so it was reduced to <quote>Repository File - System</quote> and the documentation directory name was set to + manual is for, it is time for you to define the manual title + and the manual directory name. The manual title describes, in + few words, what the documentation manual is about. The manual + directory name must be one or more words separated by minus + sign. As convenction, to the manual directory name, it would + be convenient to use acronyms or abbreviations related to + manual's title. In our example, the documentation manual was + initially titled <quote>The CentOS Artwork Repository</quote> + but later it changed to <quote>Repository File System</quote> + and its manual directory name ended up being <code>Tcar-fs</code>. </para> <para> - Once both title and directory name related to documentation - manual have been defined, it is time to create the - documentation manual and documenting your work through - chapters and sections inside it. At this point, it is - necessary some planification to set the way the manual will be - organized. The manual organization is set through chapters and - sections. In our example, the documentation manual is made of - three chapters named <quote>The <filename + Once both manual title and manual directory name have been + defined, it is time to planificate manual's content through + chapters and sections. In our example, the documentation + manual is made of three chapters named <quote>The <filename class="directory">trunk</filename> Directory</quote>, <quote>The <filename class="directory">branches</filename> Directory</quote> and <quote>The <filename - class="directory">tags</filename> Directory</quote>. Inside - each of these chapters there is one documentation section for - each directory in &TCAR;. + class="directory">tags</filename> Directory</quote> and one + appendix named <quote>License</quote>. Inside each chapter + there is one documentation section for each directory in + &TCAR;. </para> <para> To create a manual like that one described so far, you need to introduce such organization through the <code>help</code> functionality of <command>centos-art.sh</command> script, as - the following list of commands describes: + it is described in the following list of commands: </para> <variablelist> <varlistentry> <term> - <command>centos-art help --edit tcar-fs:</command> + <command>centos-art help --edit tcar-fs</command> </term> <listitem> <para> - ... + This command creates the <quote>tcar-fs</quote> manual base + structure and opens its main definition file with your + favorite text editor so you can fix values like title, + subtitle, author, etc. </para> </listitem> </varlistentry> @@ -94,7 +92,9 @@ </term> <listitem> <para> - ... + This command creates the <quote>introduction</quote> chapter + base structure and opens its main definition file with your + favorite text editor so you can fix the chapter introduction. </para> </listitem> </varlistentry> @@ -105,21 +105,21 @@ </term> <listitem> <para> - ... + This command creates the <quote>identity</quote> section + inside the <quote>trunk</quote> chapter. If the chapter + doesn't exist it will be created first. In this command, the + <quote>identity</quote> section refers to <filename + class="directory">trunk/Identity</filename> directory inside + &TCAR;. To document other directories, follow the same + procedure but using minus signs to separate directories. For + example, to document the <filename + class="directory">trunk/Identity/Themes</filename> you would + use <quote>tcar-fs:trunk:identity-themes</quote>, and so on + for other directories. </para> </listitem> </varlistentry> - <varlistentry> - <term> - <command>centos-art help --edit tcar-fs:trunk:identity-themes</command> - </term> - <listitem> - <para> - ... - </para> - </listitem> - </varlistentry> </variablelist> <para>