From 1c90799d850c4770113eaf98d2a0af5d7e83d9fc Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Sep 15 2011 21:08:33 +0000 Subject: Reorganize files related to `Tcar-ug' documentation manual. --- diff --git a/Manuals/Tcar-ug/Manuals/Formats.docbook b/Manuals/Tcar-ug/Manuals/Formats.docbook new file mode 100644 index 0000000..3581d82 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Formats.docbook @@ -0,0 +1,8 @@ + + + Documentation Formats + + &manuals-formats-intro; + &manuals-formats-texinfo; + + diff --git a/Manuals/Tcar-ug/Manuals/Formats/docbook.docbook b/Manuals/Tcar-ug/Manuals/Formats/docbook.docbook new file mode 100644 index 0000000..326d367 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Formats/docbook.docbook @@ -0,0 +1,6 @@ + + DocBook Documentation Backend + + ... + + diff --git a/Manuals/Tcar-ug/Manuals/Formats/intro.docbook b/Manuals/Tcar-ug/Manuals/Formats/intro.docbook new file mode 100644 index 0000000..9923757 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Formats/intro.docbook @@ -0,0 +1,26 @@ + + + Introduction + + + Presently, inside &TCD;, there is support for Texinfo, LaTeX, + DocBook and LinuxDoc documentation formats. These formats have + their own specifications and requirements to create and + maintain documentation manuals through them. Inside &TCAR;, + the help functionality of + centos-art.sh script provides an interface + where documentation format specifications have been already + considered for you to be able of creating and maintaining + documentation manuals without needing to take care of those + underlaying structuring tasks. + + + + This chapter describes how the help + functionality of centos-art.sh script + implements the different documentation source formats + available inside &TCD;, and the related internationalization + issues of documentation manuals produced through them. + + + diff --git a/Manuals/Tcar-ug/Manuals/Formats/latex.docbook b/Manuals/Tcar-ug/Manuals/Formats/latex.docbook new file mode 100644 index 0000000..afbb99a --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Formats/latex.docbook @@ -0,0 +1,6 @@ + + LaTeX Documentation Backend + + ... + + diff --git a/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook b/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook new file mode 100644 index 0000000..68ad6b8 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Formats/texinfo.docbook @@ -0,0 +1,310 @@ + + + Texinfo Documentation Format + + + This section describes how the Texinfo documentation format is + implemented inside the help functionality + of centos-art.sh script to produce + documentation manuals inside &TCAR;. More information about + Texinfo documentation system itself can be found by running + the info texinfo command. + + + + Texinfo Document Structure + + The texinfo document structure provided by + help functionality creates an + organization that makes documentation manuals written in + texinfo format to be scalable and maintainable through time, + just as described in . + Structuring considerations follow the idea of an upside-down + tree to organize chapters, sections, subsections, and the + like. The document initiates with a Top node which contains + manual's main definitions (e.g., title, copyright note, + abstract, and the list of chapters). Inside each chapter the + information is logically organized in sections, subsections + and subsubsections. + + + + The first time you use the help + functionality to create a documentation manual in texinfo + format, the help functionality considers + the working directory you are placed in to determine where to + store the documentation manual source files. When the current + working directory is ~/artwork/branches/Manuals/Texinfo, + the documentation manual directory is created therein. On all + other situations, the documentation manual directory is + created under ~/artwork/trunk/Manuals + directory. Once the documentation manual directory has been + created, the help functionality creates + the related definition files using texinfo documentation + templates as described in . + + + + Inside the documentation manual directory, source files are + stored inside language specific directories. Language + specific directories are necessary to implement + internationalization of source files written in texinfo + format, as described in . + + + + Inside the language specific directory, the files + + + +${MANUAL_NAME}.texinfo +${MANUAL_NAME}-index.texinfo +${MANUAL_NAME}-menu.texinfo +${MANUAL_NAME}-nodes.texinfo + + + exist to store the manual's main definitions (e.g., title, + subtitle, author, copyright notice, chapters, appendixes, + indexes and all the similar stuff a documentation manual would + have). In addition to these files, there is one directory for + each chapter created inside the manual. Inside each chapter + directory, the files + + + +chapter.texinfo +chapter-menu.texinfo +chapter-nodes.texinfo + + + exist to control section definitions related to the chapter + directory they belong to. The documentation manual content + itself is stored in section files (a.k.a. + documentation entries) suffixed with texinfo extension and arbitrary + names, as it is displayed in . + + + + Texinfo document structure + + Texinfo document structure + + + trunk/Manuals/${MANUAL_NAME} +`-- ${LANG} + |-- ${CHAPTER_NAME} + | |-- chapter-menu.texinfo + | |-- chapter-nodes.texinfo + | |-- chapter.texinfo + | `-- ${SECTION_NAME}.texinfo + |-- Licenses + | |-- chapter-menu.texinfo + | |-- chapter-nodes.texinfo + | `-- chapter.texinfo + |-- ${MANUAL_NAME}-index.texinfo + |-- ${MANUAL_NAME}-menu.texinfo + |-- ${MANUAL_NAME}-nodes.texinfo + `-- ${MANUAL_NAME}.texinfo + + + + + + + + Texinfo Document Templates + + Texinfo document templates provide the texinfo document design + model that help functionality needs to + create and maintain texinfo document structures like that one + described in . + + + + Texinfo document templates are language-specific. This means + that there is (or at least must be) one texinfo document + template for each language you want to write documentation + manuals in texinfo format. Using one texinfo document + template for each leanguage is required because, it is not + possible to retrive translatable strings from source files + (e.g., through gettext procedures) + so translators can localize documentation source files to + other languages, independently from documentors. + + + + + When the help functionality doesn't find a + texinfo document template for that language the documentation + manual is being currently created for, the help + functionality takes the files it needs from texinfo document + templates written in English language then. + + + + + The files related to texinfo document templates are stored in + + + +~/artwork/trunk/Scripts/Bash/Functions/Help/Texinfo/Templates + + + directory, as displayed in . In this structure, + the initial state of manual's source files is customized by + the following files: + + + + + + chapter.texinfo + + + ... + + + + + + section.texinfo + + + ... + + + + + + chapter-menu.texinfo + + + ... + + + + + + chapter-nodes.texinfo + + + ... + + + + + + + There are other files that aren't related to manual's source + files, but to manual's output files. Such files are described + below and can be found both inside and outside the language + specific directories so you can control common and specific + output settings through them. + + + + + manual-ini.pl + + + ... + + + + + + manual.sed + + + ... + + + + + + manual.conf + + + ... + + + + + + + + Texinfo document template + + Texinfo document template + + + ~/artwork/trunk/Scripts/Bash/Functions/Help/Texinfo/Templates +|-- ${LANG} +| |-- Chapters +| | |-- chapter-menu.texinfo +| | |-- chapter-nodes.texinfo +| | |-- chapter.texinfo +| | `-- section.texinfo +| |-- Licenses +| | |-- GFDL.texinfo +| | |-- GPL.texinfo +| | |-- chapter-menu.texinfo +| | |-- chapter-nodes.texinfo +| | `-- chapter.texinfo +| |-- manual-index.texinfo +| |-- manual-init.pl +| |-- manual-menu.texinfo +| |-- manual-nodes.texinfo +| |-- manual.conf +| |-- manual.sed +| `-- manual.texinfo +|-- manual-init.pl +`-- manual.sed + + + + + + + Inside the directory structure of texinfo document templates, + the Chapters directory + organizes chapter specific models used to create and maintain + both chapter and sections inside manuals. On the other hand, + the Licenses directory + organizes the license information linked from all manuals. + Notice the license information is not copied into + documentation manuals when they are created, but refered from + this location where they are maintained. This configuration + permites that all documentation manuals written in texinfo + format inside &TCAR; do use the same license information and + if a change is committed to the license files, such changes be + immediatly propagated to documentation manuals the next time + their output files be updated. + + + + + Texinfo Document Configuration + + ... + + + + + Texinfo Document Internationalization + + ... + + + + + diff --git a/Manuals/Tcar-ug/Manuals/Latex.docbook b/Manuals/Tcar-ug/Manuals/Latex.docbook new file mode 100644 index 0000000..5bfd524 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Latex.docbook @@ -0,0 +1,7 @@ + + + LaTeX Backend + + &manuals-latex-intro; + + diff --git a/Manuals/Tcar-ug/Manuals/Latex/intro.docbook b/Manuals/Tcar-ug/Manuals/Latex/intro.docbook new file mode 100644 index 0000000..23f11ec --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Latex/intro.docbook @@ -0,0 +1,6 @@ + +Introduction + + ... + + diff --git a/Manuals/Tcar-ug/Manuals/Production.docbook b/Manuals/Tcar-ug/Manuals/Production.docbook new file mode 100644 index 0000000..58451f0 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production.docbook @@ -0,0 +1,12 @@ + + + Documentation Production Cycle + + &manuals-production-intro; + &manuals-production-identifying-goals; + &manuals-production-identifying-title; + &manuals-production-identifying-structure; + &manuals-production-implementing-structure; + &manuals-production-maintaining-structure; + + diff --git a/Manuals/Tcar-ug/Manuals/Production/identifying-goals.docbook b/Manuals/Tcar-ug/Manuals/Production/identifying-goals.docbook new file mode 100644 index 0000000..11b3d3d --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production/identifying-goals.docbook @@ -0,0 +1,32 @@ + + Identifying Document Goals + + Before TCAR-FS documentation manual + exist, there was an emerging need to understand what each + directory inside the growing repository layout was for, how + they could be used and how they could be connected one + another. At that moment the directory structure was very + unstable and explaining the whole idea behind it wouldn't be + possible, there were many changing concepts floating around + which needed to be considered in the same changing way. So, to + understand what was happening, the + TCAR-FS documentation manual appeared. + + + + The TCAR-FS manual let us to document + each directory inside the repository individually and, later, + by considering all directory documentations together, it would + be possible (hypothetically) to correct the whole idea through + an improvement cycle that would consolidate the final idea we + try to implement. + + + + Other documentation manuals might be different from that + described above, however, it would be helpful to make yourself + a clean idea about what you are going to document exactly + before putting your hands on it. + + + diff --git a/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook b/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook new file mode 100644 index 0000000..ce2d6e9 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook @@ -0,0 +1,124 @@ + + Identifying Document Structure + + Once both manual's title and manual's directory name have been + defined, it is time to plan manual's structure through which + chapters and sections will be organized. The + TCAR-FS manual has been following the + same organization of &TCAR; directories. Each directory inside + the repository can have its own documentation entry to store + related information that let people to communicate thoughts + about its content. As we are using texinfo format to write + such documentation entries, it is possible to refer other + documentation entries through cross reference. + + + + At this point we phase that the repository directory structure + has more levels deep than those texinfo sectioning commands + can conver. Notice that this is not a Texinfo limitation since + content in most manuals can be very good organized with the + sectioning levels provided by Texinfo system. The thing is + that it is not possible to set one sectioning level for + each directory level deep inside the repository using Texinfo + sectioning command; the content organization must be + reaccomodated in order to fit the amount of sectioning + commands the Texinfo system provides. + + + + As consequence of sectioning limitations described above, the + TCAR-FS manual was structured as + following: + + + + + + Chapter 1. The trunk + Directory + + + This chapter describes the trunk + directory and all directories inside it. The first level of + directories (i.e., the trunk directory itself) is described + inside the chapter entry. Deeper directory levels are all + documented through sections and have a file for their own. It + is also possible to write subsections and subsubsections, + however, they don't have a file for their own as sections do. + Subsections and Subsubsections should be written as part of + section files (i.e., when writting sections). + + + + + + Chapter 2. The branches + Directory + + + This chapter describes the branches + directory and all directories inside it following the same + structure described for trunk directory + above. + + + + + + Chapter 3. The tags + Directory + + + This chapter describes the tags directory + and all directories inside it following the same structure + described for trunk directory above. + + + + + + Appendix A. Licenses + + + This appendix is confined to organize licenses mentioned + in the manual. The content of this appendix is out of + documenatation manual scope itself and is shared among all + documentation manuals written through the + help of centos-art.sh + script inside &TCAR;. To know how to edit the content of this + chapter, see ... + + + + + + Index + + + This chapter organizes links to those index definitions you + defined inside the documentation manual. The index information + displayed by this chapter is auto-generated each time the + manual's output files are created so this chapter is not + editable. + + + + + + + The structure of other documentation manuals is very similar + to that one described so far. When you create a new + documentation manual it is created with a base structure that + includes the Licenses appendix and the + Index unnumbered chapter only. This structure + is ready for output but you surely found it useless since no + content is described in it (execpt for the licenses, of + course). In order to describe inside a documentation manual + recently created, you need to create the chapters it will have + and the sections inside them, as described in . + + + diff --git a/Manuals/Tcar-ug/Manuals/Production/identifying-title.docbook b/Manuals/Tcar-ug/Manuals/Production/identifying-title.docbook new file mode 100644 index 0000000..9746d03 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production/identifying-title.docbook @@ -0,0 +1,29 @@ + + Identifying Document Title + + Once you've make yourself an clean idea of what the + documentation manual is for and the needs behind, it is time + for to define the manual's title and the manual's directory + name. Both manuals' title and manual's directory name + describe what the documentation manual is about. The manual's + title is used inside the documentation and the manual's + directory name is used to store the related source files + inside the repository. As convenction, manual's title is a + few words phrase while manual's directory name is the + abbreviation of that phrase set as manual's title. + + + + Following with our example, the documentation manual was + initially titled The CentOS Artwork Repository File + System but that name was too long to remain that way, + so it was abbreviated soon into TCAR-FS which + is less descriptive but easier to remember and doesn't need to + be translated into other languages. The related manual's + directory for it would be + Tcar-fs in order to comply + with the file name convenctions described at . + + + diff --git a/Manuals/Tcar-ug/Manuals/Production/implementing-structure.docbook b/Manuals/Tcar-ug/Manuals/Production/implementing-structure.docbook new file mode 100644 index 0000000..0f44e27 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production/implementing-structure.docbook @@ -0,0 +1,84 @@ + + Implementing Document Structure + + + To create a manual like the one described in , + you need to use the help functionality of + centos-art.sh script as it is described in + the following list of commands: + + + + + + + centos-art help --edit "tcar-fs" + + + + This command creates the base structure of + TCAR-FS manual and opens its main + definition file with your favorite text editor so you can + update manual's definition values like title, subtitle, + author, etc. + + + + + + + centos-art help --edit "tcar-fs::trunk" + + + + This command creates the base structure for the + trunk chapter and opens its main definition + file with your favorite text editor so you can update the + chapter introduction. This very same procedure is used to + create branches and tags + chapters, just be sure to change the chapter field + accordingly. + + + + + + + centos-art help --edit "tcar-fs::trunk:identity" + + + + This command creates the identity section + inside the trunk chapter. If the chapter + doesn't exist it will be created first. In this command, the + identity section refers to trunk/Identity directory inside + &TCAR;. In order to document other directories, follow the + same procedure but using minus signs to separate directories. + For example, to document the trunk/Identity/Models/Themes + directory you should use the + tcar-fs::trunk:identity-models-themes + documentation entry. + + + + + In the very specific case of + TCAR-FS manual, it is also possible + to refer chapters and sections using a path/to/dir format. + For example, the reference + tcar-fs::trunk:identity-models-themes + can also be specified as trunk/Identity/Models/Themes, + in case you feel more confortable with it than the former + one. + + + + + + + diff --git a/Manuals/Tcar-ug/Manuals/Production/intro.docbook b/Manuals/Tcar-ug/Manuals/Production/intro.docbook new file mode 100644 index 0000000..b2cd59d --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production/intro.docbook @@ -0,0 +1,13 @@ + + + Introduction + + + This chapter describes the procedure you should follow to + produce and maintain manuals through texinfo documentation + backend inside &TCAR;. To illustrate this creation process, + we'll use the The CentOS Artwork Repository File + System (TCAR-FS) documentation manual as example. + + + diff --git a/Manuals/Tcar-ug/Manuals/Production/maintaining-structure.docbook b/Manuals/Tcar-ug/Manuals/Production/maintaining-structure.docbook new file mode 100644 index 0000000..de47040 --- /dev/null +++ b/Manuals/Tcar-ug/Manuals/Production/maintaining-structure.docbook @@ -0,0 +1,10 @@ + + Maintaining Document Structure + + Most maintaining tasks related to documentation manuals + written through texinfo documentation backend are standardized + by the help functionality of + centos-art.sh script, as described in . + +