out of this topic : it's about hyperlinks problems in manual-pi

[filochard]

Hi Rick
I put an issue here because I don't know how to reach you else where

It's about manual_pi where I have created an issue :
leamas/manual_pi#5

I thought Alec was in charge of this but he just told me to address you

[rgleason]

filochard,

I am truing to find where these links are in the manual.

[filochard]

Hi Rick
in leamas/manual_pi#5 (comment)
I gave some patches showing where those links are to modify in the html files

If you download manual_pi tar.gz you may uncompress it and extract the doc directory
Then in this folder you may open index.html with Firefox : you get this (partial screenshot below) :
NB I didn't click on the navbar title to unfold it

Clicking on the hyperlinks below leads to nowhere
OpenCPN Quick start Guide
Basic User Manual
Quick Start Guide
Plugins (links)

NB these links are correct in the navbar

The on line Manual is OK
It's a problem when translating these links for an offline version

The only solution I have found is to modify the links in the source of manual_pi by applying patches before packaging it

[rgleason]

@jongough @bdbcat @leamas @filochard

I am sorry but I have no idea:

1. How to handle a diff. (I read a little, but I haven't a clue that that works with Antora)
2. Where to apply them. (no links seem to be available anwhere is the OpenCPN disapera.)
3. How to get to the Opencpn appropriate manual. (I did try)
4. Why this falls on me to do when you know antora/acsciidoc is not my favorite pass time.

I think filochard deserves some kind of a resolution to this because he spent the time to provide us with good links, but I am probably not the best man for this job.

[filochard]

Hi
Apparently Antora can't translate correctly all the online links into offline links...

The only solution that I have found was to apply some modifications inside the /doc/ folder and subfolders of manual_pi :
When building my own rpm of opencpn-manual-plugin rpm I used patches to correct some wrong address I gave them here :
leamas/manual_pi#5
They explain where to bring some corrections in the source
NB when this manual is updated from the last online manual with Antora, those corrections need to be rewritten (if needed)

[rgleason]

filochard I am not familiar with the interface or where the manual is that you are referrring to.
I assume it uses antora/asciidoctor, similar to the dev manual and the plugin manuals, but I have no knowledge other than that.

I have only seen screenshots, no active links to the page where edits can be made!!!!

Additionally I am still learning antora/asciidoc and can now upload screenshots and do minor edits, but I have no idea how to apply diffs and have forgotten how to find bad links (I think we used linkchecker off line on the documents, but not sure right now)

On top of that I am doing plugins right now.

[filochard]

Hi Rick

As I proposed it here leamas/manual_pi#5

The only temporary solution is to modify some lines in the /doc/ folder

The txt files belows explain which lines of which files are to be modified to get offline links that were not created by Antora

https://github.com/user-attachments/files/17350765/manual-basic-html.diff.txt
https://github.com/user-attachments/files/17534312/ocpn-dev-manual-index-html.txt
https://github.com/user-attachments/files/17534326/ocpn-dev-manual-intro-AboutThisManual-html.txt
https://github.com/user-attachments/files/17534327/ocpn-manual_basic-html.txt

That worked for me ;o)

[rgleason]

Ok in one of the txt files I see this html

manual_pi-0.0.3-orig/doc/user-manual/opencpn/manual_basic.html

but I don't know or have the link to the documents.
Where ARE they located? One step at a time please.

[filochard]

Hi Rick

My diff files indicates where I applied modifications inside manual_pi-0.0.3.tar.gz after having unarchived it
as an example for
https://github.com/user-attachments/files/17350765/manual-basic-html.diff.txt

1. look https://github.com/leamas/manual_pi/ tab code
2. inside /doc/user-manual/opencpn/ there's a file : manual-basic.html

this file needs some corrections

the first line of the diff file indicates to apply these corrections for manual_pi-0.03/doc/user-manual/opencpn/manual-basic.html

then the diff indicates where to apply these corrections

@@ -527,7 +527,7 @@ indicates that there's something to do between lines 527 and 533
,7 and ,7 are equals that indicates that you are not adding a line or suppressing a line but simply modifying one line
the line to modify is preceded by 3 lines untouched and followed by 3 lines untouched
so line 530 needs to be modified
you have to replace this
<p><strong><a href="./quick_start_guide.html#_quick_start_guide">OpenCPN that means nothing offline
by this
<p><strong><a href="./manual_basic/quick_start_guide.html">OpenCPN``

The principle is the same for all the other lines in this diff file
and the same for the other diff files

Hope this is clearer now
Best Regards
filochard

[rgleason]

What is look https://github.com/leamas/manual_pi/ tab code?

I don't follow this at all.

I can get to https://github.com/leamas/manual_pi/blob/main/doc/user-manual/opencpn/manual_basic.html
but where do I edit it? There should be a github page that allows me to edit using asciidoc/antora, ...I thought?

Or do you want me to do something else? This is not my repository. This is Mike Rossiters and Alex Leamas. I cannot directly edit those. I could fork them, make changes and push a Pull Request.

[filochard]

if this not a repository where you can edit you probably need to create a fork
I'm gonna try to create a fork myself and try to modify the files to give you the recipe

[filochard]

Ok
It's not so difficult
I created a fork
https://github.com/filochard/manual_pi
then I have edited the file
/doc/user-manual/opencpn/manual-basic.html
with the modifications I proposed to correct the offline paths in lines 525 537 559 574
then commit the change
https://github.com/filochard/manual_pi/commits/main/

That's done

you will see that the commit has the same content as the diff.txt

If you wish, I may add the other corrections in my fork for the href in other files where they are wrong
so that you understand what to do by reading my commits

You might also test the content of the doc folder unarchived from the tar.gz for which I will give you a link

[filochard]

I have modified the doc folder in manual_pi on my fork
you may download it here (it's a huge file)
https://github.com/filochard/manual_pi/archive/ead5055e0350c27c77b48c40c21c9eaf0d8d8c56/manual_pi-ead5055e0350c27c77b48c40c21c9eaf0d8d8c56.tar.gz
Just unarchive the doc folder and then navigate with the index.html file : the links are corrected !

[rgleason]

I see your commits. That is great. I think you are using the newer documentation setup in github which is called Asciidoc/Antora. You clone the fork and then there is an "Edit" button (or it is the reverse) you click the Edit button and the repository is cloned to your remote, and any changes are saved to your remote version.

Then I don't remember if you need to make a PR back to the original repo to have the changes reviewed and accepted and brought into the documentation.

Ok so the repo that has this Manual is https://github.com/leamas/manual_pi but it is an "off-line manual"
Iif it were to be put online and available the URL would be
https://leamas.github.io/manual_pi/docs/index.html and that would be accessible and have an "Edit" button to actually edit the document. We DO NOT have that setup now.

I now understand, what you are doing. You simply forked Leamas/manual_pi and have changed the docs to fix the bad links. Therefore to get the changes entered into Leamas repo you will need to make a PR back to his remore repository.

This is your repo https://github.com/filochard/manual_pi

Now you should make a Pull Request from the upper level. Here is one from your repo to leamas.

leamas/manual_pi@main...filochard:manual_pi:main

Thanks for taking this on. It was totally unclear to me how to fix this, but I think we have it figured out now. Congratulations.

[filochard]

It's more home-made
I have downloaded in october manual_pi-0.0.3.tar.gz
I have unarchived the doc folder and then tried to navigate with Firefox from the first index.html in its tree
I discovered then that some links didn't work offline
That means that Antora can't translate correctly all the links

With Bluefish and a little knowledge of html rules I have corrected the wrong paths (bad href in some html files) inside a copy of this original /doc/ folder
And then I created diff files with Kompare for each .html file that I had modified (comparing them in the original /doc/ and in the modified /doc/)

Now
I have created a fork of alec leamas' repo
and inside my fork I have manually edited (with the edit button) the wrong html files replacing the bad lines by their correction
and then commited these editions

It's a work in progress : there are other wrong links but I didn't continue these corrections that didn't seem to arouse a great interest

If Alec and Mike are OK I will request a pull from my fork

[filochard]

Hi Rick
I am ready for pull requests (I'm familiar with this that I often do this for an other program https://github.com/thothix/guayadeque)

I asked Alec and Mike whether they are OK
leamas/manual_pi#7