# C/C++ Development User Guide

## AsciiDoc content

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:

```
mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources
# or to turn on auto-refresh
mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources -P asciidoc-auto-refresh
```

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:

`
image:command_link.png[] link:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Editors)')[General > Editors]
`

Notes:

- The `livehelp.js` is included automatically with `docinfo-header.htm`
- `PLUGINS_ROOT` cannot be used within the adoc files, so use `image:command_link.png[]` instead

## Converting html CDT help to adoc

Use pandoc, e.g.:

```
pandoc getting_started/cdt_w_basic.htm -o src/getting_started/cdt_w_basic.adoc
# or a whole group of files
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)