search

opencpn-manuals / plugins

Part of opencpn-manuals/main, not maintained as a separate manual
4 stars 3 forks source link

Many Broken Links - rgleason's #8

Closed rgleason closed 3 years ago

rgleason commented 3 years ago

It looks to me like many errors are in sean's plugin docs or ones I handle.

weather_routing:ROOT:weather_routing.adoc Line: 243 statusbar:ROOT:statusbar.adoc Line: 252 watchdog:ROOT:watchdog.adoc Line: 204 opencpn-master-plugins:squiddio:squiddio.adoc Line: 171 tactics:ROOT:tactics.adoc Line: 216 vdr:ROOT:vdr.adoc Line: 159 find-it:ROOT:find-it.adoc Line: 156 rotationctrl:ROOT:rotationctrl.adoc Line: 132 projections:ROOT:projections.adoc Line: 141 route_great_circle:ROOT:route_great_circle.adoc Line: 180 celestial_navigation:ROOT:celestial_navigation.adoc Line: 177 UPDATED - DONE dash-t:ROOT:dash-t.adoc Line: 150 rtlsdr:ROOT:rtlsdr.adoc Line: 102 pypilot:ROOT:pypilot.adoc Line: 264 weatherfax:ROOT:weatherfax.adoc Line: 234 climatology:ROOT:climatology.adoc Line: 240 polar:ROOT:polar.adoc Line: 222 chartscale:ROOT:chartscale.adoc Line: 135 ais_radar_display:ROOT:ais_radar_display.adoc Line: 96 logbook:ROOT:logbook.adoc Line: 153 sweep_plot:ROOT:sweep_plot.adoc Line: 219

leamas commented 3 years ago

OK, just do it...

leamas commented 3 years ago

Sorry, that was for Rick, I suppose... too quick again :(

leamas commented 3 years ago

@rgleason : You have a PR.

rgleason commented 3 years ago

Merged. The .gitignore with docs and public is under manual Thanks.

I have several yml under manual site.yml bldloc.yml playbook.yml

Should I delete some of these leaving site.yml? Should they be pushed up to remote or be in gitignore?

leamas commented 3 years ago

I think we all recognize the site.yml file. In the end it's up to you but personally I would remove the others and make sure site.yml works. It should certainly not be in .gitignore, it's useful for anyone cloning this.

rgleason commented 3 years ago

Thanks, will follow your suggestions.

leamas commented 3 years ago

I'm building your latest version now You can follow the results at https://github.com/opencpn-manuals/plugins/actions

leamas commented 3 years ago

results are at https://github.com/opencpn-manuals/plugins/runs/3376614152. If you search for watchdog you will find 5-10 link errors, all in one place

rgleason commented 3 years ago

Made a bunch of changes to fix the links. There are several that are very puzzling. Also removed a bunch of unused image to the "old" folder. Sorry about this but, what grep should I run to get a list of unused images?

rgleason commented 3 years ago

Antora docs Site.yml url should be to the repository

  sources:
    - url: ../
      start_path: manual/watchdog/
rgleason commented 3 years ago

There are a considerable number of links to other plugins. How do we do these lins? For weather_routing_pi we need links to the new verssion of 


** link:../sailing/polar.html[Polar_pi]
** link:../logs/vdr.html[VDR_pi]
leamas commented 3 years ago

First, a link to another manual is a dependency. As usual, this mean that the polar and vdr manuals must be in shape before you can link to them.

Besides this, a manual is a component in Antora parlance. To link to example vdr you need to look at antora.yml for that component. Here you will find the name of the component (probably 'vdr') and possibly a start_page.

If there is a start_page key the link is xref:_startpage for example (not checked!) xref:vdr::vdr.adoc

If there is no start_page you link to the default page using something like xref:vdr::index.adoc

This will work fine when building the complete manual. For your own site.yml to work you will need to include the vdr and/or polar sources in site.yml. I could help you with that if you cannot deduce how from the Antora docs. Here, use the direct url rather than the sources system used in the overall plugins project.

leamas commented 3 years ago

BTW: Please update #11 so all can see the status of plugins.

Looking at the logs at https://github.com/opencpn-manuals/plugins/actions/runs/1151522573 watchdog looks fine. So please add a DONE to it in #11 (jjust edit the one and only comment) and mark next plugin you work with UNDER WAY or so, look for other ones.

leamas commented 3 years ago

I have changed your "will do" to UNDER WAY in #11 so we all have the same notation.

As for d_tactcs_pi you repo does not contain any manual. I suggest that you use the manual i Mike's fork. Talk to him about it so you get it either in your own fork or in a fork here under opencpn-manuals.

I have added celestial_nav to plugins. Ít is currently building. You should see plenty of issues to handle for it.

Rasbats commented 3 years ago

I did a lot of editing for celestial_nav. I will PR Rick with those changes.

leamas commented 3 years ago

Please talk about dashboard_tactics_pi as well.

@rgleason: the following steps will pick up the manual directory from oplaydo (a. k. a. Rasbats) to your own repo. In your own clone of dashboard_tactics_pi do:

$ git remote add oplaydo https://github.com/oplaydo/dashboard_tactics_pi.git
$ git remote update oplaydo
$ git checkout oplaydo/master manual
$ git commit -m "Add manual directory from oplaydo - https://github.com/oplaydo/dashboard_tactics_pi.git"

The advantage of this approach, besides that it's simple, is that you will keep the git history and file permissions which are otherwise often lost in Windows.

rgleason commented 3 years ago

"I did a lot of editing for celestial_nav. I will PR Rick with those changes."

Thanks Mike, that is great, there are a lot of attachments, references and links to this one. I spent some special effort on this documentation so naturally I have an interest in preserving it and updating it to be current.

I see Alec's note too. I will try to get to fixing bad links shortly.

rgleason commented 3 years ago

Alec, I have cloned and forked petri's repository. Then I have Updated CI and Cmake files and released version 2.1 using that for a version that works with current Opencpn 5. Petri's current Dashboard_Tactics is for advanced users and it offers all kinds of features. That cannot be used until we update to more current wxWidgets.

I am not certain, but it does not look like oplaydo has changed any of Petri's documentation. https://github.com/oplaydo/dashboard_tactics_pi It still has the "docs" folder only for documentation not touched for 2 years.

So I don't think I need to do this. Thanks. What I do need to do is modify his documentation to use asciidoc/antora because it is using ReadtheDocs.

Please talk about dashboard_tactics_pi as well.

@rgleason: the following steps will pick up the manual directory from oplaydo (a. k. a. Rasbats) to your own repo. In your own clone of dashboard_tactics_pi do:

$ git remote add oplaydo https://github.com/oplaydo/dashboard_tactics_pi.git
$ git remote update oplaydo
$ git checkout oplaydo/master manual
$ git commit -m "Add manual directory from oplaydo - https://github.com/oplaydo/dashboard_tactics_pi.git"

The advantage of this approach, besides that it's simple, is that you will keep the git history and file permissions which are otherwise often lost in Windows.
rgleason commented 3 years ago

@Rasbats Re: Celestial_Nav PR Thanks! Before I merge it. Is there an html io version somewhere that I can see? There are many links I know.

In looking at this page from the PR https://github.com/oplaydo/celestial_navigation_pi/commit/67c5ee06dfba9e78201f4287e5d1a6b762936264#diff-ccc8c1d223da3a9ae3d1428ff31199b0ac44b8e878d652859590e059e09b3c26

It looks pretty good, but we are loosing some of the titles etc. I wanted to inspect further before merging.

Also I see that it is 16 changed files with 122 additons and 146 deletions so I wonder what is being deleted. I also notice that .jpg endings are being changed to jpeg. Why is this happening?

rgleason commented 3 years ago

Also dashboard_tactics has a smaller manual on the wiki which may be better to use! https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:plugins:logs:dash-t

Rasbats commented 3 years ago

@rgleason : jpeg was needed as the images are .jpeg.

How about Firefox and open celestial_navigation.adoc. You can compare with dokuwiki. Have VS Code available and make edits as you go. Probably most are in [] behind a link.

rgleason commented 3 years ago

Good idea, will try that.

rgleason commented 3 years ago

Hey guys, I appreciate all the PR's but I am finding some problems with them and have spent the afternoon trying to fix celestial_navigation for example.

  1. The images have been messed with and are illegible and much much smaller than originally. I have already optimized them. Re optimizing them into unacceptable illegible mush.
  2. The text for links has been dropped in many instances.
  3. The links themselves are not working in a number of cases.
  4. The asciidoc/antora CSS titles are inadequate the Titles below "===" are not bold enough or big enough and I often want to go to at least "=====" or ====== (This is a big pain in the butt. Asciidoc as set up does not correspond to the dokuwiki CSS at all. As a result plugin documents are not easily readable.

At this point I don't know if I am going to try to merge and fix or just do my own. Sorry.

leamas commented 3 years ago

Please note that this bug is about getting the links in shape so they pass the validation steps.

That said, I think we have viable strategy here for "your" plugins.

leamas commented 3 years ago

The links themselves are not working in a number of cases

Here are really three cases.

leamas commented 3 years ago

Titles below "===" are not bold enough or big enough and I often want to go to at least "=====" or ======

This is probably to make things more complicated than they should be. A plugin manual is at most a few pages, and going 5 - 6 levels down should not be required and actually makes it harder to read. Note that the Antora navigation gets confused if the top level in a page isn't a plain '='.

There are also other mechanisms to use like term definitions etc.

rgleason commented 3 years ago

That was one of my questions. Why is the almost always "==" ? Can I start with "=" that would add one useable level. The lower levels are simple ineffective as titles and should be changed in the CSS.

Note that the Antora navigation gets confused if the top level in a page isn't a plain '=' Also why change the images!!!! Keep them the same. It will be a pain to go find them.

Also why stripp out the link titles. I willl have to add them back taking more time.

I am finding the end result of asciidoc formatting much less satisfying than Dokuwiki's CSS For example the spacing after bullets is too wide. There are other annoying issues.

rgleason commented 3 years ago

One final thing about images. In dokuwiki you can click on the images to bring them to full size if needed. asciidoc apparently does not support this.

This process is not seamless, it is a PITA and takes more time than Dokuwiki

rgleason commented 3 years ago

"..initial (an initial?) move from dokuwiki to Asciidoc/Antora. This is completed."

Did this move strip out all link titles and mangle all images?

leamas commented 3 years ago

These things is basically after Mike's initial move. I suppose he just didn't find the time to fix those things, what he did is an initial work which provides a starting point. As an example, he probably didn't notice the missing images (in a case or two I have fixed them as well). translation/conversion problem bugs, so to speak.

Just change the levels so they start at '=', no problem

Did this move strip out all link titles and mangle all images?

No idea. And Mike is, as you know, sailing.

In dokuwiki you can click on the images to bring them to full size if needed. asciidoc apparently does not support this.

See https://powerman.name/doc/asciidoc, look for Macros: links, images & include

Rasbats commented 3 years ago

https://rasbats.github.io/opencpn-plugins-manual/celestial_navigation/0.1/celestial_nav internet linkigation.html

Before my latest edits. ctrl-left click to test an internet link.

leamas commented 3 years ago

The links themselves are not working in a number of cases.

Perhaps you have problems with intra-page links and links to other plugins. I have submitted https://github.com/rgleason/weather_routing_pi/pull/80 which have plenty of examples of both.

In weather_routing, there were a lot of intra-page links like link:weather_routing_pi.html#settings These should be converted to xref's like xref:#_settings . Note the leading underscore. Sometimes it's necessary to check the link using the browser.

A link to anothe plugin like climatology might have been something like link:../../climatology/climatology.html . These should be converted to an xref like xref:climatology::index.adoc. Here:

These references to other plugins are not usable until it's build together with other plugins in opecpn-manuals/plugins. They will typically fail in a local build.

rgleason commented 3 years ago

For a smaller thumbnail that is linked to the larger (double-click) image:

image::four-circles-of-position.png["4 Circles of Position",width=550,link="_images/four-circles-of-position.png"]

leamas commented 3 years ago

Right, nice work!

Here is also https://gitlab.com/antora/antora/-/issues/330 and https://gitlab.com/antora/antora/-/issues/603.

I wonder if using {imagesdir} is better than _images. No answer... EDIT: https://gitlab.com/antora/antora/-/issues/276

We need a place for this, something like Tips & Tricks in the Authoring section

rgleason commented 3 years ago

A plugin manual is at most a few pages, and going 5 - 6 levels using "=" for the title only and flattening the structure I was able to get it to look ok, but cel-nav is a very long single page.

Almost done with cel nav after 2 days. Just have the thumbnail links to do (will try {imagedir} and fixing images left. Then will commit and push. Then I will try to change the structure to shorten the directories.

rgleason commented 3 years ago

https://gitlab.com/antora/antora/-/issues/276

But then the solution is to call this, the admonition to not use {imagesdir} explicitly, out in the docs.

But this has always been the case. Asciidoctor has always prepended the value of the imagesdir attribute, so referencing it explicitly in the target was never correct. And this is documented in the user manual. https://asciidoctor.org/docs/user-manual/#setting-the-location-of-images (Though I can see now that the statement needs to be even clearer).

https://gitlab.com/antora/antora/-/issues/276#note_97481935

In that case, I strongly advise using a different attribute name as the imagesdir attribute has special meaning. This is what I'm objecting to: image::{imagesdir}/filename.ext[alt text] but not necessarily image::{imageprefix}/filename.ext[alt text]

leamas commented 3 years ago

yes, those were my links...

leamas commented 3 years ago

which plugin are you working on?

rgleason commented 3 years ago

cel-nav

leamas commented 3 years ago

i. e., celestial-navigation ?

rgleason commented 3 years ago

Yes, will commit and push soon. Have not found a way that works, to float images left and prevent text from floating right. For just a single image. https://docs.asciidoctor.org/asciidoc/latest/macros/image-position/

[.float-group]
--
[.left]
.Image A
image::a.png[A,240,180]
--

Text below images.
leamas commented 3 years ago

OK. Just let me know when you are done so we can change the pointer so we use your repo instead of the fork in opencpn-manuals.

rgleason commented 3 years ago

Alec, ok it is pushed to https://github.com/rgleason/celestial_navigation_pi/tree/master/manual

There is one problem I know of, which is that when I double click on an image to go to full screen, when I go back, the Browser always goes back to the bottom of the html page at 'Kubek’s Sights to test Accuracy of the Plugin"

Would you perhaps know why?

rgleason commented 3 years ago

Let me know if there are any bad links please. Thanks.

leamas commented 3 years ago

hm.. First try with linkchecker gives:

URL        `_images/Sight-2-date-time-certainty-shift.png'
Parent URL file:///home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/celestial_navigation.html, line 655, col 1
Real URL   file:///home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/_images/Sight-2-date-time-certainty-shift.png
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/_images/Sight-2-date-time-certainty-shift.png'>

URL        `_attachments/New_Computational_Methods_for_Solving_Problems_of_Vessel_Position.pdf'
Name       `New Computational Methods for Solving Problems of Vessel Position.pdf - 22 pages (pdf 305kb)'
Parent URL file:///home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/celestial_navigation.html, line 1280, col 4
Real URL   file:///home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/_attachments/New_Computational_Methods_for_Solving_Problems_of_Vessel_Position.pdf
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/_attachments/New_Computational_Methods_for_Solving_Problems_of_Vessel_Position.pdf'>

URL        `_attachments/cel_nav_determining_the_Position_and_Motion_of_a_Vessel_fr.pdf'
Name       `Determine Position & Motion of a Vessel'
Parent URL file:///home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/celestial_navigation.html, line 1391, col 4
Real URL   file:///home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/_attachments/cel_nav_determining_the_Position_and_Motion_of_a_Vessel_fr.pdf
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/mk/src/opencpn-manuals/plugins/docs/celestial_navigation/0.1/_attachments/cel_nav_determining_the_Position_and_Motion_of_a_Vessel_fr.pdf'>
leamas commented 3 years ago

I'll start the slooow checklink process while you look into above...

leamas commented 3 years ago

Attaching results from slow checklink: checklink.log.gz

EDIT: Never mind about those blocked by robots.txt, we'll handle it in the script.

You need to be able to run these test yourself, like this:

The last push will start a build which can be followed at https://github.com/opencpn-manuals/plugins, under the Actions button. Since you push to the build branch this is only for testing purposes. To actually commit to plugins/main is another issue

rgleason commented 3 years ago

Watchdog external links to dokuwiki example: https://github.com/rgleason/watchdog_pi/pull/29

https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:plugins:install_and_enable[Plugin Download, Install and Enable].

Replacement
xref:opencpn-plugins:misc:plugin-install.adoc[Plugin Download, Install and Enable].

Thanks Alec, also it is good you now have the install_and_enable adoc included.

leamas commented 3 years ago

https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/misc/plugin-install.html

EDIT: also in place: the terminology page: https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/misc/terminology.html

rgleason commented 3 years ago

Celestial_Navigation_pi moved modules up one dir, fix index.adoc, site.yml, antora.yml commiited and pushed to remote. Hope it is good!

The plugin-install.adoc looks excellent as does terminology. I made a few little typo edits on plugin-install.