Generate more of the documentation with asciidoc and automate more

- 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 - Check-in generated htm files - this makes it easier to see if anything changes unexpectedly - help in the developement Eclipse "just works" as developers don't need to generate anything - 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) Prerequisite of eclipse-cdt#992
jonahgraham · Jan 8, 2025 · 992f98e · 992f98e
1 parent 2f55372
commit 992f98e
Show file tree

Hide file tree

Showing 45 changed files with 3,995 additions and 1,211 deletions.
diff --git a/doc/org.eclipse.cdt.doc.user/.gitignore b/doc/org.eclipse.cdt.doc.user/.gitignore
diff --git a/doc/org.eclipse.cdt.doc.user/README.md b/doc/org.eclipse.cdt.doc.user/README.md
@@ -11,3 +11,43 @@ During content development, HTML files may be generated by invoking Maven locall
 ```
 mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources
 ```
+## 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 (`&quot;`) 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 &gt; 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 `&nbsp;` 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
diff --git a/doc/org.eclipse.cdt.doc.user/adoc-headers.txt b/doc/org.eclipse.cdt.doc.user/adoc-headers.txt
@@ -0,0 +1,29 @@
+////
+Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
+This program and the accompanying materials
+are made available under the terms of the Eclipse Public License 2.0
+which accompanies this distribution, and is available at
+https://www.eclipse.org/legal/epl-2.0/
+
+SPDX-License-Identifier: EPL-2.0
+////
+
+// pull in shared headers, footers, etc
+:docinfo: shared
+
+// support image rendering and table of contents within GitHub
+ifdef::env-github[]
+:imagesdir: ../../images
+:toc:
+:toc-placement!:
+endif::[]
+
+// enable support for button, menu and keyboard macros
+:experimental:
+
+// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
+// this is checked by the build in do_generate_asciidoc.sh, which also ensures
+// that the checked in html is up to date.
+// do_generate_asciidoc.sh can also be used to apply this header to all the
+// adoc files.
+// ENDOFHEADER
diff --git a/doc/org.eclipse.cdt.doc.user/build.properties b/doc/org.eclipse.cdt.doc.user/build.properties
@@ -38,8 +38,7 @@ bin.includes = about.html,\
                intro/,\
                notices.html,\
                book.css,\
-               index*/,\
-               html/
+               index*/
 
 bin.excludes = build.properties,\
 			   customBuildCallbacks.xml

diff --git a/doc/org.eclipse.cdt.doc.user/example/coderay-asciidoctor.css b/doc/org.eclipse.cdt.doc.user/example/coderay-asciidoctor.css
@@ -0,0 +1,87 @@
+/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
+pre.CodeRay{background:#f7f7f8}
+.CodeRay .line-numbers{border-right:1px solid;opacity:.35;padding:0 .5em 0 0;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
+.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
+.CodeRay .line-numbers strong{color:#000}
+table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
+table.CodeRay td{vertical-align:top;line-height:inherit}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.code{padding:0 0 0 .75em}
+.CodeRay .debug{color:#fff!important;background:navy!important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:navy}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:teal}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#000}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:teal}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:teal}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
diff --git a/doc/org.eclipse.cdt.doc.user/example/example.htm b/doc/org.eclipse.cdt.doc.user/example/example.htm
@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 2.0.23">
+<title>Example document</title>
+<link rel="stylesheet" href="./../help.css">
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
+<link rel="stylesheet" href="./coderay-asciidoctor.css">
+</head>
+<body class="article">
+<div id="header">
+<h1>Example document</h1>
+</div>
+<div id="content">
+<div id="preamble">
+<div class="sectionbody">
+<div id="toc" class="toc">
+<div id="toctitle" class="title">Table of Contents</div>
+<ul class="sectlevel1">
+<li><a href="#_images">Images</a></li>
+<li><a href="#_tables">Tables</a></li>
+<li><a href="#_lists">Lists</a></li>
+<li><a href="#_code_blocks">Code blocks</a></li>
+<li><a href="#_makefiles">Makefiles</a></li>
+<li><a href="#_see_also">See also</a></li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_images">Images</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Example image:</p>
+</div>
+<div class="paragraph">
+<p><span class="image"><img src="../images/search.png" alt="Search dialog"></span></p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_tables">Tables</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Example table:</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 50%;">
+<col style="width: 50%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Column A</th>
+<th class="tableblock halign-left valign-top">Column B</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 1A</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 1B</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 2A</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 2B</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 3A</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 3B</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_lists">Lists</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Example list:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Item A</p>
+</li>
+<li>
+<p>Item B</p>
+</li>
+<li>
+<p>Item C</p>
+</li>
+</ol>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_code_blocks">Code blocks</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Example code block:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#include</span> <span class="include">&lt;stdio.h&gt;</span>
+
+<span class="predefined-type">int</span> main (<span class="predefined-type">int</span> argc, <span class="predefined-type">char</span>* argv[]) {
+
+    printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">Hello World!</span><span class="char">\n</span><span class="delimiter">&quot;</span></span>);
+    <span class="keyword">return</span> <span class="integer">0</span>;
+
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_makefiles">Makefiles</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><strong>TODO</strong>: How to handle tabs in makefiles? Without tabs Makefile code samples cannot be copied and pasted successfully.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_see_also">See also</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>See also the README.md at the root of this bundle as it has additional help on using AsciiDoc.</p>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+</div>
+</div>
+</body>
+</html>