Skip to content

Commit 5140906

Browse files
jonahgrahamjonahgraham
committed
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 #992
1 parent 2f55372 commit 5140906

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+4222
-1209
lines changed

‎doc/org.eclipse.cdt.doc.user/.gitignore

Lines changed: 0 additions & 2 deletions
This file was deleted.

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

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,43 @@ During content development, HTML files may be generated by invoking Maven locall
1111
```
1212
mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources
1313
```
14+
## Embedding commands in help
15+
16+
Embedding commands in help needs to modify syntax slightly.
17+
Links in adoc are always surrounded by double-quotes, so double-quotes in the link need to be escaped by use `"`.
18+
See the [Eclipse help for general information](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command.htm).
19+
20+
e.g. opening a preference page can be done like this:
21+
22+
`
23+
image:command_link.png[] link:javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Editors)")[General > Editors]
24+
`
25+
26+
Notes:
27+
28+
- The `livehelp.js` is included automatically with `docinfo-header.htm`
29+
- `PLUGINS_ROOT` cannot be used within the adoc files, so use `image:command_link.png[]` instead
30+
31+
## Converting html CDT help to adoc
32+
33+
Use pandoc, e.g.:
34+
35+
```
36+
pandoc getting_started/cdt_w_basic.htm -o src/getting_started/cdt_w_basic.adoc
37+
# or a whole group of files
38+
for i in getting_started/*; do pandoc -o src/${i%.*}.adoc $i; done
39+
```
40+
41+
Apply these changes after:
42+
43+
- Replace `image:../images/` -> `image:` because we use images in different locations depending on whether we are in GitHub or in online help
44+
- 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
45+
- Fix anchors `\[#([^\]]+)\]####` -> `[[$1]]`
46+
- 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)
47+
- Remove doubled-up line continuation characters `^\+\n \+` -> `+`
48+
- Remove extra `+` around horizontal rulers (lines with `'''''`) `'''[\n\s]+\+` -> `'''` and ` *\+[\n\s]+'''` -> `'''`
49+
- Removed unneeded line breaks `(.) \+$` -> `$1` (lines that have just `+` are [list continuation](https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation))
50+
- 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.
51+
- Remove copyright statements from bottom of files (the `docinfo-footer.htm` has copyright)
52+
- Fix the related concepts/tasks in the footer (convert to lists?)
53+
- Add the headers to the adoc file to enable all the features and ensure consistent copyrights. See adoc-headers.txt

‎doc/org.eclipse.cdt.doc.user/adoc-headers.txt

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
////
2+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
3+
This program and the accompanying materials
4+
are made available under the terms of the Eclipse Public License 2.0
5+
which accompanies this distribution, and is available at
6+
https://www.eclipse.org/legal/epl-2.0/
7+
8+
SPDX-License-Identifier: EPL-2.0
9+
////
10+
11+
// pull in shared headers, footers, etc
12+
:docinfo: shared
13+
14+
// support image rendering and table of contents within GitHub
15+
ifdef::env-github[]
16+
:imagesdir: ../../images
17+
:toc:
18+
:toc-placement!:
19+
endif::[]
20+
21+
// enable support for button, menu and keyboard macros
22+
:experimental:
23+
24+
// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
25+
// this is checked by the build in do_generate_asciidoc.sh, which also ensures
26+
// that the checked in html is up to date.
27+
// do_generate_asciidoc.sh can also be used to apply this header to all the
28+
// adoc files.
29+
// ENDOFHEADER

‎doc/org.eclipse.cdt.doc.user/asciidoc/coderay-asciidoctor.css

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
2+
pre.CodeRay{background:#f7f7f8}
3+
.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}
4+
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
5+
.CodeRay .line-numbers strong{color:#000}
6+
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
7+
table.CodeRay td{vertical-align:top;line-height:inherit}
8+
table.CodeRay td.line-numbers{text-align:right}
9+
table.CodeRay td.code{padding:0 0 0 .75em}
10+
.CodeRay .debug{color:#fff!important;background:navy!important}
11+
.CodeRay .annotation{color:#007}
12+
.CodeRay .attribute-name{color:navy}
13+
.CodeRay .attribute-value{color:#700}
14+
.CodeRay .binary{color:#509}
15+
.CodeRay .comment{color:#998;font-style:italic}
16+
.CodeRay .char{color:#04d}
17+
.CodeRay .char .content{color:#04d}
18+
.CodeRay .char .delimiter{color:#039}
19+
.CodeRay .class{color:#458;font-weight:bold}
20+
.CodeRay .complex{color:#a08}
21+
.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
22+
.CodeRay .color{color:#099}
23+
.CodeRay .class-variable{color:#369}
24+
.CodeRay .decorator{color:#b0b}
25+
.CodeRay .definition{color:#099}
26+
.CodeRay .delimiter{color:#000}
27+
.CodeRay .doc{color:#970}
28+
.CodeRay .doctype{color:#34b}
29+
.CodeRay .doc-string{color:#d42}
30+
.CodeRay .escape{color:#666}
31+
.CodeRay .entity{color:#800}
32+
.CodeRay .error{color:#808}
33+
.CodeRay .exception{color:inherit}
34+
.CodeRay .filename{color:#099}
35+
.CodeRay .function{color:#900;font-weight:bold}
36+
.CodeRay .global-variable{color:teal}
37+
.CodeRay .hex{color:#058}
38+
.CodeRay .integer,.CodeRay .float{color:#099}
39+
.CodeRay .include{color:#555}
40+
.CodeRay .inline{color:#000}
41+
.CodeRay .inline .inline{background:#ccc}
42+
.CodeRay .inline .inline .inline{background:#bbb}
43+
.CodeRay .inline .inline-delimiter{color:#d14}
44+
.CodeRay .inline-delimiter{color:#d14}
45+
.CodeRay .important{color:#555;font-weight:bold}
46+
.CodeRay .interpreted{color:#b2b}
47+
.CodeRay .instance-variable{color:teal}
48+
.CodeRay .label{color:#970}
49+
.CodeRay .local-variable{color:#963}
50+
.CodeRay .octal{color:#40e}
51+
.CodeRay .predefined{color:#369}
52+
.CodeRay .preprocessor{color:#579}
53+
.CodeRay .pseudo-class{color:#555}
54+
.CodeRay .directive{font-weight:bold}
55+
.CodeRay .type{font-weight:bold}
56+
.CodeRay .predefined-type{color:inherit}
57+
.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
58+
.CodeRay .key{color:#808}
59+
.CodeRay .key .delimiter{color:#606}
60+
.CodeRay .key .char{color:#80f}
61+
.CodeRay .value{color:#088}
62+
.CodeRay .regexp .delimiter{color:#808}
63+
.CodeRay .regexp .content{color:#808}
64+
.CodeRay .regexp .modifier{color:#808}
65+
.CodeRay .regexp .char{color:#d14}
66+
.CodeRay .regexp .function{color:#404;font-weight:bold}
67+
.CodeRay .string{color:#d20}
68+
.CodeRay .string .string .string{background:#ffd0d0}
69+
.CodeRay .string .content{color:#d14}
70+
.CodeRay .string .char{color:#d14}
71+
.CodeRay .string .delimiter{color:#d14}
72+
.CodeRay .shell{color:#d14}
73+
.CodeRay .shell .delimiter{color:#d14}
74+
.CodeRay .symbol{color:#990073}
75+
.CodeRay .symbol .content{color:#a60}
76+
.CodeRay .symbol .delimiter{color:#630}
77+
.CodeRay .tag{color:teal}
78+
.CodeRay .tag-special{color:#d70}
79+
.CodeRay .variable{color:#036}
80+
.CodeRay .insert{background:#afa}
81+
.CodeRay .delete{background:#faa}
82+
.CodeRay .change{color:#aaf;background:#007}
83+
.CodeRay .head{color:#f8f;background:#505}
84+
.CodeRay .insert .insert{color:#080}
85+
.CodeRay .delete .delete{color:#800}
86+
.CodeRay .change .change{color:#66f}
87+
.CodeRay .head .head{color:#f4f}

‎doc/org.eclipse.cdt.doc.user/asciidoc/example.htm

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7+
<meta name="generator" content="Asciidoctor 2.0.23">
8+
<title>Example document</title>
9+
<link rel="stylesheet" href="./../help.css">
10+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
11+
<link rel="stylesheet" href="./coderay-asciidoctor.css">
12+
</head>
13+
<body class="article">
14+
<div id="header">
15+
<h1>Example document</h1>
16+
</div>
17+
<div id="content">
18+
<div id="preamble">
19+
<div class="sectionbody">
20+
<div id="toc" class="toc">
21+
<div id="toctitle" class="title">Table of Contents</div>
22+
<ul class="sectlevel1">
23+
<li><a href="#_images">Images</a></li>
24+
<li><a href="#_tables">Tables</a></li>
25+
<li><a href="#_lists">Lists</a></li>
26+
<li><a href="#_code_blocks">Code blocks</a></li>
27+
<li><a href="#_makefiles">Makefiles</a></li>
28+
<li><a href="#_see_also">See also</a></li>
29+
</ul>
30+
</div>
31+
</div>
32+
</div>
33+
<div class="sect1">
34+
<h2 id="_images">Images</h2>
35+
<div class="sectionbody">
36+
<div class="paragraph">
37+
<p>Example image:</p>
38+
</div>
39+
<div class="paragraph">
40+
<p><span class="image"><img src="../images/search.png" alt="Search dialog"></span></p>
41+
</div>
42+
</div>
43+
</div>
44+
<div class="sect1">
45+
<h2 id="_tables">Tables</h2>
46+
<div class="sectionbody">
47+
<div class="paragraph">
48+
<p>Example table:</p>
49+
</div>
50+
<table class="tableblock frame-all grid-all stretch">
51+
<colgroup>
52+
<col style="width: 50%;">
53+
<col style="width: 50%;">
54+
</colgroup>
55+
<thead>
56+
<tr>
57+
<th class="tableblock halign-left valign-top">Column A</th>
58+
<th class="tableblock halign-left valign-top">Column B</th>
59+
</tr>
60+
</thead>
61+
<tbody>
62+
<tr>
63+
<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 1A</p></td>
64+
<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 1B</p></td>
65+
</tr>
66+
<tr>
67+
<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 2A</p></td>
68+
<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 2B</p></td>
69+
</tr>
70+
<tr>
71+
<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 3A</p></td>
72+
<td class="tableblock halign-left valign-top"><p class="tableblock">Cell 3B</p></td>
73+
</tr>
74+
</tbody>
75+
</table>
76+
</div>
77+
</div>
78+
<div class="sect1">
79+
<h2 id="_lists">Lists</h2>
80+
<div class="sectionbody">
81+
<div class="paragraph">
82+
<p>Example list:</p>
83+
</div>
84+
<div class="olist arabic">
85+
<ol class="arabic">
86+
<li>
87+
<p>Item A</p>
88+
</li>
89+
<li>
90+
<p>Item B</p>
91+
</li>
92+
<li>
93+
<p>Item C</p>
94+
</li>
95+
</ol>
96+
</div>
97+
</div>
98+
</div>
99+
<div class="sect1">
100+
<h2 id="_code_blocks">Code blocks</h2>
101+
<div class="sectionbody">
102+
<div class="paragraph">
103+
<p>Example code block:</p>
104+
</div>
105+
<div class="listingblock">
106+
<div class="content">
107+
<pre class="CodeRay highlight"><code data-lang="c"><span class="preprocessor">#include</span> <span class="include">&lt;stdio.h&gt;</span>
108+
109+
<span class="predefined-type">int</span> main (<span class="predefined-type">int</span> argc, <span class="predefined-type">char</span>* argv[]) {
110+
111+
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>);
112+
<span class="keyword">return</span> <span class="integer">0</span>;
113+
114+
}</code></pre>
115+
</div>
116+
</div>
117+
</div>
118+
</div>
119+
<div class="sect1">
120+
<h2 id="_makefiles">Makefiles</h2>
121+
<div class="sectionbody">
122+
<div class="paragraph">
123+
<p><strong>TODO</strong>: How to handle tabs in makefiles? Without tabs Makefile code samples cannot be copied and pasted successfully.</p>
124+
</div>
125+
</div>
126+
</div>
127+
<div class="sect1">
128+
<h2 id="_see_also">See also</h2>
129+
<div class="sectionbody">
130+
<div class="paragraph">
131+
<p>See also the README.md at the root of this bundle as it has additional help on using AsciiDoc.</p>
132+
</div>
133+
</div>
134+
</div>
135+
</div>
136+
<div id="footer">
137+
<div id="footer-text">
138+
</div>
139+
</div>
140+
</body>
141+
</html>

‎doc/org.eclipse.cdt.doc.user/example/coderay-asciidoctor.css

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
2+
pre.CodeRay{background:#f7f7f8}
3+
.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}
4+
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
5+
.CodeRay .line-numbers strong{color:#000}
6+
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
7+
table.CodeRay td{vertical-align:top;line-height:inherit}
8+
table.CodeRay td.line-numbers{text-align:right}
9+
table.CodeRay td.code{padding:0 0 0 .75em}
10+
.CodeRay .debug{color:#fff!important;background:navy!important}
11+
.CodeRay .annotation{color:#007}
12+
.CodeRay .attribute-name{color:navy}
13+
.CodeRay .attribute-value{color:#700}
14+
.CodeRay .binary{color:#509}
15+
.CodeRay .comment{color:#998;font-style:italic}
16+
.CodeRay .char{color:#04d}
17+
.CodeRay .char .content{color:#04d}
18+
.CodeRay .char .delimiter{color:#039}
19+
.CodeRay .class{color:#458;font-weight:bold}
20+
.CodeRay .complex{color:#a08}
21+
.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
22+
.CodeRay .color{color:#099}
23+
.CodeRay .class-variable{color:#369}
24+
.CodeRay .decorator{color:#b0b}
25+
.CodeRay .definition{color:#099}
26+
.CodeRay .delimiter{color:#000}
27+
.CodeRay .doc{color:#970}
28+
.CodeRay .doctype{color:#34b}
29+
.CodeRay .doc-string{color:#d42}
30+
.CodeRay .escape{color:#666}
31+
.CodeRay .entity{color:#800}
32+
.CodeRay .error{color:#808}
33+
.CodeRay .exception{color:inherit}
34+
.CodeRay .filename{color:#099}
35+
.CodeRay .function{color:#900;font-weight:bold}
36+
.CodeRay .global-variable{color:teal}
37+
.CodeRay .hex{color:#058}
38+
.CodeRay .integer,.CodeRay .float{color:#099}
39+
.CodeRay .include{color:#555}
40+
.CodeRay .inline{color:#000}
41+
.CodeRay .inline .inline{background:#ccc}
42+
.CodeRay .inline .inline .inline{background:#bbb}
43+
.CodeRay .inline .inline-delimiter{color:#d14}
44+
.CodeRay .inline-delimiter{color:#d14}
45+
.CodeRay .important{color:#555;font-weight:bold}
46+
.CodeRay .interpreted{color:#b2b}
47+
.CodeRay .instance-variable{color:teal}
48+
.CodeRay .label{color:#970}
49+
.CodeRay .local-variable{color:#963}
50+
.CodeRay .octal{color:#40e}
51+
.CodeRay .predefined{color:#369}
52+
.CodeRay .preprocessor{color:#579}
53+
.CodeRay .pseudo-class{color:#555}
54+
.CodeRay .directive{font-weight:bold}
55+
.CodeRay .type{font-weight:bold}
56+
.CodeRay .predefined-type{color:inherit}
57+
.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
58+
.CodeRay .key{color:#808}
59+
.CodeRay .key .delimiter{color:#606}
60+
.CodeRay .key .char{color:#80f}
61+
.CodeRay .value{color:#088}
62+
.CodeRay .regexp .delimiter{color:#808}
63+
.CodeRay .regexp .content{color:#808}
64+
.CodeRay .regexp .modifier{color:#808}
65+
.CodeRay .regexp .char{color:#d14}
66+
.CodeRay .regexp .function{color:#404;font-weight:bold}
67+
.CodeRay .string{color:#d20}
68+
.CodeRay .string .string .string{background:#ffd0d0}
69+
.CodeRay .string .content{color:#d14}
70+
.CodeRay .string .char{color:#d14}
71+
.CodeRay .string .delimiter{color:#d14}
72+
.CodeRay .shell{color:#d14}
73+
.CodeRay .shell .delimiter{color:#d14}
74+
.CodeRay .symbol{color:#990073}
75+
.CodeRay .symbol .content{color:#a60}
76+
.CodeRay .symbol .delimiter{color:#630}
77+
.CodeRay .tag{color:teal}
78+
.CodeRay .tag-special{color:#d70}
79+
.CodeRay .variable{color:#036}
80+
.CodeRay .insert{background:#afa}
81+
.CodeRay .delete{background:#faa}
82+
.CodeRay .change{color:#aaf;background:#007}
83+
.CodeRay .head{color:#f8f;background:#505}
84+
.CodeRay .insert .insert{color:#080}
85+
.CodeRay .delete .delete{color:#800}
86+
.CodeRay .change .change{color:#66f}
87+
.CodeRay .head .head{color:#f4f}

0 commit comments

Comments
 (0)