Details
-
Type:
Docs: Problem
-
Status:
Resolved
-
Priority:
Minor
-
Resolution: Fixed
-
Affects Version/s: 0.2.0
-
Fix Version/s: 0.6.0
-
Component/s: None
-
Labels:None
Description
All our documentation is written with docbook.
As all docbook files are written in xml we also have to be aware of correct xml syntax.
This makes the wikifikation easier and prevents problems with automatic xml syntaxcheckers as used within several development GUIs.
So the following things I found which have to be corrected in ALL documentation languages :
&code;
No known entity... just change it to & #169; (without space) which is the same sign but only in HTML-UTF8 notation.
<sect1>
Some docufiles contain multiple base sections. Within XML only one base tag is allowed.
Also it's more consistent to have one xml file per docu-page.
So all sect1 parts have to be seperated in single xml files.
See english Zend_Cache for example how to do this.
&module_specs.
Some documents have &module_spec's assigned within their document.
It is not allowed to have trailing content after finishing the basetag.
To fix this the module_spec pars have to be added within the manual.xml file.
See english Zend_XmlRpc for example.
Naming of documentation files
We have a unknown standard for the naming of documentation files.
Always use class_subclass-description.xml syntax.
Where as class_subclass can be used without description when no additional page was found.
See english docu:
Zend_Cache is seperated in "-Backend" "-Frontend" "-Introduction" and "-Theory".
Zend_Xml-Rpc on the other hand is just a single file so no additional description is needed.
Never use an underline for description as underline is reserved for the classes.
The problem were fixed.
But of course with all new commited docu files the problem becomes actual.
Errors can be viewed within http://www.gavin.zfdev.com/doc/ to be corrected when showing up