Skip to content

Commit acd1059

Browse files
VitSimonVitSimon
committed
EN : partial translation : helpviewer, innerJS, files.lst, keywords-files.lst, keywords.lst, tree.lst, texts
1 parent 5530cbe commit acd1059

File tree

9 files changed

+285
-2
lines changed

9 files changed

+285
-2
lines changed

‎en/heading.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 📑 Heading detection
22

3-
💡 Recommendations:
3+
💡 Recommendation:
44
- Each chapter should start with h1 (1x #) heading which will be the 1st one heading and text on the start of the document.
55

66
**HelpViewer** resolves document heading in this order of priority (from most significant):

‎en/helpviewer.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# 🔎 HelpViewer Project
2+
3+
## Organization
4+
5+
Organization [HelpViewer][HelpViewer] contains 2 basic types of repositories:
6+
7+
- Basic project repositories - Viewer, translations, another service repositories
8+
- Help files repositories (**help\***)
9+
10+
## Basic repositories
11+
12+
| Repository | Content |
13+
|---|---|
14+
| [HelpViewer][RHelpViewer] | Base repository of project - help files viewer. |
15+
| [Translations][RTranslations] | Language translation strings for UI of HelpViewer. Repository is inserted to **HelpViewer** as a Git submodule. It is also one of the sources of language list which is offered to user for language selection of UI and help file version. |
16+
| [.github][R.github] | Base repository of organization with operational information. |
17+
| [helpviewer.github.io][RWebHello] | GitHub Pages project for web presentation. [CI deployment script][RWebHelloDeploy] will do page content update with defined version number to deploy. |
18+
| [fulltextSearchDBBuilder][FTSIndexBuilder] | Full text index generator logic. This Bash skript is used by CI scripts which handles publishing of help files in case there is required to create full text index. |
19+
| [helpTemplate][RhelpTemplate] | Template for help file project. It is intended for help authors as a basic blank project. |
20+
21+
## Help files repositories
22+
23+
Repository names are starting with **help\***. Due to the naming of the project, there are exceptions as described above.
24+
25+
| Repository | Content |
26+
|---|---|
27+
| [helpHello][RhelpHello] | Project hello help file for public web presentation. |
28+
| [helpUser][RhelpUser] | Help file with starting instruction, UI description for HelpViewer users. Ut describes basic work with Viewer. |
29+
| [helpAuthorsGuide][RhelpAuthorsGuide] | (This) Help file (pages) for help file authors. Describes all necessary steps for creation and publishing of your own help file. |
30+
31+
## Version publishing
32+
33+
- Versions are released irregularly
34+
- The version number is always the date of the release in yearmonthday format (for example: 20250621)
35+
- If more than one version is released on a given day, then the first version has the format yearmonth and each subsequent version has the suffix **-number** starting from 1 with step 1, for example: 20250606-1, 20250606-2
36+
- The data for describing version changes is obtained from **CHANGELOG.md** in the root of the repository. The description for the latest version is always appended to the beginning of the file. The oldest versions tend to be lowest in the listing. Do not change or remove the last section with “**File introduced**” - it is also for your information
37+
- This procedure applies to **HelpViewer** as well as other tools and issued help
38+
- The same procedure is also recommended for authors of help files, although they are free to decide this point on their own
39+
40+
[HelpViewer]: https://github.com/HelpViewer "HelpViewer"
41+
[RHelpViewer]: https://github.com/HelpViewer/HelpViewer "HelpViewer"
42+
[RTranslations]: https://github.com/HelpViewer/Translations "Translation"
43+
[RWebHello]: https://github.com/HelpViewer/helpviewer.github.io "Project web presentation"
44+
[RWebHelloDeploy]: https://github.com/HelpViewer/helpviewer.github.io/actions/workflows/toPages.yml "Project web presentation - deployment"
45+
[FTSIndexBuilder]: https://github.com/HelpViewer/fulltextSearchDBBuilder "Full text index builder"
46+
[RhelpTemplate]: https://github.com/HelpViewer/helpTemplate "Help file project template"
47+
[RhelpHello]: https://github.com/HelpViewer/helpHello
48+
[RhelpUser]: https://github.com/HelpViewer/helpUser
49+
[RhelpAuthorsGuide]: https://github.com/HelpViewer/helpAuthorsGuide
50+
[R.github]: https://github.com/HelpViewer/.github "Repository with basic information"

‎en/innerJS.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# 🧩 Inline JavaScript
2+
3+
Into **md** text you can insert JavaScript code block, which will be executed after chapter text is loaded.
4+
5+
Chapter text is loaded and sfter that with short time delay there will be executed functions of inline JavaScript.
6+
7+
💡 Recommendation:
8+
- Please be courteous and use this feature of the app judiciously with respect to user experience and adherence to accessibility rules for your help. HelpViewer does not interfere with the script logic here in any way, it just passes it on to the client side for further processing.
9+
**The author of the help is responsible for the content and effects of the scripts embedded within the help.**
10+
11+
```
12+
1. Download <span id="linkhereI"></span> and unzip it.
13+
14+
<script>
15+
insertDownloadLink('linkhereI');
16+
</script>
17+
```
18+
19+
With insertDownloadLink function you can do call insertDownloadLink('target object id', 'mask'), where in mask text will be any of these special characters:
20+
21+
- @ = newest version
22+
- | = package.zip (as same behavior as without any mask specified)
23+
- _ = current version of HelpViewer (not help file) user has currently opened
24+
25+
This example will prepare hyperlink to package with latest published version of **HelpViewer** and inserts it to named span object:
26+
27+
1. Download <span id="linkhereI"></span> and unzip it.
28+
29+
<script>
30+
insertDownloadLink('linkhereI');
31+
</script>

‎en/mdata/files.lst.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# 📑 File list (files.lst)
2+
3+
- ⚠️ This format is very strict, please follow the rules exactly.
4+
- Defines list of valid chapters of help file
5+
- It is recommended that all files should be listed there
6+
- One row = one item
7+
- Line break in the uncomplete definition is not allowed
8+
- This file is used for the keywords dictionary (📇) and full text search (🔎). In both cases, it provides a descriptive title for the file. If a file is not listed here, its relative path and filename will be shown instead
9+
10+
## File structure
11+
12+
```
13+
[1]|[2]
14+
```
15+
16+
## Position description
17+
18+
| Position | Description |
19+
|---|---|
20+
| [1] | Relative file path and name inside help file |
21+
| [2] | Title used in dictionaries. It is also a backup title when user will reload the page without any click on tree or any dictionary item |

‎en/mdata/keywords-files.lst.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 📇 Keyword - file connection (keywords-files.lst)
2+
3+
- ⚠️ This format is very strict, please follow the rules exactly.
4+
- This file defines interconnection of keywords ([keywords.lst][Dkeywords.lst]) and file list ([files.lst][Dfiles.lst])
5+
- One row = one item
6+
- Line break in the uncomplete definition is not allowed
7+
- This file is used for the keywords dictionary (📇)
8+
9+
## File structure
10+
11+
```
12+
[1]
13+
[1];[2]
14+
```
15+
16+
## Position description
17+
18+
| Position | Description |
19+
|---|---|
20+
| [1] | Index propojeného souboru (počítáno od nuly) |
21+
| [2] | Index propojeného souboru (počítáno od nuly). Opakování je přípustné, vždy je však před informací středník (**;**) |
22+
23+
## Rules
24+
25+
- A line never ends with a semicolon
26+
- Semicolon is the delimiter for any single interconnection definition
27+
- Each line in this file corresponds to the same line in the keyword file. If you open the two files side by side, you can think of them as two columns of a table - the corresponding information is on the same rows.
28+
29+
[Dfiles.lst]: mdata/files.lst.md "files.lst"
30+
[Dkeywords.lst]: mdata/keywords.lst.md "keywords.lst"

‎en/mdata/keywords.lst.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# 📇 Keywords list (keywords.lst)
2+
3+
- ⚠️ This format is very strict, please follow the rules exactly.
4+
- Defines keywords list in help
5+
- One row = one item
6+
- Line break in the uncomplete definition is not allowed
7+
- This file is used for the keywords dictionary (📇)
8+
9+
## File structure
10+
11+
```
12+
[1]
13+
[1];[2]
14+
```
15+
16+
## Position description
17+
18+
| Position | Description |
19+
|---|---|
20+
| [1] | Keyword |
21+
| [2] | Optional. Synonym for a given word. If it should be used, then If it is to be used, it is always preceded by a semicolon (**;**) and may be repeated any number of times. |
22+
23+
## Rules
24+
25+
- A space is not a word separator
26+
- A line never ends with a semicolon
27+
- At least position [1] must be defined
28+
- Synonyms are broken down into individual words and the user is offered the same list of topics for all these words (**keywords-files.lst**)
29+
- If synonyms overlap across rows (one synonym appears on multiple rows), HelpViewer will build a merged list of topics in which each topic will only appear once (decided here by files.lst)

‎en/mdata/tree.lst.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 📖 TOC tree (tree.lst)
2+
3+
- ⚠️ This format is very strict, please follow the rules exactly.
4+
- This file defines hierarchy structure of help chapters
5+
- It is not mandatory that all files are part of it
6+
- One row = one item of tree
7+
- Line break in the uncomplete definition is not allowed
8+
9+
## File structure
10+
11+
```
12+
[1][2]|[3]|[4]|[5]
13+
```
14+
15+
## Position description
16+
17+
| Position | Description |
18+
|---|---|
19+
| [1] | One space = one sublevel (plunge). No spaces = main level |
20+
| [2] | Title of the item in the tree |
21+
| [3] | Hint bubble text when hovering over an item |
22+
| [4] | Empty or valid relative path to the image to be attached to the left side of the item |
23+
| [5] | The relative path of the target file with the chapter content or special names below |
24+
25+
### Position [5]: special names
26+
27+
| Value | Description |
28+
|---|---|
29+
| =latestApp | Looks up the URI for the latest version of HelpViewer |
30+
| =latestHelp | Looks up the URI for the latest version of the help file (if the repository is hosted on GitHub as public) |

‎en/texts.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# 📝 Chapter text
2+
3+
HelpViewer predicts all texts will be coded in **UTF-8 no BOM (65001)** code page.
4+
5+
In chapter text you can use all the standard syntax of **[md][MDSyntax]** document as e.g. **#** tag for heading even to lovel 6 (e.g. **###### Heading**). These headings are used by **HelpViewer** to build sub chapters (🔖) structure automatically and offers this TOC to user for improve browsing experience. If there will not be any more headings in chapter (excluding **h1**)then not any list will be shown to user.
6+
7+
You can also intersperse the md code with html or javascript code if needed.
8+
9+
In next subchapters of this chapter there are more information which you should know and also HelpViewer features you can use.
10+
11+
## Icons
12+
13+
Inside chapter text you can insert unicode letters/characters also. Some of them stands for icons which you can use without need to install any other external library.
14+
15+
The insertion into the chapter text is done either by direct copy of the character or by inserting two other shapes (HTML character entities):
16+
```
17+
💡
18+
&amp;#128161;
19+
&amp;#x1F4A1;
20+
```
21+
22+
For exact codes and situations I advice to use Copilot/ChatGPT, which will help you find suitable icons quickly.
23+
24+
## Lists
25+
26+
For correct bullet list item there is required to have a space between marking (number for numbered list, - for bullet list):
27+
28+
```
29+
- Point2
30+
1. Point2
31+
```
32+
33+
Example (pair - wrong and right):
34+
35+
A)
36+
37+
-Point1
38+
- Point2
39+
40+
B)
41+
42+
1.Point1
43+
1. Point2
44+
45+
## Paragraphs
46+
47+
In case of paragraph there is need to have one empty row between them in **md** file:
48+
```
49+
First paragraph
50+
51+
Second paragraph
52+
```
53+
54+
Example:
55+
56+
First paragraph
57+
58+
Second paragraph
59+
60+
## Two spaces on the end of line
61+
62+
If you will use on the end of one line twice the space ( ) character and you will continue with another line afterwards then you will provide the same spacing for new line as the previous one line had:
63+
64+
```
65+
- ☰ Show left panel back__
66+
*(if hidden)*
67+
```
68+
In this code listing there underscores (_; 2 are here) stands for spaces ( ) to be clearly visible.
69+
70+
Example:
71+
72+
- ☰ Show left panel back
73+
*(if hidden)*
74+
75+
## Collapsible section
76+
77+
With usage of plain HTML code you can create collapsible section in text of your chapter. Rendering logic will correctly transfers to correct output for user.
78+
79+
```
80+
&lt;details&gt;
81+
&lt;summary&gt;There is main heading here. Another information will be shown when it will be clicked&lt;/summary&gt;
82+
There is extended description of given point.
83+
&lt;/details&gt;
84+
```
85+
86+
Example:
87+
<details>
88+
<summary>There is main heading here. Another information will be shown when it will be clicked</summary>
89+
There is extended description of given point.
90+
</details>
91+
92+
[MDSyntax]: https://www.markdownguide.org/basic-syntax/ "MD syntax"

‎en/tree.lst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Publishing of help|Publishing of help||publish.md
2424
🔑 Token|GitHub PAT token||token.md
2525
🌐 New language|New language||newLang.md
2626
🤝 Integration with application|Integration with application||integration.md
27-
Project HelpViewer|Project HelpViewer||helpviewer.md
27+
HelpViewer Project|HelpViewer Project||helpviewer.md
2828
🌐 New language|New language||newLangViewer.md
2929
🚀 Download latest version|Package for offline use and deployment||=latestApp
3030
🔗 GitHub|GitHub repository||https://github.com/HelpViewer/HelpViewer

0 commit comments

Comments
 (0)