<?xml version="1.0"?> 

<!--
	description:

		"HTML Format with ISE's stylesheet"

	tool: "Gobo Eiffel Doc"
	copyright: "Copyright (c) 2017, Eric Bezault and others"
	license: "MIT License"
	date: "$Date$"
	revision: "$Revision$"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="gedoc/html_ise_stylesheet">
<chapterinfo>
	<copyright>
		<year>2017</year>
		<holder>Eric Bezault</holder>
	</copyright>
	<author>
		<firstname>Eric</firstname><surname>Bezault</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>25 March 2017</date>
</chapterinfo>

<title>HTML Format with ISE's Stylesheet</title>

<para>
With <projectname>gedoc</projectname>, it is possible to generate HTML documentation out of 
an Eiffel project, using the same stylesheet used by the HTML documentation generated by
ISE EiffelStudio. See <ulink url="https://www.eiffel.org/doc/eiffelstudio/Producing%20and%20Exporting%20Documentation">
Producing and Exporting Documentation</ulink> for more details about the documentation
format <filename>html-stylesheet</filename> from ISE EiffelStudio.
</para>

<section><title>Generating Documentation for an Eiffel Project</title>
<para>
In order to generate HTML documentation which is very similar to the
one produced by the following command-line (with 
<ulink url="https://www.eiffel.org/doc/eiffelstudio/EiffelStudio%3A%20Using%20command%20line%20options#Commands_for_generating_documentation">
ISE toolbox</ulink>):
<blockquote>
	<filename>ec -filter html-stylesheet -all -config project.ecf</filename>
</blockquote>
you should use the following command-line:
<blockquote>
	<filename>gedoc --format=html_ise_stylesheet --library-prefix --output=some_output_directory project.ecf</filename>
</blockquote>
where <filename>project.ecf</filename> is the ECF file describing the Eiffel project,
and <filename>some_output_directory</filename> is the directory where the HTML files
will be generated. Note that an Xace file can also be used in place of the ECF file.
The command-line option <filename>--library-prefix</filename> tells <projectname>gedoc</projectname>
that HTML class files should be generated in a subfolder of the output directory 
whose name is the name of the Eiffel library containing these Eiffel classes
(one subfolder per library). The command-line option <filename>--force</filename> 
can be used when you run this command several times to update the documentation
after some modifications in the Eiffel class. It will tell <projectname>gedoc</projectname>
to overwrite the files which already exist. Without this option,
files will not be overwritten and <projectname>gedoc</projectname> will emit an error
message. Alternatively, the command-line option <filename>--interactive</filename> can
be used. It will ask confirmation to the user before overwriting files. Finally, if you want
to generate HTML documentation only for a subset of the classes in your Eiffel project,
you can use the command-line option <filename>--class</filename> with some wildcards.
</para>
</section>

<section><title>Generated Files</title>
<para>
For each Eiffel class <classname>FOO</classname>, <projectname>gedoc</projectname>
generates three HTML file: <filename>foo.html</filename>, <filename>foo_chart.html</filename>
and <filename>foo_links.html</filename>. The file <filename>foo.html</filename>
contains a pretty-printed, colorized and hyper-linked version of the class text.
The file <filename>foo_chart.html</filename> contains general information about the
class, the list of its parent classes, and the list of exported features (both
declared in the class text and inherited from ancestors). Note that in order to
comply with the original <filename>html-sytlesheet</filename> format from ISE
EiffelStudio, features declared in class <classname>ANY</classname> are not listed
here, unless redefined in a descendant. And finally the file <filename>foo_links.html</filename>
lists the parent classes of the class, its heirs (other classes having this
class as parent), its direct client classes and supplier classes.
</para>
<para>
Each HTML file has a natigation bar at the top and bottom of the page. The button
<filename>Classes</filename> lists all classes in the Eiffel project, with the
"description" text of their "note" clause (formerly known as "indexing" clause).
The button <filename>Groups</filename> lists all Eiffel libraries used in the
project, and the button <filename>Group hierarchy</filename> also lists their
clusters. Clicking on the name of an Eiffel library will then display the list
of classes in this library. The button <filename>Chart</filename> shows the
file <filename>foo_chart.html</filename> (already mentioned above) for the class 
<classname>FOO</classname> currently displayed. The button <filename>Relations</filename>
shows the file <filename>foo_links.html</filename>. The button <filename>Text</filename>
shows the file <filename>foo.html</filename>. Finally, in the text field 
<filename>Go to:</filename> you can type the name of a class, then type "Enter"
to jump to that class.
</para>
</section>

<section><title>Why yet another HTML Documentation Generator?</title>
<para>
At work, as part of our DevOps effort, we have a Continuous Integration cycle
and Continuous Delivery cycle which have to process 20,000 classes. During
these phases, we generate HTML documentation out of these Eiffel classes.
Here is the performance that we get when using ISE original 
<filename>html-stylesheet</filename> format:
<programlisting>
	<filename>ecb.exe -config integration.ecf -filter html-stylesheet -all</filename>
		44 minutes
		RAM: 3.9 GB
		EIFGEN: 3.0 GB
</programlisting>
This is way too slow within a Continuous Integration cycle and Continuous 
Delivery cycle. Knowing that <projectname>gelint</projectname> is super fast
to analyze huge Eiffel systems (here, more than 20,000 classes), we tried to
use the same code as <projectname>gelint</projectname> as a front-end of
<projectname>gedoc</projectname> to generate similar HTML files. The results
were up to our expectations:
<programlisting>
	<filename>gedoc.exe --format=html_ise_stylesheet --force --library-prefix --output=some_output_directory integration.ecf</filename>
		2 minutes 54 seconds
		RAM: 3.0 GB
		No disk usage
</programlisting>
This is when <projectname>gedoc</projectname> has been compiled with the Gobo 
Eiffel Compiler (aka <projectname>gec</projectname>) with no garbage collection.
Here is what we get when <projectname>gedoc</projectname> is compiled with 
<projectname>gec</projectname> using the Boehm GC:
<programlisting>
	<filename>gedoc.exe --format=html_ise_stylesheet --force --library-prefix --output=some_output_directory integration.ecf</filename>
		3 minutes 5 seconds
		RAM: 2.7 GB
		No disk usage
</programlisting>
This is still acceptable as part of a Continuous Integration cycle and 
Continuous Delivery cycle.
</para>
</section>
</chapter>
