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

[Aline Manera]

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
>