diff --git a/Manuals/Repository/Docbook/Introduction/history.docbook b/Manuals/Repository/Docbook/Introduction/history.docbook index 0cf2f3d..3b362bc 100644 --- a/Manuals/Repository/Docbook/Introduction/history.docbook +++ b/Manuals/Repository/Docbook/Introduction/history.docbook @@ -79,9 +79,10 @@ Olins (1989) and Wikipedia related links. This way, the rendition script main's goal - becomes into: automating production of a monolithic corporate - visual identity structure, based on the mission and the - release schema of The CentOS Project. + becomes to: automate the production process of a + monolithic corporate visual identity structure, based on the + mission and the release schema of The CentOS + Project. diff --git a/Manuals/Repository/Docbook/Introduction/usage.docbook b/Manuals/Repository/Docbook/Introduction/usage.docbook index f1ba9df..6b1d9ae 100644 --- a/Manuals/Repository/Docbook/Introduction/usage.docbook +++ b/Manuals/Repository/Docbook/Introduction/usage.docbook @@ -1,6 +1,6 @@ - Usage convenctions + Repository convenctions The CentOS Artwork Repository is supported by Subversion (http://subversion.tigris.org/), a version control system which diff --git a/Manuals/Repository/Docbook/Manuals.ent b/Manuals/Repository/Docbook/Manuals.ent index 5919e6d..8bb6cd7 100644 --- a/Manuals/Repository/Docbook/Manuals.ent +++ b/Manuals/Repository/Docbook/Manuals.ent @@ -6,3 +6,4 @@ + diff --git a/Manuals/Repository/Docbook/Manuals/Docbook.docbook b/Manuals/Repository/Docbook/Manuals/Docbook.docbook index f7cff53..671428c 100644 --- a/Manuals/Repository/Docbook/Manuals/Docbook.docbook +++ b/Manuals/Repository/Docbook/Manuals/Docbook.docbook @@ -1,20 +1,7 @@ - The DocBook backend + DocBook Backend - - Overview - ... - - - - How to create new manuals - ... - - - - How to maintain manuals - ... - + &manuals-docbook-intro; diff --git a/Manuals/Repository/Docbook/Manuals/Docbook/intro.docbook b/Manuals/Repository/Docbook/Manuals/Docbook/intro.docbook new file mode 100644 index 0000000..ce80f3c --- /dev/null +++ b/Manuals/Repository/Docbook/Manuals/Docbook/intro.docbook @@ -0,0 +1,9 @@ + + + Introduction + + + ... + + + diff --git a/Manuals/Repository/Docbook/Manuals/Texinfo.docbook b/Manuals/Repository/Docbook/Manuals/Texinfo.docbook index 3424f68..b3702b3 100644 --- a/Manuals/Repository/Docbook/Manuals/Texinfo.docbook +++ b/Manuals/Repository/Docbook/Manuals/Texinfo.docbook @@ -1,6 +1,6 @@ - The Texinfo backend + Texinfo Backend &manuals-texinfo-intro; &manuals-texinfo-structure; diff --git a/Manuals/Repository/Docbook/Manuals/Texinfo/encoding.docbook b/Manuals/Repository/Docbook/Manuals/Texinfo/encoding.docbook index e77e506..3d72a9b 100644 --- a/Manuals/Repository/Docbook/Manuals/Texinfo/encoding.docbook +++ b/Manuals/Repository/Docbook/Manuals/Texinfo/encoding.docbook @@ -1,5 +1,5 @@ - Document encoding + Document Encoding ... diff --git a/Manuals/Repository/Docbook/Manuals/Texinfo/intro.docbook b/Manuals/Repository/Docbook/Manuals/Texinfo/intro.docbook index 7410942..857d75e 100644 --- a/Manuals/Repository/Docbook/Manuals/Texinfo/intro.docbook +++ b/Manuals/Repository/Docbook/Manuals/Texinfo/intro.docbook @@ -27,4 +27,12 @@ is no functionality to help you doing such things, yet. + + The Texinfo documentation backend could result useful to you + if your only need is to document directory structures in a + manual that follows, exactly, the same organization of the + structure it documents (e.g., one directory one documentation + entry for it). + + diff --git a/Manuals/Repository/Docbook/Manuals/Texinfo/localizing.docbook b/Manuals/Repository/Docbook/Manuals/Texinfo/localizing.docbook index d2f1d05..871f277 100644 --- a/Manuals/Repository/Docbook/Manuals/Texinfo/localizing.docbook +++ b/Manuals/Repository/Docbook/Manuals/Texinfo/localizing.docbook @@ -1,4 +1,4 @@ - - Document localization + + Document Localization ... diff --git a/Manuals/Repository/Docbook/Manuals/Texinfo/structure.docbook b/Manuals/Repository/Docbook/Manuals/Texinfo/structure.docbook index c6c36b5..f79669a 100644 --- a/Manuals/Repository/Docbook/Manuals/Texinfo/structure.docbook +++ b/Manuals/Repository/Docbook/Manuals/Texinfo/structure.docbook @@ -1,35 +1,110 @@ - Document structure + Document Structure - Based on the fact that there is only one repository directory - structure to document, there is only one documentation manual - structure based on Texinfo documentation backend to maintain, - for each language we want to provide support. + The document structure provides the organization needed to + make the documentation scalable and maintainable through time + which, in turn, involves document sectioning and file + organization inside specific locations of the working copy. + The document structure is also a convenction we adopt in order + to automate frequent tasks related to the document structure + itself. Without a well defined document structure convenction, + it would be very difficult for automation script to guess + where the documentation files are. - Each language-specific documentation structure based on - Texinfo documentation backend is stored in the trunk/Manuals/Repository - directory. Inside this location, we use the file - repository-init.pl, - repository.css and - repository.sed to control common - characteristics of all language-specific document structures - (e.g., common initialization of texi2html - as well as common visual styles and transformations applied to - final XHTML output). + The file organization of Texinfo documentation backend takes + place in trunk/Manuals/Repository/Texinfo/ + directory. Inside this location there is one documentation + structure for each language you want to support and the + repository-init.pl and + repository.sed files which let you + control common characteristics of final XHTML output (e.g., + texi2html initialization, and markup + transformations). - - Texinfo document structure. + + The document sectioning follows the idea of an upside-down + tree to organize chapters, sections, subsections, and the + like. The document initiates with a Top node where we placed + document's title, copyright note, abstract, and a list of + available chapters to start browsing. Inside each chapter the + information is logically organized in sections which in turn + are subdivided in subsections and subsubsections. + + + + The Texinfo document structure produced by + help functionality organizes information + in two chapters only, which are: + + + + + + Directories — This chapter organizes documentation + entries related to repository directories. In the normal + work flow, you don't need to touch the files of this + chapter by your own. For that purpose, the + centos-art.sh script porovides the + help functionality. To manipulate + documentation entries in this chapter, you use the + help functionality as described in + . + + + + + + Licenses — This chapter includes licenses from + trunk/Scripts/Functions/Help/Texinfo/Templates/$LANG/Licenses/ + directory. In the normal work flow, you don't need to + touch this chapter. It is created when the document + structure is created and should ramain that way. If you + need to improve the markup, update the template files for + your language, not the content of this chapter. + + + + + + + + + At the same level of chapter directories, the + repository.texinfo, + repository-index.texinfo, + repository-menu.texinfo and + repository-nodes.texinfo files exist to + set manual's main definitions (e.g., title, copyright notice, + chapters, appendixes, indexes and all the similar stuff a + documentation manual should have). + + + Inside each chapter directory, the + chapter.texinfo, + chapter-menu.texinfo and + chapter-nodes.texinfo files exist to + control definition of sections. In addition to these files, + there are documentation entries to store the document's content + itself, using arbitrary file names prefixed with the texinfo extension, just as it is + illustrated in . + + + + The Texinfo document structure. - Texinfo document structure. + The Texinfo document structure. - trunk/Manuals/Repository + trunk/Manuals/Repository/Texinfo |-- $LANG | |-- Directories | | |-- chapter-menu.texinfo @@ -37,11 +112,6 @@ | | |-- chapter.texinfo | | |-- trunk/Identity.texinfo | | `-- trunk.texinfo -| |-- Introduction -| | |-- chapter-menu.texinfo -| | |-- chapter-nodes.texinfo -| | |-- chapter.texinfo -| | `-- history.texinfo | |-- Licenses | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo @@ -58,59 +128,4 @@ - - Inside each language-specific directory, we have the Introduction, Directories and Licenses directories to cover - manual's introduction, documentation of repository directories - and license information. In addition to these directories, we - also have the repository.texinfo, - repository-index.texinfo, - repository-menu.texinfo and - repository-nodes.texinfo files to make up - the manual's main structure (e.g., title, copyright notice, - chapters, appendixes, indexes and all the similar stuff a - documentation manual should have). - - - - Inside chapter directories, we have at least the files - chapter.texinfo, - chapter-menu.texinfo and - chapter-nodes.texinfo to control section - definitions inside the chapter. In addition to these files, we - have documentation entries to store the information itself. - - - - Inside Introduction - directory, documentation entries are managed without any - functionality's help, you need to take care of them by your - own. - - - - Inside Directories - directory, documentation entries are all managed by the - help functionality and you don't need to - take care of them. To manage documentation entries here you - need to use the help functionality as - described in . - - - - Inside Licenses - directory, there aren't documentation entries. Instead, they - are imported from trunk/Scripts/Functions/Help/Templates/$LANG/Licenses/ - directory. We did it this way to reuse license files when - different language-specific document structures, based on - Texinfo documentation backend, are created for first time. - There is no need to duplicate the license files inside each - language-specific document structure if they can be placed in - a single location and then be imported to reduce the amount of - files in need of maintainance. - - diff --git a/Manuals/Repository/Docbook/Manuals/Texinfo/templates.docbook b/Manuals/Repository/Docbook/Manuals/Texinfo/templates.docbook index 9d29e9b..0ba3d41 100644 --- a/Manuals/Repository/Docbook/Manuals/Texinfo/templates.docbook +++ b/Manuals/Repository/Docbook/Manuals/Texinfo/templates.docbook @@ -1,5 +1,5 @@ - Document templates + Document Templates ...