The Asciidoctor Maven Plugin is configured to generate an HTML file in the `html/` folder for each AsciiDoc source file (`*.adoc`) placed in the `src/asciidoc/` folder.
All AsciiDoc source files should include GitHub rendering support, as illustrated in the [example document](src/asciidoc/example.adoc).
During content development, HTML files may be generated by invoking Maven locally:
Adding `-DuseSimrelRepo`, and after first run `-o` can speed up target platform resolution speed significantly.
## Embedding commands in help
Embedding commands in help needs to modify syntax slightly.
Links in adoc are always surrounded by double-quotes, therefore single-quotes (`'`) or escaped double-quote (`"`) need to be used in the command, as appropriate, this is opposite to the quoting that is shown in the Eclipse help [documentation](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command_authoring.htm).
See the [Eclipse help for general information](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command.htm).
e.g. opening a preference page can be done like this:
for i in getting_started/*; do pandoc -o src/${i%.*}.adoc $i; done
```
Apply these changes after:
- Replace `image:../images/` -> `image:` because we use images in different locations depending on whether we are in GitHub or in online help
- Replace `link:([^[]+).htm\[` -> `xref:$1.adoc[` so that links are always to `adoc` files. Asciidoctor will change that to `htm` on generation so if target has not been converted yet that is ok. This allows links to work when asciidoctor generates for other formats
- Fix anchors `\[#([^\]]+)\]####` -> `[[$1]]`
- Fix unneeded ` ` with `\u00A0` -> nothing (some of these were used to indent makefiles, but that meant they couldn't be copied and pasted anyway, so another solution is needed)
- Remove doubled-up line continuation characters `^\+\n \+` -> `+`
- Remove extra `+` around horizontal rulers (lines with `'''''`) `'''[\n\s]+\+` -> `'''` and ` *\+[\n\s]+'''` -> `'''`
- Removed unneeded line breaks `(.) \+$` -> `$1` (lines that have just `+` are [list continuation](https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation))
- Since `C++` uses a double `+` it can confuse asciidoc, replace `C\+\+` -> `{cpp}` (the C++ attribute). See [Character Replacement Attributes Reference](https://docs.asciidoctor.org/asciidoc/latest/attributes/character-replacement-ref/) for all built-in attributes.
- Remove copyright statements from bottom of files (the `docinfo-footer.htm` has copyright)
- Fix the related concepts/tasks in the footer (convert to lists?)
- Add the headers to the adoc file to enable all the features and ensure consistent copyrights. See adoc-headers.txt
- Remove the original htm file from source control and add it to .gitignore (add whole folder if possible, or individual files if not whole folder is converted)
