search

opencpn-manuals / plugins

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

Simplify Navigation #72

Closed rgleason closed 3 years ago

rgleason commented 3 years ago

There is something funny about the navigation, I get caught in Beta Plugin Land and it is hard to get out. Also there seems to be a Beta nav.adoc that is the same as the header plugiin adoc.

I would think that conceptually we have all plugins documentation in one barrel and dip in there for the Main Plugins and the Beta Plugns, that would make it easier to move a plugin into Main and might make navigation easier.

I find there might be some room to simplify the folder and layers a bit, but I hesitate to say how as I know you guys have been working with this a lot. I am just wondering if some changes could be made to make things easier in the long run.

rgleason commented 3 years ago

BTW I'm pretty much finished with editing titles and indexes etc. and will likely just be editing individual plugin manuals for awhile. Also I've got to get all of the TP frontend PI updated, its pretty bad right now.

Thanks for putting up with me, I've learned a lot had have a crib sheet for going forward.

leamas commented 3 years ago

BTW I'm pretty much finished with editing titles and indexes [snip]

This is off-topic, right?

leamas commented 3 years ago

here is something funny about the navigation, I get caught in Beta Plugin Land and it is hard to get out.

The only thing I see is that when actually looking at a plugin (main or beta), the left navigation pane is replaced with a list of plugins, ordered and complete. This is because the plugin manuals does not include or depend on openpcn-manuals/plugins, which is the way it should be for other reasons. This is not that bad, since:

rgleason commented 3 years ago

Ok, I think may be there should be a Main Plugin link at the top of the Beta page and visa versa.

You definitely get caught in Beta Land. Try it.

rgleason commented 3 years ago

Also I think this structure can be simplified. There are two identical pages basically, which are not necessary. It has happened because Beta and Main were separate for a long time and they have now been connected. There is some re-organizing needed.

leamas commented 3 years ago

You definitely get caught in Beta Land. Try it.

Just did. Not caught, "Back" button works fine.

There is some re-organizing needed.

Perhaps, but then we need a more concrete proposal. And a better problem description, I don't see any difference when looking at the beta plugins vs the main ones.

Rasbats commented 3 years ago

Also I think this structure can be simplified. @leamas @rgleason : I am going to try rather a large reorganisation, removing partials. If this works this would simplify the installation of new plugins and make the whole structure more transparent. It works on local build ... standby.

Rasbats commented 3 years ago

Mistake ... local build was from before the reorganisation. Trying another build.

Rasbats commented 3 years ago

Completely screws up the navigation on the left of the page. Still playing.

Rasbats commented 3 years ago

As I see it - partials is a way of producing an index. We need an index and this involves adding the xref for the new plugin to the index (partials files nav-plugins.adoc, nav-beta-plugins.adoc). If you think of nav as the index this may help. partials has to stay!

Rasbats commented 3 years ago

Link made on the beta page to return to main plugins: commit c9bbd2e0704d8058c2df3a0af94c267e741755d5

leamas commented 3 years ago

[snip] partials has to stay!

I havn't really shared your mixed feelings about partials from the beginning. That said, I concur with your conclusion.

rgleason commented 3 years ago

I may play with this a little if I can find some time. I should understand it anyway.

rgleason commented 3 years ago

Are these pages supposed to be exact duplicates?

Main & Beta Plugins + Suppl Hrdwr & Softwr, Authoring Links ../manual/master-plugins/modules/ROOT/nav.adoc <--

Short Main & Beta Plugins ../manual/master-plugins/modules/ROOT/pages/index.adoc <--- Duplicate Could bee the same as top link ../manual/beta-plugins/modules/ROOT/pages/indexs.adoc <--- Duplicate Duplicate Could bee the same as top link

Main Plugins Listing .../manual/master-plugins/modules/ROOT/pages/plugins.adoc <--Duplicate ,../manual/master-plugins/modules/ROOT/partials/nav-plugins.adoc <--Duplicate

Beta Plugins Listing ../manual/beta-plugins/modules/ROOT/nav.adoc <--References just xref:index..adoc[Home} and xref:beta-plugins.adoc ../manual/beta-plugins/modules/ROOT/pages/beta-plugins.adoc <--- Duplicate ../manual/master-plugins/modules/ROOT/partials/nav-beta-plugins.adoc <---Duplicate

rgleason commented 3 years ago

It on my plate

Rasbats commented 3 years ago

@rgleason : Bit off-topic but ... https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/advanced/advanced.html

leamas commented 3 years ago

I could do some nit-picking here, hope you don't mind. Before doing that: great text!

Some nit-picks:

rgleason commented 3 years ago

Thanks

Well you've done a lot of work there. Doubt it will ever change, but I think current is a bit contorted due to the way the process went and searching for how to do it, not anyone's fault at all!!!

  1. The sources have the manuals, totally separate and all plugins are together under it.
  2. The navigation docs can work as you need, keeping it really simple, referencing the sources.
  3. The problem (Actually it is Not a problem, see below) is if the nav structure is simplified and changed all the links to all distributed plugins has to change! That is a big job. (Maybe good regex changes are possible? I don't know this)
  4. So when and if this gets done, we would want to be certain about the structure.
  5. I don't have time to devote really, but maybe move beta-plugins into the main plugins somewhere appropriate.
  6. Where are the links to this https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/advanced/advanced.html? Never saw it.

└─── plugins <---- Rename and abandon the beta-plugin navigation branch │ │ antora.yml │ │ │ └───modules │ ├───advanced <---Has content in it │ ├───authoring <---Has content in it │ ├───chart_downloader_tab <---Has content │ ├───dashboard <---Has content │ ├───grib_weather <---Has content │ ├───misc <---Has content │ │ │ ├───ROOT <---Where all navigation for External Plugins │ │ │ nav.adoc <--Links to plugins.adoc and beta-plugins.adoc and links Internal, Authoring, etc. │ │ │ │ │ ├───pages <-- The only content in this section is the "managed-pi.png !!! │ │ │ index.adoc <-- don't know if this should be plugins-main or not. │ │ │ plugins-main.adoc <-- Links to sources (main plugins) │ │ │ plugins-beta.adoc <---Links to sources (beta plugins) -- Add? │ │ │ plugins-all.adoc <---Links to sources (beta plugins) -- Add? │ │ │ │ │ └───partials <--- Why is this needed? I don't think it is needed. │ ├───sat2chart <---Has content │ └───wmm <---Has content

I believe this would work fine, and it is much simpler, but it is a lot of work restructuring it.

rgleason commented 3 years ago

I am starting to realize that the links in most of the plugins will not be affected at all!!! The links within the plugins generally all go to to ones with some real content!!!

│ ├───advanced <---Has content in it │ ├───authoring <---Has content in it │ ├───chart_downloader_tab <---Has content │ ├───dashboard <---Has content │ ├───grib_weather <---Has content │ ├───misc <---Has content │ ├───sat2chart <---Has content │ └───wmm <---Has content

So there would NOT be any rework of links in the plugins (Isn't this right?)

rgleason commented 3 years ago

So you could make a new branch, make these changes, test it and then rebase it (almost said merge (:-)) .

Rasbats commented 3 years ago

@rgleason : There are other priorities than rebuilding the structure.

Rasbats commented 3 years ago

@leamas :

using italics while commands are using monospace.

Could you give some examples of asciidoc ?

leamas commented 3 years ago

Didn't find one one the spot, although I know for sure I have done plenty of them. Attaching a quick translation of a Markdown thing I have at hand.

LINUX_DEVICES.adoc.gz

EDIT: Here is a single example of an in-line command in monospace: search for stty.

leamas commented 3 years ago

@Rasbats : BTW, you could compare your description with the description in the top of the source-state.sh script. The latter is correct, and you have missed some things, notably that it's possible to update or restore a single plugin.

rgleason commented 3 years ago
  • @rgleason : There are other priorities than rebuilding the structure.

I don't disagree, but I believe it can and should be done later without much trouble.

rgleason commented 3 years ago

This has been done. It is in the Build Branch. It is quite simple along the lines shown above with some differences. Look at the structure please to redraw the diagram.

BUILD Branch: https://github.com/opencpn-manuals/plugins/commits/build "Simplify Navigation" https://github.com/opencpn-manuals/plugins/commit/230902a0fa79d856434d05a0b93ba47b069a566b

See this html result https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/index.html

Please take a look and then I will push to Main. Tomorrow Morning

Rasbats commented 3 years ago

@rgleason : Does this build locally for you if you remove partials? https://github.com/opencpn-manuals/plugins/blob/build/manual/plugins/modules/ROOT/pages/index.adoc This page shows 'Authoring' has no link. Other pages show no link. Suggest another look.

leamas commented 3 years ago

Does this build locally for you if you remove partials?

Partials is the underpinnings for the left pane navigation tree. Why is it so important to get rid of it?

This page shows 'Authoring' has no link. Other pages show no link.

That's just github rendering asciidoc files, and github does not understand the Antora extended link syntax. OTOH, the real stuff at https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/index.html is linked correctly, so this is a red herring

That said I don't actually see any difference in the user navigation, just a cleaned up directory structure. Which is good, but am I missing something?

leamas commented 3 years ago

The radical approach would be to remove all links in https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/index.html. That would leave us with descriptions of what's available in the different sections and the left pane navigation tree. Simple and clean from a user perspective.

Rasbats commented 3 years ago

Partials is the underpinnings for the left pane navigation tree. Why is it so important to get rid of it?

Rick was concerned about the work needed to add a new manual and the number of places to edit. I thought this was the impetus for his simplification. Why change it if you still need partials?

leamas commented 3 years ago

Well, I see the value of a simpler directory structure now when it's done. Don't you?

leamas commented 3 years ago

If we really want to simplify maintenance: https://github.com/opencpn-manuals/plugins/issues/72#issuecomment-927069357

rgleason commented 3 years ago

Well it all works for me locally, no problem. I found that I need partials because we have 3 lists that are drawn into the nav bar. Nav-all, nav-main and nav-beta.

May I push this to main branch, then you can work on it more?

Ps i like the navigation as is, just did not like the structure.

leamas commented 3 years ago

You don't need permission from anyone, just do it. If someone is upset, he'll have to revert which isn't a big deal.

That said, to me this looks good.

rgleason commented 3 years ago

Thanks. Will first try to do your requested changes to the wiki, then this.

rgleason commented 3 years ago

Mike, I just did another antora site.yml locally and your menus are working very nicely including the Authoring and General and Supplementary Information. I think you will find this much easier to understand and maintain. We basically have to update

..\manual\plugins\modules\ROOT

..\manual\plugins\modules\authoring\pages

There may be a clever way to use "partials" pages in the index-main.adoc and the index-beta.adoc Also to turn the authoring.adoc into a partials:nav-authoring.adoc and use that in nav.adoc and authoring.adoc.

Then we would only have to edit 5 instead of 7 pages.

in one place. But that is for an other time. Perhaps we should just use this for awhile

I hope that helps.

So I am going to rebase and push to main now.

rgleason commented 3 years ago

Change main site.yml page to site: title: OpenCPN url: https://opencpn-manuals.github.io/plugins start_page: opencpn-plugins::index.adoc <--Just this.

Outline

│ │ plugins │ │ │ └── antora.yml " nav: - modules/ROOT/nav.adoc" │ │ │ └──modules │ ├─── advanced <---Has content in it │ ├─── authoring <---Has content in it also is used for index.adoc │ ├─── chart_downloader_tab <---Has content │ ├─── dashboard <---Has content │ ├─── grib_weather <---Has content │ ├─── misc <---Has content │ ├───sat2chart <---Has content │ └───wmm <---Has content │ │ │ ├─── ROOT <---Where all navigation for Plugins is done │ │ ├───── nav.adoc <--Uses partials files nav-main.adoc, nav-beta.adoc, nav-all.adoc. Lefthand Nav bar │ │ ├───── antora.yml
│ │ ├───── pages <-- These file are displayed in the center page area │ │ ├──────── index.adoc <-- Has main links to Gen. Info, Main & Beta Plugins, Authoring │ │ ├──────── index-main.adoc <-- Has the links to sources (main plugins) (could use partials) │ │ ├──────── index-beta.adoc <---Has the links to sources (beta plugins) (could use partials) │ │ ├───── partials Lists used in other files like nav.adoc │ │ ├──────── nav-main.adoc <-- Links to sources (main plugins) │ │ ├──────── nav-beta.adoc <---Links to sources (beta plugins) │ │ ├──────── nav-all.adoc <---Links to sources (beta plugins)

rgleason commented 3 years ago 

Rick@Dart MINGW64 ~/documents/github/OM-plugins (nav)
$ git fetch

Rick@Dart MINGW64 ~/documents/github/OM-plugins (nav)
$ git rebase origin/main
Current branch nav is up to date.

Rick@Dart MINGW64 ~/documents/github/OM-plugins (nav)
$ git log --oneline -10
8ef7584 (HEAD -> nav) Simplify Navigation -sm chngs
d2d7c63 (origin/build) [full-linkcheck] empty commit
230902a Simplify Navigation
12e9c3b (origin/main, origin/HEAD, main) [full-linkcheck] empty commit
d5614ec [full-linkcheck] empty commit
84aac89 sml chgs to nav index
5769c7d Update advanced.adoc
80105f3 advanced.adoc
d09063b misc/plugin-install: Update info on supported platforms.
ea53f68 advanced

Then push git push origin nav:main $ git push origin nav:main

rgleason commented 3 years ago

It appears that these worked and are now in main. Closing

8ef7584 (HEAD -> nav) Simplify Navigation -sm chngs
d2d7c63 (origin/build) [full-linkcheck] empty commit
230902a Simplify Navigation
Rasbats commented 3 years ago

Locally this looks good. Now ... have you pushed to build? Has this been updated for your work in main: https://opencpn-manuals.github.io/plugins/

rgleason commented 3 years ago

Thanks I am in my nav branch locally right now, so

git checkout main
git pull
   lots of changes

Rick@Dart MINGW64 ~/documents/github/OM-plugins (main)
$ git log --oneline -10
8ef7584 (HEAD -> main, origin/main, origin/HEAD, nav) Simplify Navigation -sm chngs
d2d7c63 (origin/build) [full-linkcheck] empty commit
230902a Simplify Navigation
12e9c3b [full-linkcheck] empty commit
d5614ec [full-linkcheck] empty commit
84aac89 sml chgs to nav index
5769c7d Update advanced.adoc
80105f3 advanced.adoc
d09063b misc/plugin-install: Update info on supported platforms.
ea53f68 advanced

and now HEAD seems to be the same as my nav branch, so I am current

Thanks.

rgleason commented 3 years ago

That's good that locally it looks good. I am trying to figure out why your nice expandable Nav.adoc isn't used all the time,
when
the Center page is showing index-main.adoc (LATER- This is OK, not an issue, shows nav.adoc) and index-beta.adoc? (LATER - This is OK, not an issue shows nav.adoc) and when you are viewing a plugin (LATER - this is where the problem is, nav.adoc is not being used!!!)

Note: When you are viewing an internal plugin the nice expandible Nav.adoc is used!!! I think it should be that way for all the external plugins too. Do you agree?

See https://github.com/opencpn-manuals/plugins/issues/78

rgleason commented 3 years ago

Actually, I totally agree with Alec here, but we need to get the Left Nav Bar working the same for everything (whoops I've been saying the right nav bar! It is the Left nav bar!!1 )

leamas commented 3 years ago

That wxWidgets link is, well, off-topic.

we need to get the Left Nav Bar working the same for everything

Won't happen. This would require that all plugins included the partials from opencpn-manuals/plugins, and this is exactly the kind of dependency we want to avoid. That is, as soon as we added or removed a plugin we would need to file PRs against all plugins. We shouldn't do that.

Since the "Back" button works just fine, let's drop this idea that it should look the same in all situations.

@rgleason : I have 15 (!) unread messages from you since yesterday. No time to handle them, will just drop.

rgleason commented 3 years ago

Alec wrote: Won't happen. This would require that all plugins included the partials from opencpn-manuals/plugins, and this is exactly the kind of dependency we want to avoid. That is, as soon as we added or removed a plugin we would need to file PRs against all plugins. We shouldn't do that.

It wont require recomplie of all pi if the site.yml nav: is simply referring to the partials will it?

There would be no need for a pr to the plugins each time. It is a one time pr to each pi once we have it right.

rgleason commented 3 years ago

Fine. Most of those were from your requests for help with the wiki.

@rgleason : I have 15 (!) unread messages from you since yesterday. No time to handle them, will just drop.

rgleason commented 3 years ago

@leamas I have updated sources.state file so it works again and pushed to build, fulll-linkcheck and then to main. Then git remote update origin Then git rebase origin/main (but I have no changes in main right now) Then git log --oneline -10 (looks good) Then git checkout -b nav-again I would like to rebase commit "Simplify Navigation" 230902a which is in my "nav" branch locally, onto "nav-again" branch. How would I do that?

rgleason commented 3 years ago

I just read " You should not rebase commits you have already pushed to a remote host. A consequence may be an inability to git push your local rebased branch to a remote host, leaving your only option to git push --force."

I have already commited and pushed these changes to a remote host

So I need to somehow reapply "Simplify Navigation" 230902a from the remote.

I could simply make a new commit with the same changes but doing it manually, using the nav-again" branch. I would checkout the Simplify Navigation commit, copy the relevant files somewhere and then checkout nav-again and apply those files.

leamas commented 3 years ago

No. You should persuade Mike to revert his reverts. You could do that yourself, but somehow you and @rasbats must communicate about this and find some common ground, so better if he does it.

leamas commented 3 years ago

... or cherry-pick your previous commits: https://stackoverflow.com/questions/8728093/how-do-i-un-revert-a-reverted-git-commit