On 02/03/2014 12:24 AM, CrÃstian Viana wrote:
Hi!
I am starting to create this patch to add documentation pages to Kimchi. The idea is to have the help content in XML files in a help-specific format (DITA) which will be processed, using XSTL, to generate the HTML pages. I am sending three sample DITA files (Storage, Templates and Virtual Machines), the XSL file and also the generated HTML files for that documentation. Please note that the HTML files will not be added to the final versions, they will be generated dynamically (e.g. via Makefile) when building the distribution package. The command "xsltproc <XSL file> <DITA file>" generates the HTML output corresponding to the DITA file processed by the XSL file. The current version of the XSL file generates a simple HTML output, but we will enhance it over time. And, obviously, we can apply a CSS file to make it look pretty.
Yeap. The HTML files are simple but we can give them a better look through CSS files. In my mind, I would like to see a table of contents with links to sub-sections. Maybe for that we need to change the DITA file structure.
Instead of preprocessing the DITA files to generate the HTML files statically, there is also the option to process them in the client side using the client's browser. A single line in the DITA file can tell the browser to do so. Most modern browsers are able to process XML files linked to an XSL file dynamically. However, for security reasons, Google Chrome does not allow a local file to load another local file (i.e. the DITA file cannot load the XSL file), so this client-side process does not work on Chrome locally. When we improve this patch and integrate it to Kimchi, when the files will be served using a web server, I believe Chrome will transform them correctly. But that is only another way of displaying the HTML files; we can always process them statically to generate the HTML files. We can decide later which approach we will use.
I personally prefer the first approach. That way we don't depend on browser support/functionalities to have the HTML files exposed to user. And as we support a lot of different browser (desktop and mobile ones) it will be safer to generate the HTML files by ourselves.
Keep in mind that this patch is not finished yet.
Any feedback is welcome.
CrÃstian Viana (1): doc: Add DITA help pages
dita/dita.xsl | 23 +++++++++++++++++++++ dita/kimhstor.dita | 45 ++++++++++++++++++++++++++++++++++++++++ dita/kimhstor.html | 31 ++++++++++++++++++++++++++++ dita/kimhtempl.dita | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++ dita/kimhtempl.html | 38 ++++++++++++++++++++++++++++++++++ dita/kimhvirtm.dita | 47 ++++++++++++++++++++++++++++++++++++++++++ dita/kimhvirtm.html | 30 +++++++++++++++++++++++++++ 7 files changed, 273 insertions(+) create mode 100644 dita/dita.xsl create mode 100644 dita/kimhstor.dita create mode 100644 dita/kimhstor.html create mode 100644 dita/kimhtempl.dita create mode 100644 dita/kimhtempl.html create mode 100644 dita/kimhvirtm.dita create mode 100644 dita/kimhvirtm.html