8:24 p.m.
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
8:24 p.m.
New subject: [PATCH] doc: Add DITA help pages
Signed-off-by: Crístian Viana <vianac(a)linux.vnet.ibm.com>
---
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
diff --git a/dita/dita.xsl b/dita/dita.xsl
new file mode 100644
index 0000000..9d0e080
--- /dev/null
+++ b/dita/dita.xsl
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns="http://www.w3.org/1999/xhtml">
+ <xsl:output method="xml" indent="yes"
encoding="UTF-8" />
+
+ <xsl:template match="/">
+ <html>
+ <head>
+ <title><xsl:value-of select="/cshelp/title"
/></title>
+ </head>
+ <body>
+ <xsl:apply-templates select="//cshelp" />
+ </body>
+ </html>
+ </xsl:template>
+
+ <xsl:template match="cshelp">
+ <h1><xsl:value-of select="title" /></h1>
+ <p class="shortdesc"><xsl:value-of
select="shortdesc" /></p>
+ <p class="csbody"><xsl:copy-of
select="csbody/node()" /></p>
+ </xsl:template>
+</xsl:stylesheet>
diff --git a/dita/kimhstor.dita b/dita/kimhstor.dita
new file mode 100644
index 0000000..f9ae93e
--- /dev/null
+++ b/dita/kimhstor.dita
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet href="dita.xsl" type="text/xsl" ?>
+<?Pub Sty _display FontColor="red"?>
+<?Pub Inc?>
+<cshelp id="kimhstor" xml:lang="en-us">
+ <title>Storage</title>
+ <shortdesc>The Storage page lists the available storage pools, including the
default storage pool.</shortdesc>
+ <csprolog>
+ <csmetadata>
+ <cswindowtitle>Title of window or panel associated with this help; for
review output only.</cswindowtitle>
+ <cswidgetlabel>Name of field or control associated with this help; for
review output only</cswidgetlabel>
+ </csmetadata>
+ </csprolog>
+ <csbody>
+ <p>For each storage pool, the following information is
displayed:<dl><dlentry><dt>Name</dt><dd>Name of the storage
pool and percentage
used.</dd></dlentry><dlentry><dt>State</dt><dd>State
of the storage pool, active (green) or inactive (red).
</dd></dlentry><dlentry><dt>Location</dt><dd>File path
to the location of the storage
pool.</dd></dlentry><dlentry><dt>Type</dt><dd><uicontrol>dir</uicontrol>
for
directory.</dd></dlentry><dlentry><dt>Capacity</dt><dd>Amount
of space in the storage
pool.</dd></dlentry><dlentry><dt>Allocated</dt><dd>Amount
of space already allocated in the storage
pool.</dd></dlentry></dl></p>
+ <p>The following actions can be selected for each storage
pool:<ul><li>Select <uicontrol>Activate</uicontrol> to activate
the storage
+pool so that it can be used.</li><li>Select
<uicontrol>Undefine</uicontrol> to remove an inactive storage
+pool.</li></ul></p>
+ <p>To display storage volume details for a storage pool, click the
+arrow on the right side of the storage pool row. Details include
+the following:<dl><dlentry><dt>Type</dt><dd>The type of
storage pool, for example, dir or
disk.</dd></dlentry><dlentry><dt>Format</dt><dd>The
format, varying dependent on the
type.</dd></dlentry><dlentry><dt>Capacity</dt><dd>Size
of the storage
volume.</dd></dlentry><dlentry><dt>Allocated</dt><dd>Amount
of space already allocated in the storage pool.</dd></dlentry></dl>To
define a storage pool, click the <uicontrol>plus
+(+)</uicontrol> icon in the upper right of the display.</p>
+ </csbody>
+ <cshelp id="kimhdefstor" xml:lang="en-us">
+ <title>Define a storage pool</title>
+ <shortdesc> Define a storage pool.</shortdesc>
+ <csprolog>
+ <csmetadata>
+ <cswindowtitle>Title of window or panel associated with this help;
for review output only.</cswindowtitle>
+ <cswidgetlabel>Name of field or control associated with this help;
for review output only</cswidgetlabel>
+ </csmetadata>
+ </csprolog>
+ <csbody>
+ <p>
+ <ol>
+ <li>Type the name to be used to identify the storage
pool.</li>
+ <li>Type the file path to the storage pool.</li>
+ <li>Click
<uicontrol>Create</uicontrol>.</li>
+ </ol>
+ </p>
+ </csbody>
+ </cshelp>
+ <?Pub Caret -1?>
+</cshelp>
+<?Pub *0000003013?>
diff --git a/dita/kimhstor.html b/dita/kimhstor.html
new file mode 100644
index 0000000..bcf8bac
--- /dev/null
+++ b/dita/kimhstor.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Storage</title>
+ </head>
+ <body>
+ <h1>Storage</h1>
+ <p class="shortdesc">The Storage page lists the available storage
pools, including the default storage pool.</p>
+ <p class="csbody">
+ <p xmlns="">For each storage pool, the following information is
displayed:<dl><dlentry><dt>Name</dt><dd>Name of the storage
pool and percentage
used.</dd></dlentry><dlentry><dt>State</dt><dd>State
of the storage pool, active (green) or inactive (red).
</dd></dlentry><dlentry><dt>Location</dt><dd>File path
to the location of the storage
pool.</dd></dlentry><dlentry><dt>Type</dt><dd><uicontrol>dir</uicontrol>
for
directory.</dd></dlentry><dlentry><dt>Capacity</dt><dd>Amount
of space in the storage
pool.</dd></dlentry><dlentry><dt>Allocated</dt><dd>Amount
of space already allocated in the storage
pool.</dd></dlentry></dl></p>
+ <p xmlns="">The following actions can be selected for each
storage pool:<ul><li>Select <uicontrol>Activate</uicontrol> to
activate the storage
+pool so that it can be used.</li><li>Select
<uicontrol>Undefine</uicontrol> to remove an inactive storage
+pool.</li></ul></p>
+ <p xmlns="">To display storage volume details for a storage pool,
click the
+arrow on the right side of the storage pool row. Details include
+the following:<dl><dlentry><dt>Type</dt><dd>The type of
storage pool, for example, dir or
disk.</dd></dlentry><dlentry><dt>Format</dt><dd>The
format, varying dependent on the
type.</dd></dlentry><dlentry><dt>Capacity</dt><dd>Size
of the storage
volume.</dd></dlentry><dlentry><dt>Allocated</dt><dd>Amount
of space already allocated in the storage pool.</dd></dlentry></dl>To
define a storage pool, click the <uicontrol>plus
+(+)</uicontrol> icon in the upper right of the display.</p>
+ </p>
+ <h1>Define a storage pool</h1>
+ <p class="shortdesc"> Define a storage pool.</p>
+ <p class="csbody">
+ <p xmlns="">
+ <ol>
+ <li>Type the name to be used to identify the storage
pool.</li>
+ <li>Type the file path to the storage pool.</li>
+ <li>Click
<uicontrol>Create</uicontrol>.</li>
+ </ol>
+ </p>
+ </p>
+ </body>
+</html>
diff --git a/dita/kimhtempl.dita b/dita/kimhtempl.dita
new file mode 100644
index 0000000..0a9bcff
--- /dev/null
+++ b/dita/kimhtempl.dita
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?Pub Sty _display FontColor="red"?>
+<?Pub Inc?>
+<cshelp id="kimhtempl" xml:lang="en-us">
+ <title>Templates</title>
+ <shortdesc>The Templates page shows the defined virtual machine templates
+that can be used to create KVM virtual machines.</shortdesc>
+ <csprolog>
+ <csmetadata>
+ <cswindowtitle>Title of window or panel associated with this help;
+for review output only.</cswindowtitle>
+ <cswidgetlabel>Name of field or control associated with this help;
+for review output only</cswidgetlabel>
+ </csmetadata>
+ </csprolog>
+ <csbody>
+ <p>For each template, the following information is
displayed:<dl><dlentry><dt>OS</dt><dd>Name of the operating
system or
distribution.</dd></dlentry><dlentry><dt>Version</dt><dd>Version
of the operating system or
distribution.</dd></dlentry><dlentry><dt>CPU</dt><dd>Number
of processors defined for the
template.</dd></dlentry><dlentry><dt>Memory</dt><dd>Amount
of random access memory to be allocated, in
MB.</dd></dlentry></dl></p>
+ <p>The following actions can be selected for each
template:<ul><li>Select <uicontrol>Edit</uicontrol> to edit the
template.</li><li>Select <uicontrol>Delete</uicontrol> to delete
the template.</li></ul>To add a template, click the <uicontrol>plus
(+)</uicontrol> icon
+in the upper right of the display.</p>
+ </csbody>
+ <cshelp id="kimhedittempl" xml:lang="en-us">
+ <title>Edit template</title>
+ <shortdesc>Edit an existing template.</shortdesc>
+ <csprolog>
+ <csmetadata>
+ <cswindowtitle>Title of window or panel associated with this help;
+for review output only.</cswindowtitle>
+ <cswidgetlabel>Name of field or control associated with this help;
+for review output only</cswidgetlabel>
+ </csmetadata>
+ </csprolog>
+ <csbody>
+ <p><ol><li>Edit the following information for the
template:<dl><dlentry><dt>Name</dt><dd>Name of the
template.</dd></dlentry><dlentry><dt>CPU</dt><dd>Number
of processors defined for the
template.</dd></dlentry><dlentry><dt>Memory</dt><dd>Memory
to be allocated to the virtual
machine.</dd></dlentry></dl></li><li>Click
<uicontrol>Save</uicontrol>.</li></ol>The following information is
displayed but cannot be
edited:<dl><dlentry><dt>Vendor</dt><dd>The name of the
company that created the operating system or distribution
+that the template is configured to
use.</dd></dlentry><dlentry><dt>Version</dt><dd>The
version of the operating system or distribution that the template
+is configured to use.</dd></dlentry></dl></p>
+ </csbody>
+ </cshelp>
+ <?Pub Caret -1?>
+ <cshelp id="kimhaddtempl">
+ <title>Add template</title>
+ <shortdesc>Add a template from source media.</shortdesc>
+ <csbody>
+ <p>Select the location from the following
options:<ol><li>Select the location of the source media from the following
options:<dl><dlentry><dt>Local ISO image</dt><dd>Select to
scan storage pools for installation ISO images available
+on the system.</dd></dlentry><dlentry><dt>Remote ISO
image</dt><dd>Select to specify a remote location for an installation ISO
image.</dd></dlentry></dl></li><li>Click
<uicontrol>Create</uicontrol>.</li></ol></p>
+ </csbody>
+ </cshelp>
+ <cshelp id="kimhaddloct">
+ <title>Add template - local ISO image</title>
+ <shortdesc>Add a template from a local ISO image.</shortdesc>
+ <csbody>
+ <p>The ISO images available on the system are
displayed.<dl><dlentry><dt>OS</dt><dd>Name of the operating
system or
distribution.</dd></dlentry><dlentry><dt>Version</dt><dd>Version
of the operating system or
distribution.</dd></dlentry><dlentry><dt>Size</dt><dd>Size
of the ISO image.</dd></dlentry></dl></p>
+ <p>To create a template from an ISO image, complete the following
+steps:<ol><li>Choose from the following options:<ul><li>Select an
ISO image from which to create a template.</li><li>Select the
<uicontrol>All</uicontrol> check box to create a template
+from each listed ISO image.</li><li>Select the <uicontrol>I want to
use a specific file</uicontrol> check
+box to specify a path to the ISO image.</li></ul></li><li>Click
<uicontrol>Create</uicontrol>.</li></ol></p>
+ </csbody>
+ </cshelp>
+</cshelp>
+<?Pub *0000004376?>
diff --git a/dita/kimhtempl.html b/dita/kimhtempl.html
new file mode 100644
index 0000000..56be13a
--- /dev/null
+++ b/dita/kimhtempl.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Templates</title>
+ </head>
+ <body>
+ <h1>Templates</h1>
+ <p class="shortdesc">The Templates page shows the defined virtual
machine templates
+that can be used to create KVM virtual machines.</p>
+ <p class="csbody">
+ <p xmlns="">For each template, the following information is
displayed:<dl><dlentry><dt>OS</dt><dd>Name of the operating
system or
distribution.</dd></dlentry><dlentry><dt>Version</dt><dd>Version
of the operating system or
distribution.</dd></dlentry><dlentry><dt>CPU</dt><dd>Number
of processors defined for the
template.</dd></dlentry><dlentry><dt>Memory</dt><dd>Amount
of random access memory to be allocated, in
MB.</dd></dlentry></dl></p>
+ <p xmlns="">The following actions can be selected for each
template:<ul><li>Select <uicontrol>Edit</uicontrol> to edit the
template.</li><li>Select <uicontrol>Delete</uicontrol> to delete
the template.</li></ul>To add a template, click the <uicontrol>plus
(+)</uicontrol> icon
+in the upper right of the display.</p>
+ </p>
+ <h1>Edit template</h1>
+ <p class="shortdesc">Edit an existing template.</p>
+ <p class="csbody">
+ <p xmlns=""><ol><li>Edit the following
information for the
template:<dl><dlentry><dt>Name</dt><dd>Name of the
template.</dd></dlentry><dlentry><dt>CPU</dt><dd>Number
of processors defined for the
template.</dd></dlentry><dlentry><dt>Memory</dt><dd>Memory
to be allocated to the virtual
machine.</dd></dlentry></dl></li><li>Click
<uicontrol>Save</uicontrol>.</li></ol>The following information is
displayed but cannot be
edited:<dl><dlentry><dt>Vendor</dt><dd>The name of the
company that created the operating system or distribution
+that the template is configured to
use.</dd></dlentry><dlentry><dt>Version</dt><dd>The
version of the operating system or distribution that the template
+is configured to use.</dd></dlentry></dl></p>
+ </p>
+ <h1>Add template</h1>
+ <p class="shortdesc">Add a template from source media.</p>
+ <p class="csbody">
+ <p xmlns="">Select the location from the following
options:<ol><li>Select the location of the source media from the following
options:<dl><dlentry><dt>Local ISO image</dt><dd>Select to
scan storage pools for installation ISO images available
+on the system.</dd></dlentry><dlentry><dt>Remote ISO
image</dt><dd>Select to specify a remote location for an installation ISO
image.</dd></dlentry></dl></li><li>Click
<uicontrol>Create</uicontrol>.</li></ol></p>
+ </p>
+ <h1>Add template - local ISO image</h1>
+ <p class="shortdesc">Add a template from a local ISO
image.</p>
+ <p class="csbody">
+ <p xmlns="">The ISO images available on the system are
displayed.<dl><dlentry><dt>OS</dt><dd>Name of the operating
system or
distribution.</dd></dlentry><dlentry><dt>Version</dt><dd>Version
of the operating system or
distribution.</dd></dlentry><dlentry><dt>Size</dt><dd>Size
of the ISO image.</dd></dlentry></dl></p>
+ <p xmlns="">To create a template from an ISO image, complete
the following
+steps:<ol><li>Choose from the following options:<ul><li>Select an
ISO image from which to create a template.</li><li>Select the
<uicontrol>All</uicontrol> check box to create a template
+from each listed ISO image.</li><li>Select the <uicontrol>I want to
use a specific file</uicontrol> check
+box to specify a path to the ISO image.</li></ul></li><li>Click
<uicontrol>Create</uicontrol>.</li></ol></p>
+ </p>
+ </body>
+</html>
diff --git a/dita/kimhvirtm.dita b/dita/kimhvirtm.dita
new file mode 100644
index 0000000..cc6294c
--- /dev/null
+++ b/dita/kimhvirtm.dita
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?Pub Sty _display FontColor="red"?>
+<?Pub Inc?>
+<cshelp id="kimhvirtm" xml:lang="en-us">
+ <title>Virtual machines</title>
+ <shortdesc>The Virtual machines page lists the defined KVM virtual
+machines.</shortdesc>
+ <csprolog>
+ <csmetadata>
+ <cswindowtitle>Title of window or panel associated with this help;
+for review output only.</cswindowtitle>
+ <cswidgetlabel>Name of field or control associated with this help;
+for review output only</cswidgetlabel>
+ </csmetadata>
+ </csprolog>
+ <csbody>
+ <p>For each virtual machine, the following information is
displayed:<dl><dlentry><dt>Name</dt><dd>Name of the virtual
machine.</dd></dlentry><dlentry><dt>CPU</dt><dd>Percentage
of processor utilization in the virtual
machine.</dd></dlentry><dlentry><dt>Network
I/O</dt><dd>Network input/output transmission rate in KB per
seconds.</dd></dlentry><dlentry><dt>Disk I/O</dt><dd>
Disk input/output transmission rate in KB per
seconds.</dd></dlentry><dlentry><dt>Console</dt><dd>Current
state of guest operating system console.</dd></dlentry></dl></p>
+ <p>The following actions icons are displayed for each virtual
machine:<dl><dlentry><dt>Reload</dt><dd>Click to reload the
displayed data.
</dd></dlentry><dlentry><dt>Power</dt><dd>Click to
power on the virtual machine. If the icon is red, the
+power is off; if the icon is green, the power is
on.</dd></dlentry></dl> </p>
+ <p>The following actions can be selected for each virtual
machine:<ul><li>Select <uicontrol>VNC</uicontrol> to connect to
the remote console
+for the virtual machine.</li><li>Select
<uicontrol>Delete</uicontrol> to delete the virtual
machine.</li></ul>To create a virtual machine, click the <uicontrol>plus
(+)</uicontrol> icon
+in the upper right of the page.</p>
+ </csbody>
+ <cshelp id="kimhvirtmcrt" xml:lang="en-us">
+ <title>Create virtual machine</title>
+ <shortdesc>Create a virtual machine using an existing
template.</shortdesc>
+ <csprolog>
+ <csmetadata>
+ <cswindowtitle>Title of window or panel associated with this help;
+for review output only.</cswindowtitle>
+ <cswidgetlabel>Name of field or control associated with this help;
+for review output only</cswidgetlabel>
+ </csmetadata>
+ </csprolog>
+ <csbody>
+ <p>
+ <ol>
+ <li>Type the name to be used to identify the virtual
machine.</li>
+ <li>Click to select a template.</li>
+ <li>Click
<uicontrol>Create</uicontrol>.</li>
+ </ol>
+ </p>
+ </csbody>
+ </cshelp>
+ <?Pub Caret -1?>
+</cshelp>
+<?Pub *0000002746?>
diff --git a/dita/kimhvirtm.html b/dita/kimhvirtm.html
new file mode 100644
index 0000000..079ec21
--- /dev/null
+++ b/dita/kimhvirtm.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Virtual machines</title>
+ </head>
+ <body>
+ <h1>Virtual machines</h1>
+ <p class="shortdesc">The Virtual machines page lists the defined KVM
virtual
+machines.</p>
+ <p class="csbody">
+ <p xmlns="">For each virtual machine, the following information
is displayed:<dl><dlentry><dt>Name</dt><dd>Name of the
virtual
machine.</dd></dlentry><dlentry><dt>CPU</dt><dd>Percentage
of processor utilization in the virtual
machine.</dd></dlentry><dlentry><dt>Network
I/O</dt><dd>Network input/output transmission rate in KB per
seconds.</dd></dlentry><dlentry><dt>Disk I/O</dt><dd>
Disk input/output transmission rate in KB per
seconds.</dd></dlentry><dlentry><dt>Console</dt><dd>Current
state of guest operating system console.</dd></dlentry></dl></p>
+ <p xmlns="">The following actions icons are displayed for each
virtual machine:<dl><dlentry><dt>Reload</dt><dd>Click to
reload the displayed data.
</dd></dlentry><dlentry><dt>Power</dt><dd>Click to
power on the virtual machine. If the icon is red, the
+power is off; if the icon is green, the power is
on.</dd></dlentry></dl> </p>
+ <p xmlns="">The following actions can be selected for each
virtual machine:<ul><li>Select <uicontrol>VNC</uicontrol> to
connect to the remote console
+for the virtual machine.</li><li>Select
<uicontrol>Delete</uicontrol> to delete the virtual
machine.</li></ul>To create a virtual machine, click the <uicontrol>plus
(+)</uicontrol> icon
+in the upper right of the page.</p>
+ </p>
+ <h1>Create virtual machine</h1>
+ <p class="shortdesc">Create a virtual machine using an existing
template.</p>
+ <p class="csbody">
+ <p xmlns="">
+ <ol>
+ <li>Type the name to be used to identify the virtual
machine.</li>
+ <li>Click to select a template.</li>
+ <li>Click
<uicontrol>Create</uicontrol>.</li>
+ </ol>
+ </p>
+ </p>
+ </body>
+</html>
--
1.8.5.3
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
3936
days inactive
3950
days old
3 comments
2 participants
participants (2)
-
Aline Manera -
Crístian Viana