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?
Do you mean that we would not put the source doc directory in the distribution kits?
Also, some images will be common between languages, some won't (i.e. screenshots).
The XML format will basically be a structured XML document, in which some nodes will be able to have a limited set of HTML tags in them (bold, italitcs etc. NO structual tags). It will make heavy use of the XInclude standard to get seperate files. Rough file system structure idea for system: src/xslt/xml-big.xml src/xslt/html-big.xml src/xslt/html-split.xml src/xslt/html-common.xml src/xslt/pdf.xml src/xslt/docbook.xml src/english-iso-8859-1/master.xml src/english-iso-8859-1/top.xml src/english-iso-8859-1/requirements.xml src/english-iso-8859-1/introduction.xml src/english-iso-8859-1/installation.xml src/english-iso-8859-1/config.xml src/english-iso-8859-1/config/PmaAbsoluteUri.xml src/english-iso-8859-1/config/PmaAbsoluteUri_DisableWarning.xml src/english-iso-8859-1/config/Servers.connect_type.xml src/english-iso-8859-1/config/... (more files go here) src/english-iso-8859-1/config/Functions.xml src/english-iso-8859-1/faq.xml src/english-iso-8859-1/faq/1.1.xml src/english-iso-8859-1/faq/1.2.xml src/english-iso-8859-1/faq/... src/english-iso-8859-1/faq/5.1.xml src/english-iso-8859-1/faq/5.2.xml src/english-iso-8859-1/faq/... src/english-iso-8859-1/faq/7.3.xml src/english-iso-8859-1/howto.xml src/english-iso-8859-1/howto/qbe/... src/english-iso-8859-1/howto/(whatever other howtos get written)/... src/english-iso-8859-1/developers.xml src/english-iso-8859-1/credits.xml src/french-iso-8859-1/(same files as english, just with french content) src/images/... bin/... (scripts go here) output/xml-big/ (empty on CVS tree) output/html-big/ ("") output/html-split/ ("") output/pdf/ ("") output/docbook/ ("")
(master.xml is the root file)
I'll see about putting together a prototype idea over the weekend.
This will allow us to finally have translated documentation as well :-) Plus maintaining just one little xml file for each part of the application is a lot easier.
You can do a distinct document (howto-qbe or whatever) with screenshots. I am not familiar with the best way to structure the doc, but I guess that Documentation.html (and .txt) is getting too big.
ok, we agreed that we would keep the doku in one file - was there also allready agreement to keep the howtos within the same file? reason is i just rewrote db_details_qbe quite heavily, so next thing i'll have to go over the docu that Marc wrote as a usage tip for this, and i'd like to do this with some nice screenshots - however if it stays in one page with the docu i won't as it would get too big to load then.
Make a new document for now, with screenshots in PNG format (saved in the images directory, use a unique naming system maybe howto-qbe-####.png).
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.
-
Marc Delisle -
Robin Johnson