\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sb-texinfo.info
@settitle SB-TEXINFO
@c %**end of header

@c for install-info
@dircategory Software development
@direntry
* sb-texinfo:           Documentation String to Texinfo Converter
@end direntry

@finalout

@macro project
@sc{sb-texinfo }
@end macro

@titlepage
@title @project
@subtitle Documentation String to Texinfo Converter
@end titlepage

@contents 

@include include/sb-texinfo.texinfo

@node Top, Overview, (dir), (dir)
@top Introduction

@project converts Common Lisp documentation strings for inclusion in
a Texinfo manual---which can then be converted into eg. HTML and PDF.

While current implementation is SBCL-only, there is no fundamental
reason why support for other Common Lisps could not be added.

@project was originally written for processing the SBCL docstrings
by Rudi Sclatte in 2004, and has been maintained as part of SBCL since
then. This version was split from the SBCL sources in 2011 in order to
generalize it for documenting other software. Like SBCL, this manual
is in the Public Domain.

@c Version control
@project is maintained in Git:
@example
git clone git://github.com/nikodemus/sb-texinfo.git
@end example
will get you a local copy.
@example
@url{http://github.com/nikodemus/sb-texinfo/}
@end example
is the GitHub project page, where the issue tracker is located.

@menu
* Overview::
* Docstrings::
* Examples::
* Dictionary::
* Function Index::
@end menu

@node Overview, Docstrings, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Overview

There are two main ways of using @project

@itemize

@item @strong{The Right Way:}
The recommended way is to write a manual in Texinfo, and use the
@code{@@include} directive to include processed docstrings generated using
@reffun{generate-includes}.

@item @strong{Quick and Dirty:}
Call @reffun{document-package} with the name of the package or
packages to document. This will produce a Texinfo file containing
extracted documentation for the project.

This can be a convenient way to produce a template for further
development using the first method, and perhaps more importantly
quickly allows you to generate reference documentation for packages
with docstrings but no manual.

@end itemize

@node Docstrings, Examples, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter Docstrings

The documentation is generated out of the docstrings of exported symbols.
The docstrings are used mostly as is, except for the following conversions

@itemize
@item Special Characters, such as @code{@@}, @code{@{} and @code{@}} are escaped so
      they are not mangled by texinfo.
@item @code{ALL-CAPS} words that name a symbol are included as a @code{@@code@{all-caps@}}
      so they are formatted nicely.
@item It tries to recognize unnumbered lists and output an @code{@@itemize} block containing
      the itemized entries.
@item It tries to recognize lisp code blocks and puts them in @code{@@lisp} blocks.
@end itemize

@menu
* Itemized Lists::
* Lisp Code::
@end menu

@node Itemized Lists, Lisp Code, Docstrings, Docstrings
@comment  node-name,  next,  previous,  up
@section Itemized Lists

A section in the docstring is an item when it starts with either
@code{-} or @code{*} followed by a space.  All subsequent lines which
are indented more than the @code{-} or @code{*} are considered part of the item.
Empty lines are include in an item.

When a line is encountered that is indented less than or the same as the previous
@code{-} or @code{*},
which does not mark a new item, all items collected are put in an @code{@@itemize} section.

Each item itself is scanned for subitems.  An item is recognized as a subitem
if the indentation level is higher than the current item.

It is not possible to include Lisp Code examples in an item.

In the exaple below, all @code{-} are recognized as toplevel items and the
@code{*} are recognized as sub items.  Note that ony the identation matters,
so both could have been marked by the same character.

@lisp
Below we itemize 2 top level items
- The first case is about subitems

  Sub items are recognized by a higher indentation like this:
  * Sub 1
  * Sub 2
  This line is still part of the first toplevel item

- Second toplevel item

This is not part anymore of the itemized list.
@end lisp


@node Lisp Code,  , Itemized Lists, Docstrings
@comment  node-name,  next,  previous,  up
@section Lisp Code

A section in the docstring is recognized as a lisp section if
@itemize
@item It starts and end with an empty line.
@item The first non space character after the opening empty line
      is one of @code{(}, @code{;} or @code{<}.
@item The section is ended with the first empty line it encounters unless
      the next lines first non whitespace character is again one of
      @code{(}, @code{;} or @code{<}.
@end itemize

The exception in the last clause is there so an empty line in the middle
of lisp code is recognized.

So it will recognize the definition of @code{fib} in the following example:

@lisp
So for example

(defun fib (n)
   "A buggy implementation of the Fibonacci function"
   (cond
   ;; Easy cases
      ((= 0 n) 0)
      ((= 1 n) 1)

   ;; Generic case
      (t (+ (fib (- n 1)) (fib (- n 2))))))

And this is normal text again.
@end lisp


@node Examples, Dictionary, Docstrings, Top
@comment  node-name,  next,  previous,  up
@chapter Examples

@section Using @code{generate-includes}

This manual is produced using the @reffun{generate-includes} method.
@file{sb-texinfo.texinfo} is the main Texinfo source file, where
docstrings are included.

@example
@url{https://raw.github.com/nikodemus/sb-texinfo/master/doc/sb-texinfo.texinfo}
@end example

A @file{Makefile} is responsible for running SBCL and the Texinfo toolchain.

@example
@url{https://raw.github.com/nikodemus/sb-texinfo/master/doc/Makefile}
@end example

Finally, @file{style.css} is used to prettify the HTML version.

@example
@url{https://raw.github.com/nikodemus/sb-texinfo/master/doc/style.css}
@end example

This produces the following HTML and PDF files:

@example
@url{http://nikodemus.github.com/sb-texinfo/sb-texinfo.html}
@url{http://nikodemus.github.com/sb-texinfo/sb-texinfo.pdf}
@end example

and a GNU info file as well.

@section Using @code{document-package}

An alternate version of this manual, produced using

@lisp
(sb-texinfo:document-package
 :sb-texinfo
 :output-file "document-package-sample.texinfo")
@end lisp

and further processed using the @file{Makefile} linked above:
@example
@url{http://nikodemus.github.com/sb-texinfo/document-package-sample.html}
@url{http://nikodemus.github.com/sb-texinfo/document-package-sample.pdf}
@end example

@node Dictionary,Function Index , Examples, Top
@comment  node-name,  next,  previous,  up
@chapter Dictionary

@include include/fun-sb-texinfo-document-package.texinfo
@include include/fun-sb-texinfo-document-package-pathname.texinfo
@include include/fun-sb-texinfo-generate-includes.texinfo

@include include/short-backmatter.texinfo

@bye