Document Name ExtendedHelp.txt Author Carlo Hogeveen Version 0.3.1 3 September 2022 History v0.3 is a complete rewrite of v0.2 It lets go of the idea of merging Semware and user help files, and adds lots of new ideas. v0.3.1 corrects typos and grammer and improves wording. And now explicitly includes the potential follow-up project to be able to generate a text and HTML file from the new Help. Context As an end-user tool, TSE's built-in Help system provides an awesome user experience, but under the hood it is a very technical beast and requires hostile procedures to maintain it. Which is one of the reasons why Semware has hardly done so since TSE 4.4 was released in 2005, resulting in an outdated Help system content-wise. Post 2005 TSE versions come with a supplemental read.me file, that rudimentary lists changes since TSE 4.4. Adapting to this I am maintaining descriptions of known bugs and of badly, incompletely and undocumented features at https://ecarlo.nl/tse/files/TSE_Pro_Undocumented_Features.html Because as a web page it requires an internet connection and is not integrated with TSE, this provides an inferior user experience. Goal I want to - be able to add and edit my own documentation and notes in TSE's Help, - enable others to do the same, - provide us with a way to exchange these. Scope delimiters Given TSE's small user base and limits on my time and needs, it does not make sense to go crazy on features, but to keep things as simple as possible. So no redesign of TSE's Help, but reuse of existing features where possible. I have tentatively made these choices: - The Help's character encoding remains OEM. - Con: - The same old non-ANSI character set as the old Help. - Pros: - The ability to keep using TSE's drawing capabilities. - Retaining character compatibility with TSE's Console version. - The Help's text formatting remains fixed-format. So no line-wrapping, meaning too long lines are shown clipped-off. For an example see appendix F in the Help. My advice is to limit the Help to 80 displayed characters per line. TSE's own documentation crosses that limit in only 71 lines. - For links, topics, subtopics, bold, and italic text: - How they are displayed remains the same. - Their functionality remains the same. Design plan TSE's old Help is defined in the unreadable and hard-to-maintain files "tsehelp.hlp" and "compile.hlp". You might think of "tsehelp" and "compile" as Help domains. The old Help has "tsehelp" as its default domain, and hard-coded knowledge to implicitly access "compile" as a secondary domain. A macro can only explicitly access other domains. For example, a macro can access the topic "Add Compiler->Command" in the "compile.hlp" file with the case-insensitive TSE command Help('compile|Add Compiler->Command') Initially TSE's new Help is going to be derived from the merged content of "tsehelp.hlp" and "compile.hlp" into one file "tsehelp.help". From that point TSE's new Help will be defined in readable, editable help files, with names that adhere to one the formats ".help" "_.help" The default will be "tsehelp". Users can exchange their "_.help" files, which are installed by simply placing them in TSE's Help directory. Optionally they can be assigned a priority. Other domains than "tsehelp" will be directly accessible with the macro command: Help('|[topic or subtopic]') My thoughts on non-TSE domains: You will be able to create a user Help file for other domains than TSE. In my opinion this will not be a useful capability, because for non-TSE topics it does not make sense to me to use a Help solution that can only be maintained with TSE. This remains true even if I later add the capability to generate text and HTML files from it. However, given that - sometimes I am wrong, - some people have (mistakenly!) other viewpoints than me, or have other requirements, - some things are best (dis)proven in practice, - and it will be easy to do, my plan is to do implement domains anyway. ".help" Caveat: Users should not create or modify this file. For TSE's Help "tsehelp.help" will automatically be (re)created from "tsehelp.hlp" and "compile.hlp". The "tsehelp.help" file has 3 functions: - It will give Semware one way to maintain a readable and editable version of the help file instead of the two hard-to-maintain ones. However, this does carry the risk of the .help file being overwritten if one of the .hlp files accidentally becomes newer than the .help file. - It will be the initial default for the new Help. - It can function as a default and an example for user TSE help topics in user TSE help files. A ".help" file will not contain an Index. The new Help will dynamically create an overall domain Index based on topics and subtopics in all of a domain's Help files. "_.help" For any domain this file can start as an empty file to wich you add your own (version of) topics. For the two TSE domains you can start with empty topics or with each topic starting out as a copy of the TSE topic. It is your choice to redescribe a TSE topic completely or to only describe additional information for a topic. Username When executing the new Help for the first time you will be asked to enter a username for yourself. For example, my username will be "eCarlo". Semware could pick a username too as another way to start maintaining new Help for TSE. Help file usage and priority There will be configuration options to: - Enable/disable a Help file's usage. Default Help files are enabled. - Prioritize the usage of a domain's available Help files, determining which one will be shown first, next, etcetera. For TSE's Help "tsehelp.help" will default have the highest priority. TSE's new Help could for example consist of these files: tsehelp.help tsehelp_semware.help tsehelp_eCarlo.help tsehelp_Alice.help tsehelp_Bob.help The new Help files will be editable text files You should only edit Help files that end with "_.help". Other .help files could be overwritten from a newer .hlp file (e.g. from a TSE release), or when you get (a new version of) a .help file from another user. A downside of editing Help files directly is, that you will have to learn the syntax codes for bold and italic text and for all the types of addresses and links to them that TSE's Help is capable of. There will documentation for this, and the converted old Help will be a great source of examples. Help file syntax code Simplified, the old and new Help's syntax must be on-to-one compatible. This imposes these constraints: - The Help has no line-wrapping, so the syntax for a character type, an address and a link cannot span across lines. - The syntax must be unambiguous, so, for example, the abbreviation for a topic code cannot be , because that is also a TSE key definition that the Help describes. The least-bad syntax I came up with has these (dis)advantages: + It is unambiguous. + Its meaning is so clear that it is partially self-documenting. - It leads to even longer lines with syntax code. It is inevitable that lines with syntax code in a .help file are longer than these lines as shown by the Help. My choice exacerbates that. - The text of the codes can distract from the help text. + The latter can be mitigated with a help.syn syntax highlighting file. Examples of the syntax I came up with based on the existing Help for EditFile(): EditFile() INTEGER EditFile([STRING fn [STRING fn]... [, INTEGER flag]]) fn is an optional string expression specifying the file(s) to _DONT_PROMPT_ specifies that EditFile() should not display "Command-Line Options¯" in the chapter on "Starting the Editor" Fortunately the majority of Help lines do not have Help syntax, and only lines with link syntax become very long. Help file syntax checker This time-consuming operation will automatically take place each time the Help is invoke for a new or changed .help file. For each ".help" file the Help will maintain an up-to-date ".syntax_errors" file that lists the ".help" file's errors, warnings and notes. Errors will typically not prevent the Help from being shown. The new Help will have these new functions: An indicator whether the current topic occurs in another of the current domain's Help files. "switch to next help file" This needs to be a very prominent and accessible function, e.g. shown in the Help and accessible with a key. It selects the current topic in the Help file with the next higest priority in the current domain which contains that (sub)topic. "select a help file" Lets you select a help file from a list of all the current domain's help files, with an indication in which ones the current topic occurs. Potential future follow-up projects Make the new Help WYSIWYG-editable I may or may not implement this. Preliminary tests are ongoing, but for now they seem to indicate that this would not be too crazy to implement. Block marking and copy/paste seem doable too. Make invoking a Help domain extension-sensitive For example, if someone made a Help file for HTML, then invoking the Help while editing a .html or .htm file could invoke that HTML Help. Each Help domain could be configured to be invoked for a list of extensions. For not-configured extensions TSE's Help would remain the default. Again, maintaining non-TSE Help in TSE currently does not make sense to me, but I am keeping an open mind on this, especially since it would be easy to implement, and it has a certain fun factor. Actually displaying bold and and italic text In the olden days TSE had two printed manuals, the content of which was the same as TSE's built-in Help. The printed manuals could contain words and phrases, that were shown with actual bold and italic characters. In the Console version of TSE displaying bold and italic characters was and is impossible, and the GUI version did not exist back then. So in the tool bold and italic characters are currently shown with their respective configured color instead. The new Help could display bold and italic characters as bold and italic shaped without the need for colors. Only for the GUI version of TSE, of course. Generate a text and HTML version from the new Help This would be per domain, and generate one text or HTML file with the content of all the domain's enabled .help files.