<?xml version="1.0"?> 

<!--
	description:

		"Using gedoc"

	tool: "Gobo Eiffel Doc"
	copyright: "Copyright (c) 2017-2025, Eric Bezault and others"
	license: "MIT License"
-->

<chapter xmlns="https://www.gobosoft.com/eiffel/gobo/documentation" id="gedoc/usage">
<chapterinfo>
	<copyright>
		<year>2017-2023</year>
		<holder>Eric Bezault</holder>
	</copyright>
	<author>
		<firstname>Eric</firstname><surname>Bezault</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>22 September 2025</date>
</chapterinfo>

<title>Using gedoc</title>

<section><title>Command-line options</title>
<para>
The usual way to invoke <projectname>gedoc</projectname> is as follows:
<blockquote>
	<filename>gedoc --format=&lt;output_format&gt; --output=&lt;output_directory&gt; &lt;input_filename&gt;</filename>
</blockquote>
This will read the description of your Eiffel project from the 
ECF file <filename>input_filename</filename>, analyze it, and generate
the documentation files in directory <filename>output_directory</filename>
using the format <filename>output_format</filename>. Note that in addition
to ECF, the file <filename>input_filename</filename> can also
be an Eiffel class file. In that case, your Eiffel project will be considered
to be made up of only one Eiffel class. This is useful when we just want to
pretty-print one Eiffel file.
</para><para>
Here is the list of options that can be used with <projectname>gedoc</projectname>:
<variablelist>
	<varlistentry>
		<term>
			<filename>-h</filename>
		</term>
		<term>
			<filename>--help</filename>
		</term>
		<listitem><para>
			Print a summary of the command-line options of <projectname>gedoc</projectname> and exit.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--target=&lt;target_name&gt;</filename>
		</term>
		<listitem><para>
			Name of target to be used in ECF file.
			(default: last target in ECF file)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--format=&lt;pretty_print|html_ise_stylesheet|descendants|implicit_converts|explicit_converts|ecf_pretty_print|available_targets|executable_name&gt;</filename>
		</term>
		<listitem><para>
			Format for the output. (default: <filename>pretty_print</filename>) The formats currently supported are
			<filename>pretty_print</filename> to use <projectname>gedoc</projectname> as an 
			<link linkend="pretty_printer">Eiffel pretty-printer</link>, 
			<filename>html_ise_stylesheet</filename> to generate
			<link linkend="html_ise_stylesheet">HTML documentation using
			ISE's stylesheet</link>, 
			<filename>descendants</filename> to get the <link linkend="descendants">descendants</link>
			of a class or of a set of classes,
			<filename>implicit_converts</filename> and <filename>explicit_converts</filename>
			to list <link linkend="implicit_conversions">implicit conversions</link> in the code and make them explicit,
			<filename>ecf_pretty_print</filename> to use <projectname>gedoc</projectname> as an
			<link linkend="ecf_pretty_printer">ECF pretty-printer</link> to format or
			convert ECF files,
			<filename>available_targets</filename> to figure out the list of
			<link linkend="available_targets">available targets</link> in an ECF file, and
			<filename>executable_name</filename> to get the <link linkend="executable_name">name
			of the executable</link> to be compiled using a given ECF file.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>-c &lt;class_name&gt;</filename>
		</term>
		<term>
			<filename>--class=&lt;class_name&gt;</filename>
		</term>
		<listitem><para>
			Name of classes to be processed. (default: process all classes
			in the Eiffel project) The name can contain wildcards such as
			<filename>FOO*</filename> or <filename>@(FOO|BAR)</filename>.
			This option can be used several times to specify several class
			names.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>-o &lt;directory_name&gt;</filename>
		</term>
		<term>
			<filename>--output=&lt;directory_name&gt;</filename>
		</term>
		<listitem><para>
			Directory for generated files. (default: next to each class file)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--library-prefix</filename>
		</term>
		<listitem><para>
			Add subfolders with library names in the output directory.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>-f</filename>
		</term>
		<term>
			<filename>--force</filename>
		</term>
		<listitem><para>
			Overwrite existing files without asking.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>-i</filename>
		</term>
		<term>
			<filename>--interactive</filename>
		</term>
		<listitem><para>
			Ask before overwriting a file, unless <filename>--force</filename> is specified.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--ise[=major[.minor[.revision[.build]]]]</filename>
		</term>
		<listitem><para>
			Version of Eiffel whose semantics should be used during code analysis. (default: latest version)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--ecf=&lt;latest|major.minor.revision&gt;</filename>
		</term>
		<listitem><para>
			Version of ECF to be used when converting ECF files. (default: version of the ECF input file)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--setting=name=value</filename>
		</term>
		<listitem><para>
			Override settings defined in ECF file. This option can be used several
			times to override several settings.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--capability=name=value</filename>
		</term>
		<listitem><para>
			Override capability usage defined in ECF file. This option can be used several
			times to override several capabilities.
		</para></listitem>
	</varlistentry>	
	<varlistentry>
		<term>
			<filename>--variable=NAME=VALUE</filename>
		</term>
		<listitem><para>
			Override variables defined in ECF file. This option can be used several
			times to override several variables.
		</para></listitem>
	</varlistentry>	
	<varlistentry>
		<term>
			<filename>--thread=&lt;thread_count&gt;</filename>
		</term>
		<listitem><para>
			Number of threads to be used to run <projectname>gedoc</projectname>.
			Negative numbers -N mean &quot;number of CPUs - N&quot;.
			(default: -3, aka &quot;max (number of CPUs -3, 1)&quot;)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--silent</filename>
		</term>
		<listitem><para>
			Run <projectname>gedoc</projectname> in silent mode.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--verbose</filename>
		</term>
		<listitem><para>
			Run <projectname>gedoc</projectname> in verbose mode.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--no-benchmark</filename>
		</term>
		<listitem><para>
			Should no benchmark information be displayed?
			(default: display non-nested benchmark information)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--nested-benchmark</filename>
		</term>
		<listitem><para>
			Should nested benchmark information be displayed?
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--metrics</filename>
		</term>
		<listitem><para>
			Should metrics information be displayed?
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>-V</filename>
		</term>
		<term>
			<filename>--version</filename>
		</term>
		<listitem><para>
			Print the version number of <projectname>gedoc</projectname> and exit.
		</para></listitem>
	</varlistentry>
</variablelist>
</para>
</section>

</chapter>
