Documentation questions

  1. I’m unsure about the difference between readme.md and readme.htm (aside from the different file formats). I think the htm is shown when the user installs the package – if so, what is the function of the md file?
  2. I have documentation in PDF format. It is important for users to have access to this because putting all the details about the keyboard in the welcome.htm would make it too long and complicated. I know I can create a Start Menu item in Windows to provide access to the PDF; is there any other way? What about Mac (or Linux) users?
  3. I’ve put all the changes to my keyboard in history.md and included it in the package. Is there any way for users to access this file? Not something people will do often, but I’d still like to know.

Good questions!

  1. README.md is intended for people browsing the source of the keyboard on GitHub. The README.md file displays automatically when viewing the project folder. Most keyboard authors are not putting a lot of detail into it, but it is an opportunity to give technical background on the keyboard for other keyboard authors, as opposed to the readme.htm file which is intended to introduce the keyboard for end users. See for example keyboards/release/gff/gff_ethiopic at master · keymanapp/keyboards · GitHub

  2. If you include a .pdf, add a link to it in welcome.htm, because:

    • the vast majority of Windows users never discover new entries in the Start Menu, so the links are not very useful
    • we only support Start Menu links on Windows
    • welcome.htm is intended to be the home page for your documentation on all platforms.
  3. In theory you could add the HISTORY.md file to your .kps and link to it in your welcome.htm. Currently, we don’t do much with it but we are planning to support Markdown format in .kps in the future (see #9477)

We recommend organizing the keyboard files according to this file layout
https://help.keyman.com/developer/current-version/reference/file-layout

The page also has brief descriptions about what each file is for.

For keyboards hosted on keyman.com, a PHP version of the welcome.htm is available on the help site
Keyman Support | Type to the world in your language

Thanks again, Marc.

Your answer addresses my question #1 very well.

Re #2: I suspected that the Start menu wouldn’t be very useful. How do you link to a PDF in welcome.htm? I looked this up in the commonmark.org reference, and it shows only using a web address in parentheses after [Link]. I don’t have a website to host the PDF on and was hoping to simply include it in the package.

#3: I think I will put the change log at the end of the documentation (and leave it in history.md); probably remove it from the documentation if the history file ever becomes more useful.

Thanks, darcy. It’s good to know about the PHP file. I have referred many times to the file layout page while getting my revised keyboard to work (which it mostly does now).

The “readme.htm” file is packaged with the keyboard and is displayed on the point of installation. It should contain just enough information to enable the user to verify that the keyboard is suitable.

The “welcome.htm” and any files it references are also packaged with the keyboard. The “welcome.htm” file is displayed at the conclusion of the installation and any time that the user asks for help. It provides the help information that is included with the keyboard.

Here’s an example of a keyboard whose “welcome.htm” file references a PDF file:

The “balochi_scientific” keyboard (keyboards/release/b/balochi_scientific at master · keymanapp/keyboards · GitHub) includes this line in the “welcome.htm” file:

<p>See <a href="balochi_scientific.pdf">this document</a> for all the key combinations.</p>

The “balochi_scientific.pdf” file is included in the package (the list of files in the .kps file) so that welcome.htm can reference it.

The PHP help file is not mentioned in the list Darcy cited. It would be named “sample.php” and be located in a folder named “help”, which would be located in the source folder. It essentially repeats the help information that is found in the welcome.htm file. It is not packaged with the keyboard, but instead provides the online help for the keyboard when it is included in the Keyman keyboards repository. We’re aware that this results in some unfortunate duplication and hope to (someday!) have a unified source for the help files. (For example, for the balochi_scientific keyboard, the PDF file is duplicated in the “help” folder so that the PHP help file can reference it.)

Write again if you still have questions!

To add a link to a local .pdf file to a .htm file, you add an <a> tag: <a href="file.pdf">PDF</a>. Then just make sure you have added the .pdf to the package. (For .htm, don’t use Markdown).

Thanks to you and Marc – I now have documentation link working properly in welcome.htm. :smiley: Now we’ll see about the php file.