Note: I am leaving the Chris WIP comment in the code until we decide on what URL it should be hosted at.

@jsherer markdown would be perfect. Then the URL can be changed to the github repo and it will display nicely in a web browser. If you want to add it to the docs directory just push a commit to this branch and then I'll update the URL to it when you get it done.

Tested both CI builds and my own builds on Windows and Linux, and the link to the User's Guide works fine on all.

Suggestion: Would it be good to have two ways to access it? Perhaps have a local copy, in case a station is not on-line (e.g., Field Day, DX-pedition, etc.), with a notice and link to check the on-line copy for latest updates.

Or... If the operator's workstation is on-line, access the on-line copy. If access to the on-line copy fails due to disconnection, access a locally-stored copy distributed with the software, and present a note to check the on-line copy for the latest updates.

73,
-Joe-
K0OG

I think so, Joe. Once I get this doc converted it’ll be easy to publish a pdf.
…
On Dec 18, 2025 at 9:02 AM -0500, Joe-K0OG @.>, wrote: Joe-K0OG left a comment (JS8Call-improved/JS8Call-improved#105) Tested both CI builds and my own builds on Windows and Linux, and the link to the User's Guide works fine on all. Suggestion: Would it be good to have two ways to access it? Perhaps have a local copy, in case a station is not on-line (e.g., Field Day, DX-pedition, etc.), with a notice and link to check the on-line copy for latest updates. 73, -Joe- K0OG — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: @.>

I added something to my original post, so you may not have seen it:

Or... If the operator's workstation is on-line, access the on-line copy. If access to the on-line copy fails due to disconnection, access a locally-stored copy distributed with the software, and present a note to check the on-line copy for the latest updates.

73,
-Joe-
K0OG

I think most people, even on field day, are going to have cellular and if it's hosted on the website as PDF it's pretty easy to download it in the field. That being said, it's very easy to bundle it as PDF in the MacOS disc image too, or even in the app bundle itself on MacOS. I decided to use the web method in the software menu because I see a lot of software that does that now, including SmartSDR for FlexRadio, as it reduces the payload for distributed software vs building it into the code. When the markdown version displays in your web browser, simply include a link in that to download the PDF version to save on your computer.

It is something that the software has never had before. The recent discussion on groups.io re: misunderstanding of how the > symbol works made me realize it would only take me 5 minutes to code it up. So why not make the Help menu a little more useful, as new users especially might want to refer to it and it provides them with an easy way to find it without increasing the payload for distributed software.

I think so, Joe. Once I get this doc converted it’ll be easy to publish a pdf.

Can also link to the PDF version if it's stored in the docs directory in the source tree, since almost all browsers offer an option to save a PDF to your local drive. If there's any scripts involved with converting from markdown to PDF, those script(s) can go in the tools directory.

Would it be simple to try the on-line version first, and if it fails, fall back to a locally-stored version distributed with JS8Call?

I think we need to consider that there may be significant operations where there is a grid-down situation, and JS8Call is the lifeline.

73,
-Joe-
K0OG

Would it be simple to try the on-line version first, and if it fails, fall back to a locally-stored version distributed with JS8Call?

On MacOS it is quite easy to include a PDF version of the User Guide in the distributable disc image. However, I have to make sure this makes it past Apple's notarization process. Bundled in the .app itself will (probably) result in it getting rejected. Bundling it in the .dmg should fly.

I tried using GitHub vs the website for hosting the User Guide that is displayed from the Help menu item. The website works by far the best - it is very fast, while GitHub is quite slow rendering PDF. From the website (at least with MacOS Safari) it uses the built-in PDF reader in the web browser, complete with an index. It has all the tools to download it and save a local copy, zoom in or out, display it in the native PDF reader, or print it. None of this worked from GitHub. GitHub is great at displaying markdown, not so much with PDF, and markdown is not a suitable format for download to a user's computer.

So this PR is fully functional for a production release as-is. I'm going to merge it to get this one out of the way.

Details of whether or not we're going to include a copy of the User Guide with distributed software, or how we're going to maintain the source code of the document is separate anyway. No sense to piling a bunch of stuff on a PR that was only intended to get the User Guide available from the Help menu fully functional for a 2.5.0 release.

So Jordan can continue converting the document to markdown. I extracted the source code of the document to .docx with Microsoft Office 2024 on Mac. Google's .docx exporter on Google Docs does not work, fails to render some of the images. So I now have the editable source to it with no Google markup too.

@jsherer @wmiler This was just an experiment to export markdown from Microsoft Office using the pandoc plugin
https://github.com/JS8Call-improved/JS8Call-improved/blob/experiment/user_guide/docs/JS8Call_User_Guide.md

It doesn't exactly format correctly and unlike .docx or .pdf which hosts the images with it, markdown does not support this and the images have to be hosted in a separate directory for it. So markdown may not be such a good idea for something like this. On GitHub even the .pdf is less than ideal and does not show any sort of index or page outline like it does on the website. Plus you have to keep asking for it to display more pages. So I honestly don't think it's worth it to have the PDF in the docs directory.
https://github.com/JS8Call-improved/JS8Call-improved/blob/experiment/user_guide/docs/JS8Call_User_Guide.pdf

A PDF can be exported from the .docx any time to update the website or include it in the Release assets. And with that in the docs directory it can be worked on and improved by anyone, any time. Unless Jordan can come up with a lot better markdown than I got from that export (which would take a lot of work to fix it up and get the images in it), I question the value of markdown for this too.

This works well on Windows and Linux, whether off line or on line. What I can't tell is whether it is trying on-line first, and if not found, then pull local. Is that the logic? That way, if on-line is available, the latest guide will be displayed.

Also, it would be nice, if on-line, and the local copy isn't the latest, download the latest copy to the local docs directory.

73,
-Joe-
K0OG

If it's off-line it's pulling it from your web browser cache which was one of the advantages of hosting it on the website vs GitHub. Adding a bunch of bloat to the code to attempt to download the latest copy is not practical because most end-users are not going to have the source tree on their computers. And that would mean versioning it somehow. It is totally optional as to whether or not the end-user wants to save it locally.

From this point forward it will always be included in the latest Release assets, which will also be the version linked from the website. It has never been a feature of the software before, so there's no sense to going overboard with it because it does not get changed very often.

Bundling it with the MacOS dmg does not work - tried it with a build on master this morning, sent it into Apple and it got rejected because it is not a valid copy of a license, and it is not linked to anything in the .app bundle. PDF's can contain malicious code, often hidden in scripts or embedded files that exploit vulnerabilities in PDF readers. Therefore Apple considers it a dead piece of bundled (possible) malware that is not a required library. I cancelled the submission to remove it from my submission history and put a "will not fix" flag on it.

@Chris-AC9KH Yeah, that's fine - not a big deal. As you say, if someone wants the latest copy, downloading is trivial.

Merry Christmas to all!

73,
-Joe-
K0OG