From e72c45fb2227dd6cc536388a01a3737fd952513c Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Thu, 31 Aug 2017 12:01:37 -0500 Subject: [PATCH] CONTRIBUTING-DOCUMENTATION.adoc edit I made it be more formal and be easier to read. --- CONTRIBUTING-DOCUMENTATION.adoc | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING-DOCUMENTATION.adoc b/CONTRIBUTING-DOCUMENTATION.adoc index 900e9d42a99b..03f64f3ce2f6 100644 --- a/CONTRIBUTING-DOCUMENTATION.adoc +++ b/CONTRIBUTING-DOCUMENTATION.adoc @@ -1,4 +1,4 @@ -= How to contribute to the reference manual += 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. @@ -13,14 +13,16 @@ from the project root execute the following command: ./gradlew asciidoctor ---- -The generated reference manual will then be available at `build/asciidoc/html5/index.html`. +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. +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/asciidoc/Guardfile`. -Make sure first to follow the setup instructions within the +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]): @@ -31,26 +33,28 @@ install to make it work (assuming that you are using http://livereload.com/[Live ---- When running `guard start` within the `src/asciidoc/` folder, any changes to the -`src/asciidoc/index.adoc` file will automatically be written to +`src/asciidoc/index.adoc` file are automatically written to `src/asciidoc/build/index.html`. == Troubleshooting -* If you are using LiveReload, make sure to select _Allow access to file URLs_ in the +* 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. +* 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. +* 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]