mirror of
https://github.com/eclipse-cdt/cdt
synced 2025-08-15 20:25:46 +02:00
9aa3144840
- Migrate all getting_started from html to adoc
- Document (in README.md) notes on migrating html to adoc
- Reorganize generation of adoc slightly so that
- all directories can be generates at once
- output suffix changed to htm so that migrated files
exist at the same URL on help.eclipse.org
- Add generation to the cleanliness checks to ensure that the
html matches adoc
- Manage the adoc headers with a script as that is a large section
of copy-pasted code on each adoc file (see README + adoc-headers.txt)
- Move maven version info to pluginManagement (consistency with other
maven plug-ins)
- New profile "asciidoc-auto-refresh" which will auto build the
files as edited.
Prerequisite of #992
59 lines
3.8 KiB
Markdown
59 lines
3.8 KiB
Markdown
# 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)
|