Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for ocp-indent #1

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update docs for ocp-indent #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ <h3>Toolchains</h3>
<h3>Tools</h3>
<table class="table table-striped">
<tr><td width="20%"><a href="ocp-build.html">ocp-build</a></td><td width="70%">A build manager for OCaml applications</td><td>1.99.9-beta</tr>
<tr><td><a href="ocp-indent.html">ocp-indent</a></td><td>A customizable tool to indent OCaml code</td><td>1.5.2</td></tr>
<tr><td><a href="ocp-indent.html">ocp-indent</a></td><td>A customizable tool to indent OCaml code</td><td>1.8.1</td></tr>
<tr><td><a href="ocp-index.html">ocp-index</a></td><td>A tool to search environment for auto-completion</td><td>1.1.4</td></tr>
<tr><td><a href="ocaml-top.html">ocaml-top</a></td><td>The interactive
editor for education</td><td>1.1.2</td></tr>
Expand Down
148 changes: 67 additions & 81 deletions docs/ocp-indent.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,87 +45,80 @@
</div>
<div class="content">
<div class="container">
<h1>ocp-indent</h1>
<p>ocp-indent is a customizable tool to indent OCaml code. </p>
<hr />
<div class="span12">
<h3>Ressources</h3>
<table class="table table-striped">
<tr><td><a href="http://www.github.com/OCamlPro/ocp-indent">ocp-indent on Github</a></td><td>Latest sources in the official GIT repository</td></tr>
</table>
</div>
<br />
<h2>
<a name="installation" class="anchor" href="#installation"><span class="octicon octicon-link"></span></a>Installation</h2>
<h3>
<a name="using-opam" class="anchor" href="#using-opam"><span class="octicon octicon-link"></span></a>Using OPAM</h3>
<h1 id="ocp-indent">ocp-indent</h1>
<p>A simple tool to indent OCaml programs</p>
<p>Authors: Louis Gesbert (OCamlPro), Thomas Gazagnaire (OCamlPro), Jun Furuse</p>
<p>License: LGPL 2.1 with linking exception</p>
<h2 id="installation">Installation</h2>
<h3 id="using-opam">Using OPAM</h3>
<p>The simplest way to install <code>ocp-indent</code> is using <a href="http://opam.ocamlpro.com">OPAM</a>:</p>
<div class="highlight"><pre>opam install ocp-indent
</pre></div>
<h3>
<a name="from-sources" class="anchor" href="#from-sources"><span class="octicon octicon-link"></span></a>From sources</h3>
<p>You can also install <code>ocp-indent</code> from sources. You'll need <code>ocaml (&gt;= 3.12.1)</code>
and <code>ocp-build (&gt;= 1.99.3-beta)</code>:</p>
<div class="highlight"><pre>./configure
<pre><code class="language-bash">opam install ocp-indent
</code></pre>
<h3 id="by-hand">By hand</h3>
<p>You can also compile and install <code>ocp-indent</code> from sources. You'll need <code>ocaml (&gt;= 3.12.1)</code> and <code>ocp-build (&gt;= 1.99.6-beta)</code>:</p>
<pre><code class="language-bash">./configure
make
make install
</pre></div>
</code></pre>
<p>If you use opam and want it installed alongside ocaml, you may want to use
<code>./configure --prefix $(opam config var prefix)</code>.</p>
<h2>
<a name="usage" class="anchor" href="#usage"><span class="octicon octicon-link"></span></a>Usage</h2>
<p>The above installation step copies elisp and vim scripts to
<code>&lt;prefix&gt;/share/typerex/ocp-indent/</code>. You then need to load them in
the editor of your choice to automatically use ocp-indent.</p>
<h3>
<a name="emacs" class="anchor" href="#emacs"><span class="octicon octicon-link"></span></a>Emacs</h3>
<p>Run the following command to setup tuareg-mode to use <code>ocp-indent</code>: </p>
<div class="highlight"><pre><span class="nb">echo</span> <span class="s1">'(load-file "'</span><span class="s2">"$(opam config var prefix)"</span><span class="s1">'/share/typerex/ocp-indent/ocp-indent.el")'</span> &gt;&gt;~/.emacs
</pre></div>
<h3>
<a name="vim" class="anchor" href="#vim"><span class="octicon octicon-link"></span></a>Vim</h3>
<p>Use the following command to tell Vim to use <code>ocp-indent</code>:</p>
<div class="highlight"><pre><span class="nb">echo</span> <span class="s1">'autocmd FileType ocaml source '</span><span class="s2">"$(opam config var prefix)"</span><span class="s1">'/share/typerex/ocp-indent/ocp-indent.vim'</span> &gt;&gt;~/.vimrc
</pre></div>
<h3>
<a name="other-editors" class="anchor" href="#other-editors"><span class="octicon octicon-link"></span></a>Other editors</h3>
<h2 id="usage">Usage</h2>
<p>The above installation step copies elisp scripts to
<code>&lt;prefix&gt;/share/emacs/site-lisp/</code> and vim scripts to
<code>&lt;prefix&gt;/share/ocp-indent/vim/</code>. You then need to load them in the editor of
your choice to automatically use ocp-indent.</p>
<p>Installing OPAM package
<a href="https://opam.ocaml.org/packages/user-setup/user-setup.0.3/"><code>user-setup</code></a> will
trigger automatic configuration for popular editors (emacs and vim currently,
but more are in the works). If you prefer to handle your configuration manually,
read on.</p>
<h3 id="emacs">Emacs</h3>
<p>Run the following command to setup tuareg-mode or caml-mode to use <code>ocp-indent</code>
for indentation:</p>
<pre><code class="language-bash">echo '(load-file &quot;'&quot;$(opam config var share)&quot;'/emacs/site-lisp/ocp-indent.el&quot;)' &gt;&gt;~/.emacs
</code></pre>
<p>The <code>tab</code> key should now reindent the current line using ocp-indent.</p>
<h3 id="vim">Vim</h3>
<p>Use the following command to tell Vim to use <code>ocp-indent</code> to indent OCaml code:</p>
<pre><code class="language-bash">echo 'set rtp^=&quot;'&quot;$(opam config var ocp-indent:share)&quot;'/vim&quot;' &gt;&gt;~/.vimrc
</code></pre>
<p>Automatic indentation as you type should take place, depending on your
configuration. Use <code>==</code> to reindent the current line, and <code>=G</code> to reindent until
the end of buffer.</p>
<h3 id="other-editors">Other editors</h3>
<p>As <code>ocp-indent</code> is a command-line tool, you can easily integrate it with other editors.</p>
<div class="highlight"><pre>ocp-indent &lt;src-file&gt; &gt; &lt;dst-file&gt;
</pre></div>
<pre><code class="language-bash">ocp-indent &lt;src-file&gt; &gt; &lt;dst-file&gt;
</code></pre>
<p>You can also tell it to indent only a subsets of lines, and to output only the indentation level:</p>
<div class="highlight"><pre>ocp-indent &lt;src-file&gt; --lines &lt;l1&gt;-&lt;l2&gt; --numeric
</pre></div>
<h2>
<a name="configuration-options" class="anchor" href="#configuration-options"><span class="octicon octicon-link"></span></a>Configuration options</h2>
<pre><code class="language-bash">ocp-indent &lt;src-file&gt; --lines &lt;l1&gt;-&lt;l2&gt; --numeric
</code></pre>
<h2 id="configuration-options">Configuration options</h2>
<p>By default, <code>ocp-indent</code> comes with sensible default parameters. However,
you can customize some of the indentation options using command-line
arguments. For more details, see:</p>
<div class="highlight"><pre>ocp-indent --config <span class="nb">help</span>
</pre></div>
<h3>
<a name="configuration-file" class="anchor" href="#configuration-file"><span class="octicon octicon-link"></span></a>Configuration file</h3>
<pre><code class="language-bash">ocp-indent --help
</code></pre>
<h3 id="configuration-file">Configuration file</h3>
<p>The same parameters can be defined in a configuration file, allowing for user
defaults and per-project parameters. The latter is particularly convenient to
transparently ensure consistency in projects with many contributors, without
requiring them to change their settings in any way (except that, obviously, they
need to use ocp-indent !).</p>
<p>If a <code>.ocp-indent</code> file is found in the current directory or its ancestors, it
overrides definitions from <code>~/.ocp/ocp-indent.conf</code> and the built-in default.
The command-line can of course still be used to override parameters defined in
the files.</p>
<p>Have a look at ocp-indent's own <a href="/OCamlPro/ocp-indent/blob/master/.ocp-indent"><code>.ocp-indent</code></a> file for an
overrides definitions from <code>$XDG_CONFIG_HOME/ocp/ocp-indent.conf</code>,
<code>~/.ocp/ocp-indent.conf</code> and the built-in default. The command-line can of
course still be used to override parameters defined in the files.</p>
<p>Have a look at ocp-indent's own <a href=".ocp-indent"><code>.ocp-indent</code></a> file for an
example.</p>
<h3>
<a name="in-file-configuration" class="anchor" href="#in-file-configuration"><span class="octicon octicon-link"></span></a>In-file configuration</h3>
<h3 id="in-file-configuration">In-file configuration</h3>
<p>There is no built-in support for in-file configuration directives. Yet, some
editors already provide that features, and with emacs, starting your file with a
line like:</p>
<pre><code>(* -*- ocp-indent-config: in=2 -*- *)
</code></pre>
<p>will enable you to have the indentation after <code>in</code> setup to 2 locally on this
file.</p>
<h2>
<a name="how-does-it-compare-to-tuareg-" class="anchor" href="#how-does-it-compare-to-tuareg-"><span class="octicon octicon-link"></span></a>How does it compare to tuareg ?</h2>
<h2 id="how-does-it-compare-to-tuareg">How does it compare to tuareg ?</h2>
<p>We've run some benchmarks on real code-bases and the result is quite
conclusive. Keep in mind than most of existing source files are
either indented manually or following tuareg standards. You can
Expand All @@ -136,38 +129,31 @@ <h2>
<a href="https://github.com/OCamlPro/ocp-indent/tree/master/tests/passing">here</a>. The
currently failing tests can be seen
<a href="http://htmlpreview.github.com/?https://github.com/OCamlPro/ocp-indent/blob/master/tests/failing.html">here</a>.</p>
<h2>
<a name="testing" class="anchor" href="#testing"><span class="octicon octicon-link"></span></a>Testing</h2>
<h2 id="testing">Testing</h2>
<p>It's hard to deliver a great indenter without tests. We've built
<code>ocp-indent</code> based on a growing collection of unit-tests. If you find an
indentation bug, feel free to send us a code snippet that we will
incorporate into our test suite.</p>
<p>The tests are organized as follows:</p>
<ul>
<li>
<code>tests/passing</code> contains tests that are properly indented and should be left
unchanged by ocp-indent.</li>
<li>
<code>tests/failing</code> contains tests for which ocp-indent currently returns the
<li><code>tests/passing</code> contains tests that are properly indented and should be left
unchanged by ocp-indent.
</li>
<li><code>tests/failing</code> contains tests for which ocp-indent currently returns the
results in <code>tests/failing-output</code>, hence <code>meld tests/failing{,-output}</code> should
give an overview of currently known bugs (also available online
<a href="http://htmlpreview.github.com/?https://github.com/OCamlPro/ocp-indent/blob/master/tests/failing.html">here</a>).</li>
<li>
<code>tests/test.sh</code> checks the current state against the reference state (checked
into git).</li>
<li>
<code>tests/test.sh --[git-]update</code> updates the current reference state.</li>
<li>See <code>tests/test.sh --help</code> for more</li>
</ul><p>Please make sure tu run <code>make &amp;&amp; tests/test.sh --git-update</code> before any commit,
so that the repo always reflects the state of the program.</p></article>
<br />
<div class="right">
<p><a class="btn btn-large btn-primary" href="http://www.ocamlpro.com/">
OCamlPro &rsaquo;&rsaquo;</a></p>
</div>
</div>
</div>
</div>
<a href="http://htmlpreview.github.com/?https://github.com/OCamlPro/ocp-indent/blob/master/tests/failing.html">here</a>).
</li>
<li><code>tests/test.sh</code> checks the current state against the reference state (checked
into git).
</li>
<li><code>tests/test.sh --[git-]update</code> updates the current reference state.
</li>
<li>See <code>tests/test.sh --help</code> for more
</li>
</ul>
<p>Please make sure tu run <code>make &amp;&amp; tests/test.sh --git-update</code> before any commit,
so that the repo always reflects the state of the program.</p>
</div>
</div>
<div class="footer">
Expand Down
Loading