[Kimchi-devel] [PATCH RFC] doc: Add DITA help pages

[Crístian Viana]

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.

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.

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

-- 
1.8.5.3