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).