Marc Delisle wrote:
Robin Johnson wrote:
Hi List.
Marc Delisle wrote:
It's time for a /docs directory, with smaller documents. Someone (Robin?) suggested to use XML or DocBook format.
The only thing I will regret is searching with the browser in Documentation.html. Another idea was to put the doc in a table
located
in the pmadb, and we integrate a small search engine. But this would not be good as users would need the doc to install the doc :)
Maybe a splitted doc and a well-made index would make me happy :)
Here is my proposal: We start a seperate directory in the CVS for the documentation, and inside it we have the master files in XML format, plus the scripts to build the HTML/PDF formats.
We will still be generating a big Documentation.html file, but our sources will be seperated to make for easier editing. There will be a Documentation version where the sections are split up as well. All generated from the same XML data.
Mike's point was that the resulting doc would be too big to load, if he adds screenshots for QBE explanations. Does the new structure address this problem?
Define "too big to load", as I regularly load 10 meg HTML documents and use them for reference (SGI technical publications).
The All on one page version of the MySQL documentation http://www.mysql.com/documentation/mysql/full/ is 2.5 megabytes in size.
This is the point of having the HTML-split form, for those that don't want to load a massive HTML page, and instead just use little pages.
Do you mean that we would not put the source doc directory in the distribution kits?
Definetly not.
The only thing included with the main distribution will be a single copy of the english documentation, for size reasons.
There will be additional download packages containing the documentation in other formats and languages.
Also, some images will be common between languages, some won't (i.e. screenshots).
Actually, thinking about this, every screenshot will be per language, as we don't have any graphical screens really. So we will just move those image/ directories to inside the language directories.