cdt/doc/org.eclipse.cdt.doc.user/README.md

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.

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. See the Eclipse help for general information.

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)
• Since C++ uses a double + it can confuse asciidoc, replace C\+\+ -> {cpp} (the C++ attribute). See Character Replacement Attributes Reference 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)