Skip to content

Commit

Permalink
Regenerate the manual
Browse files Browse the repository at this point in the history
  • Loading branch information
@bbatsov
bbatsov committed Jan 9, 2019
1 parent a4437a8 commit 79319d0
Show file tree
Hide file tree
Showing 5 changed files with 199 additions and 81 deletions.
15 changes: 6 additions & 9 deletions docs/nrepl/about/contributing.html
View file
Expand Up @@ -258,31 +258,28 @@ <h2 id="_funding"><a class="anchor" href="#_funding"></a>Funding</h2>
</div>
<div class="paragraph">
<p>We welcome both individual and corporate sponsors! We also offer a wide array of funding channels to account
for your preferences (although currently <a href="https://opencollective.com/cider">Open Collective</a> is our preferred funding platform).</p>
for your preferences (although currently <a href="https://opencollective.com/nrepl">Open Collective</a> is our preferred funding platform).</p>
</div>
<div class="paragraph">
<p>If you&#8217;re working in a company that&#8217;s making significant use of nREPL we&#8217;d appreciate it if you suggest to your company
to become a nREPL sponsor.</p>
</div>
<div class="paragraph">
<p>You can support the development of nREPL, CIDER, <a href="https://github.com/clojure-emacs/clojure-mode">clojure-mode</a> and <a href="https://github.com/clojure-emacs/inf-clojure">inf-clojure</a> via
<a href="https://opencollective.com/cider">Open Collective</a>,
<a href="https://salt.bountysource.com/teams/cider">Salt</a>,
<a href="https://opencollective.com/nrepl">Open Collective</a>,
<a href="https://www.patreon.com/bbatsov">Patreon</a>,
<a href="https://liberapay.com/bbatsov/donate">Liberapay</a> and PayPal.</p>
</div>
<div class="paragraph">
<p><a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&amp;hosted_button_id=GRQKNBM6P8VRQ"><span class="image"><img src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif" alt="Paypal"></span></a></p>
<a href="https://liberapay.com/bbatsov/donate">Liberapay</a> and
<a href="https://www.paypal.me/bbatsov">PayPal</a>.</p>
</div>
<div class="sect2">
<h3 id="_open_collective"><a class="anchor" href="#_open_collective"></a>Open Collective</h3>
<div class="ulist">
<ul>
<li>
<p>[<a href="https://opencollective.com/cider#backer">Become a backer</a>] (for individuals)</p>
<p>[<a href="https://opencollective.com/nrepl#backer">Become a backer</a>] (for individuals)</p>
</li>
<li>
<p>[<a href="https://opencollective.com/cider#sponsor">Become a sponsor</a>] (for companies)</p>
<p>[<a href="https://opencollective.com/nrepl#sponsor">Become a sponsor</a>] (for companies)</p>
</li>
</ul>
</div>
Expand Down
66 changes: 66 additions & 0 deletions docs/nrepl/design/middleware.html
View file
Expand Up @@ -392,6 +392,19 @@ <h2 id="_sessions"><a class="anchor" href="#_sessions"></a>Sessions</h2>
<div class="sect1">
<h2 id="_pretty_printing"><a class="anchor" href="#_pretty_printing"></a>Pretty Printing</h2>
<div class="sectionbody">
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Pretty-printing support was added in nREPL 0.5 and the API is still
considered experimental.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>nREPL includes a <code>pr-values</code> middleware to print the results of evaluated
forms as strings for returning to the client. By default, this will use either
Expand All @@ -412,6 +425,59 @@ <h2 id="_pretty_printing"><a class="anchor" href="#_pretty_printing"></a>Pretty
:print-options {:print-width 120}}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>A note for client authors - passing strings will work just fine as
well (using the bencode transport you can&#8217;t pass keywords and symbols
as anyways).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-clojure hljs" data-lang="clojure">{"op" "eval"
"code" "(+ 1 1)"
"printer" "my.custom/print-value"
"print-options" {"print-width" 120}}</code></pre>
</div>
</div>
<div class="paragraph">
<p>nREPL will take of converting the keys of the <code>print-options</code> map to
keywords, so they&#8217;d work as expected with their respective printers.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The requirement for the <code>printer</code> function are the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It should take one or two arguments - a value to print, and an optional print options map.</p>
</li>
<li>
<p>It should return the printed value as a string. This means you can&#8217;t use directly
functions like <code>clojure.pprint/pprint</code>, as they output the printed value instead of returning
it as a string.</p>
</li>
<li>
<p>The printer function should have no side-effects.</p>
</li>
<li>
<p>In the absence of print options it should ideally respect Clojure&#8217;s print dynamic vars - e.g. <code><strong>print-length</strong></code>, <code><strong>print-right-margin</strong></code>, etc.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Great examples of functions that honour the API contract are
<code>zprint.core/zprint-str</code> and <code>puget.printer/pprint-str</code>.</p>
</div>
</div>
</div>
</article>
Expand Down
92 changes: 68 additions & 24 deletions docs/nrepl/index.html
View file
Expand Up @@ -182,7 +182,7 @@ <h1>nREPL</h1>
<h2 id="_overview"><a class="anchor" href="#_overview"></a>Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nREPL is a Clojure network REPL that provides a REPL server and
<p>nREPL is a Clojure <strong>n</strong>etwork REPL that provides a REPL server and
client, along with some common APIs of use to IDEs and other tools
that may need to evaluate Clojure code in remote environments.</p>
</div>
Expand All @@ -208,13 +208,77 @@ <h2 id="_why_nrepl"><a class="anchor" href="#_why_nrepl"></a>Why nREPL?</h2>
implement it, with allowances for hosts that lack the concurrency primitives to
support e.g. asynchronous evaluation, interrupts, etc.</p>
</div>
<div class="paragraph">
<p>For more information about the motivation, architecture, use cases, and
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
For more information about the motivation, architecture, use cases, and
discussion related to nREPL, see the original design notes,
available <a href="https://docs.google.com/document/edit?id=1dnb1ONTpK9ttO5W4thxiXkU5Ki89gK62anRqKEK4YZI&amp;authkey=CMuszuMI&amp;hl=en#">here</a>,
and the <a href="https://github.com/clojure/tools.nrepl/wiki/nREPL.Next">notes</a> and
<a href="http://groups.google.com/group/clojure-dev/browse_frm/thread/6e366c1d0eaeec59">discussion</a>
around its recent redesign.<sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnote_1" title="View footnote.">1</a>]</sup></p>
around its recent redesign.<sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnote_1" title="View footnote.">1</a>]</sup>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_beyond_clojure"><a class="anchor" href="#_beyond_clojure"></a>Beyond Clojure</h2>
<div class="sectionbody">
<div class="paragraph">
<p>While this site is mostly about nREPL&#8217;s reference (canonical) Clojure implementation,
it&#8217;s important to point out that the nREPL protocol is language-agnostic and can be
leveraged for many languages that have the ability to evaluate code
at runtime.</p>
</div>
<div class="paragraph">
<p>One way to describe nREPL would be as something similar in
nature to the <a href="https://langserver.org/">Language Server Protocol</a>. nREPL is not nearly as
ambitious as LSP, but on the other hand it&#8217;s also much simpler and it&#8217;s trivial to
create nREPL clients in any language.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You can find some alternative nREPL implementations and more on the subject <a href="beyond_clojure.html" class="page">here</a>.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_community_driven"><a class="anchor" href="#_community_driven"></a>Community-Driven</h2>
<div class="sectionbody">
<div class="paragraph">
<p>One of the defining attributes of nREPL is that it&#8217;s a project built by
the Clojure community for the Clojure community. Making it easy for everyone
interested to participate in the development of nREPL was one of the biggest
reasons why we decided to leave the "Clojure Contrib" umbrella.</p>
</div>
<div class="paragraph">
<p>Everyone&#8217;s welcome to get involved in the project, so we can take it to the next level!</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Check out the how you can help nREPL <a href="about/contributing.html" class="page">here</a>.
</td>
</tr>
</table>
</div>
</div>
</div>
Expand Down Expand Up @@ -248,26 +312,6 @@ <h2 id="_status"><a class="anchor" href="#_status"></a>Status</h2>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_beyond_clojure"><a class="anchor" href="#_beyond_clojure"></a>Beyond Clojure</h2>
<div class="sectionbody">
<div class="paragraph">
<p>While this site is mostly about nREPL&#8217;s reference (canonical) Clojure implementation,
it&#8217;s important to point out that the nREPL protocol is language-agnostic and can be
leveraged for many languages that have the ability to evaluate code
at runtime.</p>
</div>
<div class="paragraph">
<p>One way to describe nREPL would be as something similar in
nature to the <a href="https://langserver.org/">Language Server Protocol</a>. nREPL is not nearly as
ambitious as LSP, but on the other hand it&#8217;s also much simpler and it&#8217;s trivial to
create nREPL clients in any language.</p>
</div>
<div class="paragraph">
<p>You can find some alternative nREPL implementations and more on subject <a href="beyond_clojure.html" class="page">here</a>.</p>
</div>
</div>
</div>
<div id="footnotes">
<hr>
<div class="footnote" id="_footnote_1">
Expand Down
17 changes: 14 additions & 3 deletions docs/nrepl/third_party_middleware.html
View file
Expand Up @@ -203,11 +203,22 @@ <h2 id="_clojure_editor_support"><a class="anchor" href="#_clojure_editor_suppor
<p><a href="https://github.com/clojure-emacs/refactor-nrepl">refactor-nrepl</a>: A collection of functionality designed to support editor refactoring features.</p>
</li>
<li>
<p><a href="http://bpiel.github.io/sayid/">sayid</a>: A powerful tracing/debugging tool. It is a great alternative of CIDER-nREPL&#8217;s
basic tracing functionality.</p>
<p><a href="https://github.com/liquidz/iced-nrepl">iced-nrepl</a>: nREPL middleware to support vim-iced.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_debugging"><a class="anchor" href="#_debugging"></a>Debugging</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><a href="http://bpiel.github.io/sayid/">sayid</a>: A powerful tracing/debugging tool. It is a great alternative of CIDER-nREPL&#8217;s basic tracing functionality.</p>
</li>
<li>
<p><a href="https://github.com/liquidz/iced-nrepl">iced-nrepl</a>: nREPL middleware to support vim-iced.</p>
<p><a href="https://github.com/vvvvalvalval/scope-capture-nrepl">scope-capture-nrepl</a>: A companion library to scope-capture, providing an nREPL middleware that lets you put your REPL in the context of an Execution Point.</p>
</li>
</ul>
</div>
Expand Down

0 comments on commit 79319d0

Please sign in to comment.