@c Generated by the sb-manual contrib. Do not edit.

@node sb manual
@section sb-manual

@menu
* Using PAX: using pax.
* Browsing Live with PAX: browsing live with pax.
* Fancy Documentation with PAX: fancy documentation with pax.
@end menu

The @code{sb-manual} module has the SBCL user manual in forms
mimicking @code{pax:defsection}:

@example
(defsection @@example (:title "Example")
  "This is an example, but see the real @@SB-MANUAL."
  (print function)
  (@@subexample section))
@end example

The names of the variables holding the documentation are exported
from the @code{sb-manual} package. Since sections are basically
variables, in Slime, @code{M-.} on @code{"@@SB-MANUAL"}, @code{"print"}, or
on @code{"@@subexample"} will take you to the respective definition.
This makes it easy to navigate the documentation. Normal Lisp
definition docstrings and section docstrings reference sections
following the usual convention of uppercasing the name. Docstrings
are in a subset of Markdown and use very little markup in general,
so they are easy to read directly in the source.

The official manual in Info, HTML and PDF formats is generated via
Texinfo generated from these definitions.

@node using pax
@subsection Using PAX

However, @code{sb-manual::defsection} is but a dummy implementation of
@code{pax:defsection} to avoid a hard dependency on PAX.

See the @code{mgl-pax} @code{asdf:system} or @url{https://github.com/melisgl/mgl-pax/}.

When PAX is loaded, the dummy @code{defsection} definitions are made
real, so that PAX can work with them.

@anchor{Function sb-manual use-pax}
@ffindex @sortas{use-pax sb-manual} use-pax [sb-manual]
@deffn{Function} sb-manual:use-pax
Ensure that exported variables are @code{pax:section}s.
It is an error if the @code{mgl-pax} library is not loaded.

Calling this function explicitly is rarely necessary because it is
called automatically:

@itemize
@item when @code{sb-manual} is loaded, if @code{pax} is present;

@item when @code{pax:document} (more precisely, @code{dref:locate}) is called on
  an @code{sb-manual} section.
@end itemize

The latter feature requires v0.4.12 of @code{pax}. See the @code{mgl-pax}
asdf:system.
@end deffn
@node browsing live with pax
@subsection Browsing Live with PAX

With PAX, you can browse the manual live. The documentation of this
feature is available at
@uref{https://melisgl.github.io/mgl-pax-world/pax-manual.html#MGL-PAX:@@BROWSING-LIVE-DOCUMENTATION%20MGL-PAX:SECTION, online}.

If you are browsing this manual live right now, here is the
equivalent live link: @code{pax::@@browsing-live-documentation}.

Notable features:

@itemize
@item Autolinks within the manual: if @code{sb-ext:exit} is mentioned, then
  it's linked to its documentation. You basically get links to where
  @code{M-.} would go in the sources.

@item Autolinks to the CLHS.

@item View the documentation of any Lisp definition or section without
  generating the entire manual.

@item Locatives (e.g. the @code{"[function]"} in @code{"- [function]
  SB-EXT:EXIT"}) are also links in live browsing: they tell Slime
  to visit the definition.

For this to work, you need to allow Slime to evaluate Elisp sent
from SBCL:

@example
(setq slime-enable-evaluate-in-emacs t)
@end example

and maybe your window manager focus stealing configuration needs
tweaking as well.
@end itemize

Live browsing can greatly reduce the latency of Edit-Compile-View
Loop, when working on documentation.

@node fancy documentation with pax
@subsection Fancy Documentation with PAX

PAX can generate dead documentation, too. In the SBCL sources,
@code{contrib/sb-manual/make-pax-docs.sh} generates the manual in plain
text, Markdown, PDF, and HTML formats. These differ from those
generated via Texinfo in that they are autolinked (like when
@ref{browsing live with pax}).

Also, you can generate documentation yourself with e.g.

@example
(pax:document sb-manual:@@sbcl-manual :format :markdown)
@end example

