6:06 a.m.
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