Skip to content

Commit 22b3505

Browse files
VitSimonVitSimon
committed
EN : partial translation : general, helpCfg, keywords, newHelp, README, struct
1 parent 8a06341 commit 22b3505

File tree

7 files changed

+187
-1
lines changed

7 files changed

+187
-1
lines changed

‎en/README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
# Main chapter
1+
# Authoring Guide
2+
3+
The main goal is to describe:
4+
- How to create your own help file,
5+
- Internal indexes and metadata structures,
6+
- Notable HelpViewer and its processes specifics,
7+
- Integration scenarios between your application and help file
8+
- HelpViewer GitHub overview and versioning description,
9+
- How to extend HelpViewer itself

‎en/general.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# 💡 General recommendation and information sources
2+
3+
In GitHub organization **[HelpVewer][HV]** you will find repositories starting with **help\***. With exception of **helpTemplate** and **HelpViewer** all of them are examples of help files. You can take any **Release** of these and its all attachments named like this mask **Help-*.zip**. Archives are passwordless so its content is accessible to browsing.
4+
5+
During your help file creation you can browse it in offline even if it has not been released. This way you can verify future results and behavior. You can do it this way - start **HelpViewer** in web browser with browsing local file content and you will give it relative dir path to your new help file:
6+
```
7+
file://.../HelpViewer/?d=../yourhelp/__/
8+
```
9+
10+
- __ stands for short code of selected language by user.
11+
- If path doesn't works, then replace slashes **/** in d parameter for **%2F**
12+
- Fulltext search will not work here (index is being built just during releasing of help file)
13+
14+
Phrase **[pub]** in commit text message is important - runs release of your help file. Prepare in this commit update of your CHANGELOG.md file for contain new version description on start of the file. It will be automatically used for Release notes.
15+
16+
[HV]: https://github.com/orgs/HelpViewer/repositories "Repositories"

‎en/helpCfg.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# 🛠️ Help configuration
2+
3+
You can change help configuration in file **_config.txt**. File is located in language version subdir. Each language has its own independent copy.
4+
5+
File structure is:
6+
7+
```
8+
key|value
9+
key|value
10+
```
11+
12+
## Rules
13+
14+
- 1 row = one value
15+
- If the same key will repeat later in the file, the last one value will be used
16+
17+
## Configuration keys
18+
19+
### TOC icons
20+
21+
| Key name | Meaning |
22+
|---|---|
23+
| OverrideBookIcon-opened | Open book character |
24+
| OverrideBookIcon-closed | Closed book character |
25+
26+
### Overwrite user settings of UI
27+
28+
| Key name | Meaning |
29+
|---|---|
30+
| OverrideColorTheme | Overwrites user selection of color scheme and saves it to user's configuration |
31+
| OverrideSidebarVisible | Overwrites user selection if left panel will be visible and saves it to user's configuration |
32+
33+
### Managed by publishing process
34+
| Key name | Meaning |
35+
|---|---|
36+
| _lang | Current help file (package) language |
37+
| _version | Released version (took from CHANGELOG.md) |
38+
| _prjname | (organization)/(repository name) in what the help file was present during publishing process. |

‎en/keywords-files.lst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
0;1;3;25;26
2+
1;2
3+
2;6;13;22;25
4+
3;6;7;11;10;21;26
5+
3
6+
4;25
7+
4;2;3;24;26;28
8+
5;10;11;12
9+
5
10+
6
11+
7
12+
5
13+
8;16
14+
9
15+
10;11
16+
11;21
17+
10
18+
12;17;18;19;20
19+
13;31
20+
14;15;25;26
21+
15;10
22+
16
23+
21
24+
22;26
25+
23;25;26
26+
24
27+
25
28+
26
29+
27;28;29;30

‎en/keywords.lst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Overview;General description
2+
Features
3+
Steps;How to
4+
Structure
5+
Path;Directory
6+
Advice;Tip;Recommendation
7+
GitHub;Repository
8+
Document;Chapter
9+
W3C
10+
Link;Hyperlink
11+
Image;Picture
12+
WYSIWYG
13+
Code
14+
Diagram;Graph
15+
Text
16+
Heading;Structure;Breakdown;Division;Subdivision;Chapter;Subchapter
17+
Entity
18+
Index;Dictionary;Matadata
19+
Language;Localization;Translation
20+
Settings;Customizing;Strom;Configuration;Options
21+
Icon
22+
Javascript;Java script
23+
Key;Keyword;Fulltext;Full text
24+
Release
25+
Settings;Customizing;Configuration;Options
26+
Token
27+
Integration;Compatibility
28+
HelpViewer
29+
Link;Hyperlink

‎en/newHelp.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# 📖 Create new help file
2+
3+
1. Go to repository: **[helpTemplate][template]**
4+
2. Click on right top button **Use this template** and **Create a new repository**.
5+
3. Set organization and name your repository according to your needs.
6+
4. Template contains **[CI script][template-CI]**, which you not need to change/update anyhow. In future there can be developed new functionalities which you would like to use in future. In this case you will overwrite CI script manually by copy of it from **helpTemplate**.
7+
5. Clone repository to your local computer:
8+
```
9+
git clone https://github.com/{USER or ORGANIZATION}/{REPOSITORY-NAME}.git
10+
```
11+
1. Files: **LICENSE** a **README.md** you can update according to your needs
12+
13+
[template]: https://github.com/HelpViewer/helpTemplate "Help file project template"
14+
[template-CI]: https://github.com/HelpViewer/helpTemplate/blob/main/.github/workflows/publish.yml "CI script"

‎en/struct.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# 🗂️ Help project structure
2+
3+
## Directories
4+
5+
In repository you will see this structure:
6+
```
7+
├───.github
8+
│ └───workflows
9+
├───cs
10+
└───en
11+
```
12+
13+
## Structure
14+
15+
Meaning of these is:
16+
17+
| File / path | Meaning |
18+
|---|---|
19+
| .github/workflows/publish.yml | CI script, which does [help file build][build]. Results of it is Release with these attachments: **Help-(language short code).zip** a **Help-.zip** with data of directory **_base** |
20+
| README.md | Base project description (update according to your needs) |
21+
| LICENSE | License text (update according to your needs) |
22+
| CHANGELOG.md | Change log document. This file is a source for change notes attached to releases which you will publish |
23+
| _base | Usually it is not defined or exists. You can overwrite [HelpViewer UI][cusui] here |
24+
| _invariant | Shared data over all language version of help. During publishing when there is equality in file names in language version, the _invariant file will overwrite that equally named file in language directory. |
25+
| directories cs, en, ... | 🌐 [Language version][newLang] of help file. When you will create new directory herem then you have created new language of your help. |
26+
27+
## Language version files
28+
29+
Subdirectory en/ :
30+
31+
| File / path | Meaning |
32+
|---|---|
33+
| _config.txt | [Help file configuration][configDesc] |
34+
| files.lst | [File list][Dfiles.lst] with relative paths and heading for dictionaries/lists and backup headings to chapters. |
35+
| fts-keywords.lst | 🔎 If this file exists, then publishing process will prepare also [fulltext index][Dfts-keywords.lst]. If you will delete this file, then you will deactivate this feature. Keep file empty in content. |
36+
| keywords.lst | 📇 [Keywords and synonyms][Dkeywords.lst] list. You have to fill this file manually. In case this file will not exists or it will be empty, then this feature will be deactivated. |
37+
| keywords-files.lst | Relation between [keywords and files][Dkeywords-files.lst] |
38+
| tree.lst | 📖 Definition of table of contents ([TOC][Dtree.lst]). In case this file will not exists or it will be empty, then this feature will be deactivated. |
39+
| README.md | 🏡 Help main page. It will be automatically opened as first. Button on left bottom panel is directly pointing to this page. |
40+
41+
- In language subdir you can freely create new subdirs as you want.
42+
- Hyperlinks between chapters keep in relative paths between source and target file.
43+
44+
[Dfiles.lst]: mdata/files.lst.md "files.lst"
45+
[Dkeywords.lst]: mdata/keywords.lst.md "keywords.lst"
46+
[Dtree.lst]: mdata/tree.lst.md "tree.lst"
47+
[Dfts-keywords.lst]: fulltextIndex.md "fts-keywords.lst"
48+
[configDesc]: helpCfg.md ""
49+
[Dkeywords-files.lst]: mdata/keywords-files.lst.md "keywords-files.lst"
50+
[newLang]: newLang.md ""
51+
[build]: publish.md ""
52+
[cusui]: customUI.md "UI customization"

0 commit comments

Comments
 (0)