[Phpmyadmin-devel] howto

[Marc Delisle]

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