Skip to content

Commit 9748332

Browse files
akudevakudev
committed
First complete version of README_AUTHORS.md
This file should probably go to the root.
1 parent 3e566ba commit 9748332

File tree

1 file changed

+87
-31
lines changed

1 file changed

+87
-31
lines changed

‎tools/dev-server/README_AUTHORS.md

Lines changed: 87 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,86 +2,142 @@
22

33
# General
44

5-
blah
5+
The setup of this project allows maintaining *one* tutorial text that covers both JavaScript and TypeScript with minimal overhead and without duplication of content.
66

7-
# TypeScript
7+
Readers of the tutorial can freely switch the programming language of code snippets or the entire page, once deployed on GitHub Pages. For tutorial authors, an integrated dev server allows previewing the result with the same functionality locally and instantly.
88

9-
## Converting the JS Code to TypeScript
9+
Main features of the two-language support are:
10+
1. Content meant only for *one* of the programming languages can be hidden in the other by enclosing it in a specific block.
11+
2. Two adjacent code sections in different languages are automatically converted to a tab container which allows switching between languages.
12+
3. File extensions writen as `.?s` appear automatically as `.js` or `.ts` depending on the current language.
1013

11-
blah
14+
## Limitations
1215

13-
(Develop the tutorial in TS and use the debug version of the transpilation result as JS code. )
16+
The feature 3. above does not work inside code blocks (yet).
1417

15-
Search for and remove content containing the following in the transpiled JS code:
1618

17-
### `_interopRequireDefault`
19+
## Running the preview/dev server
1820

19-
Looks like this:
21+
To immediately preview the markdown document you are writing *including* the two-language magic, simply run
2022

21-
```js
22-
sap.ui.define(["./BaseController"], function (__BaseController) {
23-
24-
function _interopRequireDefault(obj) {
25-
return obj && obj.__esModule && typeof obj.default !== "undefined" ? obj.default : obj;
26-
}
27-
const BaseController = _interopRequireDefault(__BaseController);
23+
```sh
24+
npm i
2825
```
2926

30-
Remove the function definition and the line calling the function. Rename the dependency in the `sap.ui.define` call from `__BaseController` to `BaseController`.
27+
in the root folder of this project once for the setup, then to actually run the server, run
3128

29+
```sh
30+
npm start
31+
```
3232

33-
### (More of this, unless we do it in the transpiler)
33+
Then, open http://localhost:1337/README.md in your browser.
3434

3535

36-
## Combining JavaScript and TypeScript in one Common Text
36+
## Writing *one* document which covers both JavaScript and TypeScript without duplication
3737

3838
The following features help providing language-specific content without duplication of other content.
3939

40+
### 1. Language-specific Blocks of Content
4041

41-
42-
### Language-specific Blocks of Content
43-
44-
When a certain part of the tutorial content (can be explanation and/or code) is only relevant for *one* of the languages (JavaScript *or* TypeScript), then enclose it within the following tags. Note how the CSS class decides for which language it is meant!
42+
When a certain part of the tutorial content (can be explanation and/or code) is only relevant for *one* of the languages (JavaScript *or* TypeScript), then enclose it within the following tags. The CSS class decides for which language it is meant!
4543

4644
TypeScript-only:
4745

4846
```html
4947
<details class="ts-only" markdown="1"><summary>This section is relevant for TypeScript only</summary>
50-
...
48+
...here comes the TS-only text...
5149
</details>
5250
```
5351

5452
JavaScript-only:
5553

5654
```html
5755
<details class="js-only" markdown="1"><summary>This section is relevant for JavaScript only</summary>
58-
...
56+
...here comes the JS-only text...
5957
</details>
6058
```
6159

62-
The `markdown="1"` part is required for markdown parsing within HTML and the `<summary>` is helpful for readers of the raw markdown view, so use the tags as-is, with the actual content in between.
60+
The `markdown="1"` part is required for markdown parsing within HTML and the `<summary>` is helpful for readers of the raw markdown view, so please use the tag structure as-is, with your actual content in between.
6361

64-
#### Resulting Appearance<span class="hidden"> in markdown view</span>
62+
#### Resulting Appearance<span class="hidden"> in markdown view (not in the final page)</span>
6563

6664
<details class="ts-only" markdown="1"><summary>This section is relevant for TypeScript only</summary>
67-
Some TypeScript content.
65+
...here comes the TS-only text...
6866
</details>
6967

7068
<details class="js-only" markdown="1"><summary>This section is relevant for JavaScript only</summary>
71-
Some JavaScript content.
69+
...here comes the JS-only text...
7270
</details>
7371

7472

75-
### File Extensions (`.js/.ts`)
73+
### 2. Switchable code blocks in both languages
74+
75+
When a piece of code should be displayed in either JS or TS, whatever is current, then simply create two adjacent markdown-fenced code blocks. They are automatically recognized as language-specific alternatives.
76+
77+
Example:
78+
```md
79+
80+
```js
81+
const i = 0;
82+
```
83+
84+
```ts
85+
const i: number = 0;
86+
```
87+
```
88+
> Do not indent, this was only done to make the backticks within the code block visible.
89+
90+
> Some places where this occurs may not be properly recognized, so make sure to test it.
91+
92+
#### Resulting Appearance<span class="hidden"> in markdown view (here in markdown you still see BOTH and no tab container; the magic only happens in the dev server and in GitHub Pages)</span>
93+
94+
```js
95+
const i = 0;
96+
```
97+
98+
```ts
99+
const i: number = 0;
100+
```
101+
102+
### 3. File Extensions (`.js/.ts`)
76103

77-
When the text or a heading mentions the name of a file that will be JavaScript or TypeScript, depending on the language, then use the file extension `.?s`. It will automatically be switched to the current language.
104+
When the text or a section heading mentions the name of a file that will be JavaScript or TypeScript, depending on the language, then use the file extension `.?s`. It will automatically be switched to the current language.
78105

79106
Example:
80107
```md
81108
In this step you create the file `Example.controller.?s`.
82109
```
83110

84111

85-
#### Resulting Appearance<span class="hidden"> in markdown view</span>
112+
#### Resulting Appearance<span class="hidden"> in markdown view (here the extension is not replaced, the replacement only happens in the dev server and in GitHub Pages)</span>
86113

87114
In this step you create the file `Example.controller.?s`.
115+
116+
117+
118+
119+
## Converting the JS Code to TypeScript
120+
121+
TODO: tool support for this functionality does not exist yet. It can, however, already be done manually.
122+
123+
General approach: develop the tutorial in TS and use the debug version of the transpilation result as JS code.
124+
125+
To clean up the transpilation result, search for and remove content containing the following in the transpiled JS code:
126+
127+
### `_interopRequireDefault`
128+
129+
Looks like this:
130+
131+
```js
132+
sap.ui.define(["./BaseController"], function (__BaseController) {
133+
134+
function _interopRequireDefault(obj) {
135+
return obj && obj.__esModule && typeof obj.default !== "undefined" ? obj.default : obj;
136+
}
137+
const BaseController = _interopRequireDefault(__BaseController);
138+
```
139+
140+
Remove the function definition and the line calling the function. Rename the dependency in the `sap.ui.define` call from `__BaseController` to `BaseController`.
141+
142+
143+
### TODO: Some more similar things, unless we do it in the transpiler

0 commit comments

Comments
 (0)