One main goal => simplification:
Proposed Component Name
Reorganization of documentation
http://framework.zend.com/wiki/display/ZFDEV/Reorganization of documentation
0.1 - 7 January 2009: Initial Draft.
0.2 - 17 January 2009: Add Zend_Tool provider
0.3 - 17 March 2009: of the conversation between Thomas Weidner, Wil Sinclair, Matthew Weier O'Phinney and Mickael Perraud on IRC
0.4 - 22 March 2009: add informations about a new translator tool
0.5 - 25 April 2009: Added documentation standard (wiki revision: 33)
One main goal => simplification:
One main goal => simplification:
- FOP 0.95.0
This part is fully compatible with actual system without any BC. Goals are:
- centralized for all languages: figures, compilation process
- simplification of the translation and especially of the update
- enhance html rendering with syntax highlighting
- "create" pdf rendering with syntax highlighting
Centralized figures and compilation process:
- creation of a directory: "/trunk/documentation/build"
- creation of a directory: "/trunk/documentation/build/figures" for all figures, this could be modify by using "/trunk/documentation/manual/en/figures" for committing access if you need, Zend_Tool provider can verify if the images exist in language subdirectory and can take them.
- rewrite actual Makefile as Zend_Tool provider
- adding some PHP process
- creation html.xsl.in and pdf.xsl.in (based on actual ones)
Enhance CHM rendering:
- I already explain some parts in http://mikaelkael.fr/index.php?pages/Zend-Framework-CHM-Compilation even if it's not exactly what I have rewrite
Creation of pdf rendering:
- creation of the associated stylesheet to not fork docbook-xsl
- using of same images as CHM rendering
Maintain actual system with Zend_Tool provider:
- "zf clean manual"
- "zf check manual" => English doc
- "zf check manual fr" => French doc
- "zf build manual" => create HTML English doc
- "zf build manual html fr" => create HTML French doc
- "zf build manual chm" => create CHM English doc (need Html Help Workshoop, could be set ENVIRONMENT variable)
- "zf build manual chm fr" => create CHM French doc
- "zf build manual pdf-fop" => create PDF English doc with fop
- "zf build manual pdf-fop fr" => create PDF French doc with fop
Needed (in addition to http://framework.zend.com/wiki/display/ZFDEV/Translator+-+Manual+Compilation+Instructions):
- FOP 0.95.0
This could be realized by using xml entities. See http://framework.zend.com/svn/framework/standard/branches/user/mikaelkael/manual/manual.xml.in and http://framework.zend.com/svn/framework/standard/branches/user/mikaelkael/manual/en/language-defs.ent . We have to create language-defs.ent for each language. The manual.xml.in contains the fall back to English documentation.
Some actual files are very long to translate (Zend_Db_Adapter), divisions will facilitate the translation and especially the update. In the same idea, as mentioned in the comments of this page, it would be good to limit the size (in number of words for example) of a generated page (in HTML or CHM format).
To be sure that all languages will contain all files, we have to limit the using of 'xinclude' in /module_specs/* or /ref/* files. This could be easier if we apply the precedent paragraph (cutting).
My main example is 'requirements.xml'. We have to create snippets for table titles and headers, and for the word 'Hard' and 'Soft'. With this, the file 'requirements.xml' don't need to be translate (or update) each time.
Example updates are the most important documentation updates. The main reason we don't share them at this point is translation of the comments.
The first step is to link examples, this must be done by adding an id to all programlisting tags. After there is two possibilities, translations of the comments or not.
In English, we'll have for example:
In translated files, we'll just have:
or with translations of the comments:
This syntax allow to test English examples (parse error for examples). At time of rendering, we can remove '#\d+#' tags. If we add a comment in English example and it isn't translated then we fallback to English comments. The order of the comments is not important so we could add or remove them in English file if necessary. If we have phpDoc in the example without '#\d#' tag, we don't search for translations.
To improve the look and feel of the manual, and to get all chapters and pages rendered in the same style even if multiple people are involved a documentation standard has to be applied.
The following rules should be forced to all translation files:
Maximum line length of 100 chars including tags and attributes and intendation.
There is only one exception to this rule. Attributes themself are allowed to exceed the 100 chars as they are not allowed to be seperated.
Tags which are at the same level must have the same intendation
Tags which are one level under the previous tag must be intended with 4 additional spaces
It is not allowed to have multiple tags within one line
Beginning programmlisting must apply role of php, cdata and starting intendation
Programmlistings must not add linebreaks or whitespaces at the beginning or the end, as they would then be rendered.
Ending CDATA Tag and programmlisting at the same line
Tags at the same level must be seperated by a empty line to improve readability
The tag classname must be used for all Zend Framework classes. The code tag is not allowed. This rule has only to be applied if the classname stands alone. Other content is not allowed within this tag.
Variables must be wrapped in the varname tag. Variables must be written with $ otherwise they are not recognised as variables. Other content is not allowed within this tag.
Methods must be wrapped in the methodname tag. Methods must be written with () otherwise they are not recognised as methods. Other content is not allowed within this tag.
Constants must be wrapped in the constant tag. Constants must be written UPPERCASE otherwise they are not recognised as constants. Other content is not allowed within this tag.
Filenames and paths must be wrapped in the filename tag. They must include eighter a "." or "/" char. Other content is not allowed within this tag.
Commands and programm calls must be wrapped in the command tag. Commands must include a whitespace otherwise they are not recognised as variables. Other content is not allowed within this tag.
The usage of the code tag is not allowed in favor of seperation to filename, varname and constant.
The title is not allowed to hold any tags
Ending spaces are not allowed
Multiple new lines are not allowed
Empty tags (para, example and others) are not allowed. They must contain text or underlaying tags.
The usage of TABS is not allowed. Instead intendation of 4 spaces must be used.
Only Unix lineendings are allowed. Other line endings like Windows or Mac are must not be used.
Each manual file has to include the following xml declarations at file start
XML Files from translated languages must also include a revision tag which must notify the revision of the english file this translation is based of.
Short tags must not be used. Wether in description nor in code.
Note that there already exists a tool which checks parts of this standard. You can find it under: http://mikaelkael.dyndns.org/checker
After etablishing rules (with this proposal) on standard manual, we just have to apply same rules in extras documentation.
Actual quickstart (http://framework.zend.com/docs/quickstart) could be translate in Docbook format and put in http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/en/quickstart or in http://framework.zend.com/svn/framework/standard/trunk/documentation/quickstart/en
For the moment, table of contents ar only rendered for level 1 section (http://framework.zend.com/manual/en/zend.acl.html has a toc but not http://framework.zend.com/manual/en/zend.acl.refining.html). We could add TOC for all rendered file by using http://docbook.sourceforge.net/release/xsl/current/doc/html/generate.section.toc.level.html
This part is a big one. An automatic index could be rendered by adding index tag inside all the actual docuementation. For example, to add an index 'Zend_Acl' in Zend_Acl-Advanced.xml, we have to replace:
The job of determination of the words (or sentences) to index must be do in English and can change in translated files.
Modify MANUAL TRANSLATION STATUS (http://framework.zend.com/manual/status)
This page doesn't really show if a translation is outdated or not. If I take SVN 13906 to SVN 13930, these commits are just to modify tabs to spaces. Actual manual status is not able to see difference between real changes or 'esthetic' changes. Since a long time, some translators (French, Japanese or Deutsch) use a revision tag at the top of their translations to differentiate real and 'esthetic' changes:
Here is a link to test a new translator tool: http://mikaelkael.dyndns.org/checkzf. This tool can:
- check if you use the revision tag and takes it in this case, otherwise it takes the last revision change (like today in http://framework.zend.com/manual/status)
- show you the out-of-date and the non translated files, instead of showing you all the files.
- can retrieve for an out-of-date file the difference of the English file between the last translated revision and the last revision of English file, so if they are multiples revisions of the English file, they are all compile (it take into account reorganization of the SVN in revision 9506).
- can show you the last building check and associated output.
- can show you difference of number of tags between English and translated file. This is available for multiple tags: 'sectX', 'para', example'...
Because many of us are no native English, it would be great to add a documentation review. This could be simply do by adding a special tag at the top of the file:
When a new part is added, the tag is setting to no. You will find below a script that can render reviewed page based on this tag. This could be used of course for English files but also for translated ones.
At least, we should test for parse error. Then we could link examples between them with special comments which would be cleared at the time of rendering. For example with Zend_Db, the first with id 'zend.db.adapter.connecting.constructor.example' that describe the connection could be call by the second one:
Actually we have a migration chapter for each component. This makes it very difficult when you want to migrate to a new release as the user must search every single component if there are migration notes.
To make things easier we should add a single migration chapter where all migration notes from all components are collected. So the user has one place where all migration notes are displayed. Within the component chapter a link can be places to the migration chapter. This makes live much easier for all people who want to update to a new release.
... (see good use cases book)