= How to Contribute to the Reference Manual

The Spring Framework reference manual uses http://asciidoctor.org/[asciidoctor]. This
document describes how to contribute documentation updates.

== Building with Gradle

You can build the documentation using Gradle using the `asciidoctor` task. For example,
from the project root execute the following command:

[indent=0]
----
	./gradlew asciidoctor
----

The generated reference manual will then be available at
`build/asciidoc/html5/index.html`.

== Live Editing

One of the nice features about using Asciidoctor is the support for live editing.

You will find a Guardfile already present at
`spring-framework/src/docs/asciidoc/Guardfile`. First, follow the setup instructions
within the
http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc
with Live Preview] document. Once you have done that, there are additional gems to
install to make it work (assuming that you are using http://livereload.com/[LiveReload]):

[indent=0]
----
	gem install guard-rspec guard-livereload
----

When running `guard start` within the `src/asciidoc/` folder, any changes to the
`src/asciidoc/index.adoc` file are automatically written to
`src/asciidoc/build/index.html`.

== Troubleshooting

* If you are using LiveReload, select _Allow access to file URLs_ in the
LiveEdit plugin options of your browser.
* The icon used to enable _LiveReload_ can be a bit confusing. The dot is empty when it
is disabled and full when the plugin is active. Make sure to enable it on the tab
displaying the `index.html` file.
* Ensure you are _not_ running `guard start` at all, as two instances could not run at
the same time. To exit a current session in a clean way, type `e` in the shell.

== Documentation Notes

Some notes on the documentation.

* Documentation is wrapped at 90 chars. Ensure that you manually wrap your edits.
* Tabs are used for indentation. Do not use spaces.
* Follow the existing style when inserting `source` blocks.

Here are some useful resources for working with Asciidoctor:
* http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Quick Reference]
* http://asciidoctor.org/docs/user-manual/[Asciidoctor Manual]
* http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writers Guide]