search

JMRI / JMRI

JMRI model railroad digital command & control software
https://www.jmri.org
Other
240 stars 331 forks source link

Develop solution for help and web "fragment files" #6497

Closed bobjacobsen closed 3 years ago

bobjacobsen commented 5 years ago

We use a single set of files for JavaHelp content and our web site. To do this, we put the formatting information in "fragment files" that are not visible to the JavaHelp system, but appear when viewing of the web because the server has inserted them into the content via Server Side Includes (SSI):

<!--#include virtual="/Style.shtml" -->

If you're not familiar with this, please see our documentation page.

The fragment files were originally called "Header", "Footer", "Sidebar", etc with no suffix. Most webserver will do SSI in a file with a .shtml suffix, but not in others suffixes or no suffix.

It would be nice to be able to include fragment files within fragment files. For example, it would be nice to have a single, common "Tools" menu fragment that can be included in various "Sidebar" fragments so that it only has to be changed once.

But that can't work so long as that including file is called "Sidebar", because SSI instructions within that file won't be detected and resolved.

So what to do?

Are there any good solutions that will work with our existing infrastructure? (This is not about replacing JavaHelp or anything like that; if you want to propose that, please open another Issue)

The only thing I've thought of is replacing i.e. Sidebar with Sidebar.inc.shtml, and teaching the tools to not scan for errors in .inc.shtml files (which is an acceptably small change).

Would appreciate any other ideas on this.

dsand47 commented 5 years ago

Given the existing dual JavaHelp/Web requirements I don't find a better solution. It appears that the alternatives to SSI require PHP, Javascript, or modern browsers. The value of SSI is that it is transparent to JavaHelp.

I did a small test of changing Sidebar to Sidebar.shtml. It worked as expected. I ran ant scanhelp and it did not complain. I do not know anything about other tools or how they may be impacted.

In addition to the Tools list, the Automation list may be another candidate.

dsand47 commented 5 years ago

As an alternative to Sidebar.inc.shtml the html fragments could use .inc as the extension. This would apply to both the sidebar fragments and the sub includes such as the tools list.

The change to http.conf:

    AddType text/html .shtml .inc
    AddOutputFilter INCLUDES .shtml .inc

Using .inc as a common html fragment extension would make tool changes easier.

bobjacobsen commented 5 years ago

Thanks.

The question is how much we want to require of people who want to host the web site on their own machines, i.e. for development or to have a local copy. I don't think it's all that common. We do have instructions for setting up Apache at http://jmri.org/help/en/html/doc/Technical/WebSite.shtml what could be updated to include this.

dsand47 commented 5 years ago

The impact on local hosting by using an extension such as .inc is very small. I have also worked out the procedure for using Nginx on Linux.

The larger issues are the changes for people creating/updating web and help pages. This is dependent on the scope of the changes.

I am probably getting carried away, but the ideal scope is that all html fragments become .inc files, including Header, Footer, Style and lots of Sidebar(s). This means just about every page is affected.

Limiting the scope to just the Sidebar issue would reduce the scope but that would result in inconsistent html fragment handling.

This might be one of those cases where the long term payback does not justify the effort to simplify Sidebar list changes.

silverailscolo commented 5 years ago

Using the .inc extension for the Sidebar fragments seems OK te me as an occasional help page editor. Do not expect it to cover all copies of files by this name, as what is displayed in the Sidebar intentionally varies in response to the contents of the main pane. For example, when a group of items is called "Other Tools", the one you are looking at will not be in that list. If we conclude the list of items shouldn't change, then I would try to make the current item graphically stand out, so it works like a navigation pointer, possibly showing subitems for this category. JMRI is too mature to show all it can in one single sidebar.

dsand47 commented 5 years ago

The .inc proposal enables nested includes. 2 or 3 common sidebar blocks would move to their own include file. The application specific Sidebar.inc file would include the appropriate nested include files. The displayed browser page will be the same as it is now.

For example, adding an entry to the Tools list currently requires 22 file changes. And I still need to do French. With nested includes, only one file per language will need to be changed to add an entry to the Tools list.

Once all of the html code fragments are in include files, tools that check html structure can easily ignore the include files.

rhwood commented 5 years ago

You could use a static generator like https://freemarker.apache.org in all cases, which would eliminate the need to run httpd locally for development, allow JavaHelp to be complete, and allow JMRI to host its own website.

danielb987 commented 5 years ago

Is there a conclusion on which way to go forward on this? Is .inc files or static generator like freemaker the preferred way to go forward?

bobjacobsen commented 5 years ago

I haven't had time to look into @rhwood's suggestion yet, sorry. It might well be the key to this, depending on workflow impact.

danielb987 commented 5 years ago

No problem.

I took a look at @rhwood's suggestion Apache FreeMarker and got one question. Javahelp ignores SSI. If we change to a template engine like FreeMaker, then that will include all the included files in the main file, including formatting and menu items. Maybe we therefore needs to have two sets of compiled html pages, one for the web and one for Javahelp? FreeMaker will probably be able to do that, but it's one thing to look out for.

rhwood commented 5 years ago

The only thing that understands SSI is the Apache HTTPD server, since SSI is a feature of that server. It’s not that JavaHelp or anything else ignores that, it’s that SSI is not part of any HTML or other standard.

danielb987 commented 5 years ago

Yes, I understand that. But that was not my point. My point is that if we switch from SSI to a template engine, the HTML pages will include everything that was included by SSI. And that is maybe not what we want. So we might need two different trees of HTML pages, one for the Apache web server and one for Javahelp.

bobjacobsen commented 5 years ago

The original layout (as created by @plocher IIRC) used Perl scripts to handle common Header, Footer etc. There was an "update in place" step that would apply an updated file to the entire site.

When JavaHelp came along, we switched to using SSI (at that time, we were serving them from an IIS machine; lots of web servers know about SSI) so that there would be a "simple HTML" version for JavaHelp (which has it's own navigation built in) and an "embellished" one for the web. Because of SSI, no build step was needed. You just did a bit of configuration and had a live copy of the web site on your personal machine, so you could see the effect of an edit immediately on a fully-formatted web page.

But that solution wasn't particularly good for printing, either from JavaHelp nor from the web pages; there was no way to really put together the "JMRI book" that people keep starting to create and then trailing off....

And that, along with the need to eventually drop JavaHelp (because it's really no longer maintained and is starting to have problems with our content&format that are hard to manage), leads to periodic proposals for a "build various forms of content from a single base" approaches. Since refactoring the Sidebar et al is likely to be a lot of edits, maybe now is the time to look at it again.

dsand47 commented 5 years ago

I have done a lot of web searching but I was not able to find a modern alternative to JaveHelp. Either my search arguments were not effective or there truly is no alternative.

There are two primary requirements for a replacement:

Other nice to have features currently provided by JavaHelp:

A very different idea that I came up with is launching a browser window from JMRI to display the help document. I have a test version working with macOS 10.14.3, Win10 and Mint18. I suspect there may be issues with different environments, especially WinXP and some Linux variants. The main benefit is the ability to use more recent versions of HTML and CSS. The main drawback is that the user is taken out of the JMRI environment. It is disconcerting when the switch occurs.

danielb987 commented 5 years ago

Is it an option to make a JmriHelp instead of JavaHelp? That JMRI has its own help viewer developed by our selves? If we move to a template engine like FreeMaker, it could generate output in a format suitable for the web as well as a format suitable for JmriHelp, for example XML files.

rhwood commented 5 years ago

I wouldn’t attempt to maintain an in-app renderer for help content, and would use the default web browser to display help as HTML.

Complex formatted free text (aka HTML aka help content) is complex to render, and maintaining renderers is so complex that Sun and Oracle both basically didn’t bother within Java (or gave up as in the JavaHelp tool), and even Microsoft has announced that they are giving up on the one they maintain in Windows 10 (and will use Google’s). Note that you will also have to consider accessibility concerns and when displaying the JMRI help about how to address those within JMRI itself is not the time to get those wrong.

Apple has this to say about using a non-standard help viewer:

Use the system-provided Help Viewer app. Help Viewer is familiar and provides a consistent browsing experience across the system. When people look for help, it’s usually because they are having difficulty accomplishing a task, which means they might be frustrated. This isn’t a good time to make them learn a help viewing mechanism that differs from the one they use in all their other apps.

Note that Help Viewer is built into macOS, and not available elsewhere, so we can’t use it; the next best thing is the user’s default web browser, since it is likely to be familiar, and likely to be configured to display content correctly for that user.

There are a myriad of static HTML documentation examples with search built in for offline use that meeting the requirements of offline use in a browser is not difficult.

bobjacobsen commented 5 years ago

Our existing JavaHelp implementation will pop out to the local web browser when it can't natively display a file. IIRC, this is done via the jmri.util.ExternalLinkContentViewerUI class.

Originally, you couldn't really count on a web browser on the local machine, so JavaHelp (and JMRI's use of it) was intended to be independent of anything like that. Times have changed and you can count on a browser. But switching out to one is a bit of a jolt, and a browser-based solution doesn't make it easy to have support for an index, a table of contents, search, etc.

Nor does a browser-based solution take us any closer to having a way to nicely print the HTML content (though having better printing formats via css and/or XSLT might be a step in that direction)

For now, I think the minimal step is to start using .inc files to simplify the formatting-around-the-content part of the web site. Hope to work on that shortly, once I get some other things done.

For the longer term, I'm not sure what the right approach is. In the base, people have suggested backing up to a higher-level form, i.e. DocBook or similar, that could generate online pages, with-program help (maybe even machine-type specific), books, etc. There might be tools out there that can take a common format to Windows Help, macOS Help Viewer, etc. I haven't done the research on that.

KenC57 commented 5 years ago

Would the idea of making the JMRI webserver an 'always' feature help with how to display help material? The means the common browser is the viewer. Question then becomes if our webserver can support the .inc files or other methods.

devel-bobm commented 5 years ago

I've added an issue for a "wishlist" feature for some future help mechanism implementation in #6547. Neither existing JHelpDev nor ".inc" files seem to address the basic idea expressed in that issue.

plocher commented 5 years ago

$0.02

Since JMRI already has other web based things (remote panels, xml,...) some thought should go into making a web-help system tie into those other things as well, if only to make it less of a jolt when switching between java-jmri and web-jmri...

-John

On Sun, Feb 10, 2019 at 4:22 PM Ken Cameron notifications@github.com wrote:

Would the idea of making the JMRI webserver an 'always' feature help with how to display help material? The means the common browser is the viewer. Question then becomes if our webserver can support the .inc files or other methods.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-462195740, or mute the thread https://github.com/notifications/unsubscribe-auth/ABCF9wjxmRXxfuo5PwPdlZ7K0eZ778iyks5vMLfdgaJpZM4aRwz5 .

rhwood commented 4 years ago

Revisiting this:

I found JBake which can be used for static site generation using a myriad of templating engines and input formats. Of interest are that it uses:

plocher commented 4 years ago

Jekyll-based website systems like those supported by GitHub are also worth looking at - and they support all the trendy buzzwords, too :-)

-John

On Sat, Jan 4, 2020 at 2:33 PM Randall Wood notifications@github.com wrote:

Revisiting this:

I found JBake https://jbake.org which can be used for static site generation using a myriad of templating engines and input formats. Of interest are that it uses:

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AAIIL55HJW4B7KRBK7ZZKADQ4EFEVA5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDBWWA#issuecomment-570825560, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL57WS27OONVQF34O3S3Q4EFEVANCNFSM4GSHBT4Q .

rhwood commented 4 years ago

I have investigated using the GitHub pages toolkit.

Jekyll requires a C compiler to install (even though written in Ruby, and can be run in JRuby, its installer relies on native code).

Jbake is pure java, meaning our existing tool chain can be used, and it could possibly be used in JMRI itself.

Randall Sent from my iPhone

On Jan 4, 2020, at 19:46, John Plocher notifications@github.com wrote:

Jekyll-based website systems like those supported by GitHub are also worth looking at - and they support all the trendy buzzwords, too :-)

-John

On Sat, Jan 4, 2020 at 2:33 PM Randall Wood notifications@github.com wrote:

Revisiting this:

I found JBake https://jbake.org which can be used for static site generation using a myriad of templating engines and input formats. Of interest are that it uses:

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AAIIL55HJW4B7KRBK7ZZKADQ4EFEVA5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDBWWA#issuecomment-570825560, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL57WS27OONVQF34O3S3Q4EFEVANCNFSM4GSHBT4Q .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

bobjacobsen commented 4 years ago

Quite a few model railroad computers aren't attached to any network. This seems to be quite common among the older set, with sometimes older computers. We could go from using the integrated JavaHelp to having a (default) browser open a local file (HTML or some other format) if we could find a way to provide a completely-local table of contents, index and search capability.

rhwood commented 4 years ago

There are purely-in-browser single-site search engines that do not rely on a server (Lunr is commonly recommended) that can be integrated. I assume similar techniques used to generate its database can be used to generate an index and TOC (unless we want the index to be more manually curated like a site navigation system).

plocher commented 4 years ago

My point is that the JMRI stuff is on GitHub and uses the Jenkins CI system already, so it would be easy (TM) to use their existing tooling to generate the JMRI web pages and the artifacts used by the help and reference systems, without any need to install compilers or language systems locally. I've been working on upgrading my own systems to Jekyll/Github, and have found it easy to tie into the Jenkins environment to auto-generate javadocs and markdown/html web pages - the entirety of the electronics[1] and arduino[2] sub page sets there is script-generated, and my I2C abstraction library[3] has its JavaDoc generated on the fly.

Most of the GitHub Jekyll templates support a local JavaScript based search/help system out of the box that "just works" on generated sites, though I have not enabled it yet on my stuff.

In particular, as the one who set up the original bastardized server side include/ string processing cruft that the web site still has vestiges of in odd places, the conversion to a Jekyll environment wouldn't be hard, and might be an opportunity to refactor and clean up some 15 year old cruft :-)

[1] https://spcoast.github.io/electronics.html [2] https://spcoast.github.io/arduino.html [3] https://github.com/plocher/I2Cexpander, https://plocher.github.io/I2Cexpander/class_i2_cexpander.html

On Sat, Jan 4, 2020 at 4:57 PM Randall Wood notifications@github.com wrote:

I have investigated using the GitHub pages toolkit.

Jekyll requires a C compiler to install (even though written in Ruby, and can be run in JRuby, its installer relies on native code).

Jbake is pure java, meaning our existing tool chain can be used, and it could possibly be used in JMRI itself.

Randall Sent from my iPhone

On Jan 4, 2020, at 19:46, John Plocher notifications@github.com wrote:

Jekyll-based website systems like those supported by GitHub are also worth looking at - and they support all the trendy buzzwords, too :-)

-John

On Sat, Jan 4, 2020 at 2:33 PM Randall Wood notifications@github.com wrote:

Revisiting this:

I found JBake https://jbake.org which can be used for static site generation using a myriad of templating engines and input formats. Of interest are that it uses:

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub < https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AAIIL55HJW4B7KRBK7ZZKADQ4EFEVA5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDBWWA#issuecomment-570825560 , or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAIIL57WS27OONVQF34O3S3Q4EFEVANCNFSM4GSHBT4Q

.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AAIIL57OHTYHJVPSNDZOJPDQ4EV53A5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDDXMA#issuecomment-570833840, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL52QBGCIOJ622BNYCZ3Q4EV53ANCNFSM4GSHBT4Q .

rhwood commented 4 years ago

My points are:

As the one who setup the server-side include/string processing cruft used in the JMRI applications, I don’t want to maintain two different workflows/templates languages/source set for maintaining different parts of the JMRI application that ships.

On 05-Jan-2020, at 18:58, John Plocher notifications@github.com wrote:

My point is that the JMRI stuff is on GitHub and uses the Jenkins CI system already, so it would be easy (TM) to use their existing tooling to generate the JMRI web pages and the artifacts used by the help and reference systems, without any need to install compilers or language systems locally. I've been working on upgrading my own systems to Jekyll/Github, and have found it easy to tie into the Jenkins environment to auto-generate javadocs and markdown/html web pages - the entirety of the electronics[1] and arduino[2] sub page sets there is script-generated, and my I2C abstraction library[3] has its JavaDoc generated on the fly.

Most of the GitHub Jekyll templates support a local JavaScript based search/help system out of the box that "just works" on generated sites, though I have not enabled it yet on my stuff.

In particular, as the one who set up the original bastardized server side include/ string processing cruft that the web site still has vestiges of in odd places, the conversion to a Jekyll environment wouldn't be hard, and might be an opportunity to refactor and clean up some 15 year old cruft :-)

[1] https://spcoast.github.io/electronics.html [2] https://spcoast.github.io/arduino.html [3] https://github.com/plocher/I2Cexpander, https://plocher.github.io/I2Cexpander/class_i2_cexpander.html

On Sat, Jan 4, 2020 at 4:57 PM Randall Wood notifications@github.com wrote:

I have investigated using the GitHub pages toolkit.

Jekyll requires a C compiler to install (even though written in Ruby, and can be run in JRuby, its installer relies on native code).

Jbake is pure java, meaning our existing tool chain can be used, and it could possibly be used in JMRI itself.

Randall Sent from my iPhone

On Jan 4, 2020, at 19:46, John Plocher notifications@github.com wrote:

Jekyll-based website systems like those supported by GitHub are also worth looking at - and they support all the trendy buzzwords, too :-)

-John

On Sat, Jan 4, 2020 at 2:33 PM Randall Wood notifications@github.com wrote:

Revisiting this:

I found JBake https://jbake.org which can be used for static site generation using a myriad of templating engines and input formats. Of interest are that it uses:

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub < https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AAIIL55HJW4B7KRBK7ZZKADQ4EFEVA5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDBWWA#issuecomment-570825560 , or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAIIL57WS27OONVQF34O3S3Q4EFEVANCNFSM4GSHBT4Q

.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AAIIL57OHTYHJVPSNDZOJPDQ4EV53A5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIDDXMA#issuecomment-570833840, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL52QBGCIOJ622BNYCZ3Q4EV53ANCNFSM4GSHBT4Q .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497?email_source=notifications&email_token=AACISEE4G6BR23VX4YZAQXTQ4JXY7A5CNFSM4GSHBT42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIEC6ZI#issuecomment-570961765, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACISEDRRH2GO7NZUM7ETDTQ4JXY7ANCNFSM4GSHBT4Q.

jerryg2003 commented 4 years ago

I know this string of posts has changed subject along the way, but going back a year to the original post from @bobjacobsen and follow on, various of us have now replaced all references to Header, Footer, and Sidebar with those names with the .shtml suffix. [I am periodically deleting non-.shtml files when I can to reduce the “noise” of leftover files.] The help/en/parts directory was created by BobJ to contain various parts to be “included” in Sidebar.shtml files as appropriate. I have created and modified several such parts to allow flexibility in what is included and am working my way through all copies of Sidebar.shtml in help/en/html/ to use these parts.

In addition, I have created a model of a Sidebar.shtml that will be replicable across many sub-directories by use of a further included “local part.” So far, I have only implemented this in help/en/html/tools/throttle directory but will, over the next month or so, work my way through all tools directories with this approach (hardware directories will get a similar rework with a SidebarHardwareLocalPart.shtml after I am done with tools). I have already eliminated several thousand lines of duplicated (and sometimes inconsistent) html and expect to eliminate several thousand more before I am done. The goal is both consistency and ease of maintenance. E.g. we should be able to add a sidebar link to a new piece of hardware by making only the single change to the SidebarSupportedHardware.shtml part and have it show up throughout the web site.

FYI, this is part of a larger effort of mine to improve help/web site info for all our users. I’ve got a list of a couple dozen tasks that I have put in issue #8139 to track and enlist other volunteers.

Jerry

rhwood commented 4 years ago

I've done a lot of research concerning how help is provided, and have learned the following:

This has led to the following conclusions on my part:

I have begun working on the infrastructure to switch from SSI to using static site generation using AsciiDoc or Markdown or HTML as the source format, Freemarker as the templating engine, and JBake as the build tool (but don't have it PR ready yet).

plocher commented 4 years ago

Take a look at Jekyll / Liquid and the various github-enabled Documentation "themes" it supports.

Pretty much everything on your list of druthers is supported out of the box:

On Mon, Apr 6, 2020 at 6:38 AM Randall Wood notifications@github.com wrote:

I've done a lot of research concerning how help is provided, and have learned the following:

  • The only actively maintained in-app Help viewer for Java is the Eclipse help viewer, for which documentation on how to use outside an Eclipse SWT-based app is sparse. It does require that content be provided from a web server
  • JavaHelp is not only no longer maintained, it does not build under Java 8 or newer (the initial fix for that seems trivial, but then we are stuck maintaining that fork, and I don't know what else is broken and hidden by that first failure)
  • Microsoft has removed all "native" / specialized help viewers from Windows (they announced this change to developers in 2006, but only implemented in Windows 10); Microsoft's position on user assistance is that if it can't be displayed in a browser, it needs to be tightly integrated into the app (as tooltips, messages integrated into the UI, or a panel/pane/tab in the window for which it is providing help)
  • Apple recommends using its built-in help viewer, but building the search index for that can only be done on macOS
  • Java 9 and newer have built-in support for opening help content from a Java application in the Apple help viewer if on macOS (and do nothing if not on that platform)
  • GNOME has a built-in help viewer, is self-indexing for search iff using docbook or mallard for content (specifically not if using HTML for content), and has very specific path requirements (and can't handle multiple instances of JMRI at once)
  • The Apache HTTP configuration documented in our help content to load our website gets reset on even minor updates of macOS (I don't know about various linux distributions), is likely not to be supported in the next major macOS release, and is undocumented for Windows users.

This has led to the following conclusions on my part:

  • We should change from using SSI to using static site generation from templates so that the in browser help shipped with JMRI is navigable in browser (like when a user can't start JMRI and opens help/en/index.html )
  • We should have only one sidebar for all help content and it should be the Table of Contents for all help content (its easy to use CSS and a little javascript to allow the user to show or hide the TOC
  • We should move our local help content from JavaHelp to being displayed in the browser
  • We should switch from writing documentation in HTML to using AsciiDoc, as GitHub and some IDEs can do a live preview of this (AsciiDoc instead of Markdown because AsciiDoc has useful documentation-oriented features that Markdown does not)
  • We should investigate search mechanisms that work in the browser and implement one
  • Once we migrate to Java 9+, we should evaluate using Apple's help viewer on macOS

I have begun working on the infrastructure to switch from SSI to using static site generation using AsciiDoc or Markdown or HTML as the source format, Freemarker as the templating engine, and JBake as the build tool (but don't have it PR ready yet).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609799871, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL55ILR6IHVINFHXFCD3RLHLM3ANCNFSM4GSHBT4Q .

rhwood commented 4 years ago

I have looked at Jekyll.

There is one requirement that I did not articulate: the build tools have to work within the JVM (i.e. JMRI developers should not have to learn how to maintain the Ruby build chain).

I rejected Jekyll because not only can’t it run in the JVM, it’s installation requires a C compiler to be installed as well as Ruby.

Randall Sent from my iPhone

On Apr 6, 2020, at 12:41, John Plocher notifications@github.com wrote:

 Take a look at Jekyll / Liquid and the various github-enabled Documentation "themes" it supports.

Pretty much everything on your list of druthers is supported out of the box:

  • static site generation
  • automatically generated multi-level help sidebar that is context sensitive
  • Markdown or html or your choice of markup...
  • built in search

-John

On Mon, Apr 6, 2020 at 6:38 AM Randall Wood notifications@github.com wrote:

I've done a lot of research concerning how help is provided, and have learned the following:

  • The only actively maintained in-app Help viewer for Java is the Eclipse help viewer, for which documentation on how to use outside an Eclipse SWT-based app is sparse. It does require that content be provided from a web server
  • JavaHelp is not only no longer maintained, it does not build under Java 8 or newer (the initial fix for that seems trivial, but then we are stuck maintaining that fork, and I don't know what else is broken and hidden by that first failure)
  • Microsoft has removed all "native" / specialized help viewers from Windows (they announced this change to developers in 2006, but only implemented in Windows 10); Microsoft's position on user assistance is that if it can't be displayed in a browser, it needs to be tightly integrated into the app (as tooltips, messages integrated into the UI, or a panel/pane/tab in the window for which it is providing help)
  • Apple recommends using its built-in help viewer, but building the search index for that can only be done on macOS
  • Java 9 and newer have built-in support for opening help content from a Java application in the Apple help viewer if on macOS (and do nothing if not on that platform)
  • GNOME has a built-in help viewer, is self-indexing for search iff using docbook or mallard for content (specifically not if using HTML for content), and has very specific path requirements (and can't handle multiple instances of JMRI at once)
  • The Apache HTTP configuration documented in our help content to load our website gets reset on even minor updates of macOS (I don't know about various linux distributions), is likely not to be supported in the next major macOS release, and is undocumented for Windows users.

This has led to the following conclusions on my part:

  • We should change from using SSI to using static site generation from templates so that the in browser help shipped with JMRI is navigable in browser (like when a user can't start JMRI and opens help/en/index.html )
  • We should have only one sidebar for all help content and it should be the Table of Contents for all help content (its easy to use CSS and a little javascript to allow the user to show or hide the TOC
  • We should move our local help content from JavaHelp to being displayed in the browser
  • We should switch from writing documentation in HTML to using AsciiDoc, as GitHub and some IDEs can do a live preview of this (AsciiDoc instead of Markdown because AsciiDoc has useful documentation-oriented features that Markdown does not)
  • We should investigate search mechanisms that work in the browser and implement one
  • Once we migrate to Java 9+, we should evaluate using Apple's help viewer on macOS

I have begun working on the infrastructure to switch from SSI to using static site generation using AsciiDoc or Markdown or HTML as the source format, Freemarker as the templating engine, and JBake as the build tool (but don't have it PR ready yet).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609799871, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL55ILR6IHVINFHXFCD3RLHLM3ANCNFSM4GSHBT4Q .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

plocher commented 4 years ago

My $0.02, which is probably worth even less than that, because I'm not the one implementing this...

This constraint feels arbitrary and short sighted.

Installing these things is trivial, and, for what I did with it ( www.spcoast.com) does not require a compiler unless you insist on installing the ruby stuff from sources. In fact, everything can be done on Github, with nothing installed locally on your computer, if so desired.

But, go ahead and reinvent these wheels and make all the developers invest in installing and learning bespoke-to-JMRI inventions just so they don't need to install a ruby runtime...

-John

On Mon, Apr 6, 2020 at 10:23 AM Randall Wood notifications@github.com wrote:

I have looked at Jekyll.

There is one requirement that I did not articulate: the build tools have to work within the JVM (i.e. JMRI developers should not have to learn how to maintain the Ruby build chain).

I rejected Jekyll because not only can’t it run in the JVM, it’s installation requires a C compiler to be installed as well as Ruby.

Randall Sent from my iPhone

On Apr 6, 2020, at 12:41, John Plocher notifications@github.com wrote:

 Take a look at Jekyll / Liquid and the various github-enabled Documentation "themes" it supports.

Pretty much everything on your list of druthers is supported out of the box:

  • static site generation
  • automatically generated multi-level help sidebar that is context sensitive
  • Markdown or html or your choice of markup...
  • built in search

-John

On Mon, Apr 6, 2020 at 6:38 AM Randall Wood notifications@github.com wrote:

I've done a lot of research concerning how help is provided, and have learned the following:

  • The only actively maintained in-app Help viewer for Java is the Eclipse help viewer, for which documentation on how to use outside an Eclipse SWT-based app is sparse. It does require that content be provided from a web server
  • JavaHelp is not only no longer maintained, it does not build under Java 8 or newer (the initial fix for that seems trivial, but then we are stuck maintaining that fork, and I don't know what else is broken and hidden by that first failure)
  • Microsoft has removed all "native" / specialized help viewers from Windows (they announced this change to developers in 2006, but only implemented in Windows 10); Microsoft's position on user assistance is that if it can't be displayed in a browser, it needs to be tightly integrated into the app (as tooltips, messages integrated into the UI, or a panel/pane/tab in the window for which it is providing help)
  • Apple recommends using its built-in help viewer, but building the search index for that can only be done on macOS
  • Java 9 and newer have built-in support for opening help content from a Java application in the Apple help viewer if on macOS (and do nothing if not on that platform)
  • GNOME has a built-in help viewer, is self-indexing for search iff using docbook or mallard for content (specifically not if using HTML for content), and has very specific path requirements (and can't handle multiple instances of JMRI at once)
  • The Apache HTTP configuration documented in our help content to load our website gets reset on even minor updates of macOS (I don't know about various linux distributions), is likely not to be supported in the next major macOS release, and is undocumented for Windows users.

This has led to the following conclusions on my part:

  • We should change from using SSI to using static site generation from templates so that the in browser help shipped with JMRI is navigable in browser (like when a user can't start JMRI and opens help/en/index.html )
  • We should have only one sidebar for all help content and it should be the Table of Contents for all help content (its easy to use CSS and a little javascript to allow the user to show or hide the TOC
  • We should move our local help content from JavaHelp to being displayed in the browser
  • We should switch from writing documentation in HTML to using AsciiDoc, as GitHub and some IDEs can do a live preview of this (AsciiDoc instead of Markdown because AsciiDoc has useful documentation-oriented features that Markdown does not)
  • We should investigate search mechanisms that work in the browser and implement one
  • Once we migrate to Java 9+, we should evaluate using Apple's help viewer on macOS

I have begun working on the infrastructure to switch from SSI to using static site generation using AsciiDoc or Markdown or HTML as the source format, Freemarker as the templating engine, and JBake as the build tool (but don't have it PR ready yet).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609799871, or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAIIL55ILR6IHVINFHXFCD3RLHLM3ANCNFSM4GSHBT4Q

.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609928015, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL557ZF6EYTRXC7R7N5DRLIFX3ANCNFSM4GSHBT4Q .

rhwood commented 4 years ago

I followed the installation instructions on the Jekyll website and one of the gems refused to install without compiling native code.

I am also concerned about a build process for something that ships as part of JMRI, not content that resides only on the JMRI.org website, or are you seriously suggesting that the help content we currently ship with JMRI should just be ripped out without replacement since it “can be done on GitHub”?

Randall Sent from my iPhone

On Apr 6, 2020, at 13:33, John Plocher notifications@github.com wrote:

 My $0.02, which is probably worth even less than that, because I'm not the one implementing this...

This constraint feels arbitrary and short sighted.

Installing these things is trivial, and, for what I did with it ( www.spcoast.com) does not require a compiler unless you insist on installing the ruby stuff from sources. In fact, everything can be done on Github, with nothing installed locally on your computer, if so desired.

But, go ahead and reinvent these wheels and make all the developers invest in installing and learning bespoke-to-JMRI inventions just so they don't need to install a ruby runtime...

-John

On Mon, Apr 6, 2020 at 10:23 AM Randall Wood notifications@github.com wrote:

I have looked at Jekyll.

There is one requirement that I did not articulate: the build tools have to work within the JVM (i.e. JMRI developers should not have to learn how to maintain the Ruby build chain).

I rejected Jekyll because not only can’t it run in the JVM, it’s installation requires a C compiler to be installed as well as Ruby.

Randall Sent from my iPhone

On Apr 6, 2020, at 12:41, John Plocher notifications@github.com wrote:

 Take a look at Jekyll / Liquid and the various github-enabled Documentation "themes" it supports.

Pretty much everything on your list of druthers is supported out of the box:

  • static site generation
  • automatically generated multi-level help sidebar that is context sensitive
  • Markdown or html or your choice of markup...
  • built in search

-John

On Mon, Apr 6, 2020 at 6:38 AM Randall Wood notifications@github.com wrote:

I've done a lot of research concerning how help is provided, and have learned the following:

  • The only actively maintained in-app Help viewer for Java is the Eclipse help viewer, for which documentation on how to use outside an Eclipse SWT-based app is sparse. It does require that content be provided from a web server
  • JavaHelp is not only no longer maintained, it does not build under Java 8 or newer (the initial fix for that seems trivial, but then we are stuck maintaining that fork, and I don't know what else is broken and hidden by that first failure)
  • Microsoft has removed all "native" / specialized help viewers from Windows (they announced this change to developers in 2006, but only implemented in Windows 10); Microsoft's position on user assistance is that if it can't be displayed in a browser, it needs to be tightly integrated into the app (as tooltips, messages integrated into the UI, or a panel/pane/tab in the window for which it is providing help)
  • Apple recommends using its built-in help viewer, but building the search index for that can only be done on macOS
  • Java 9 and newer have built-in support for opening help content from a Java application in the Apple help viewer if on macOS (and do nothing if not on that platform)
  • GNOME has a built-in help viewer, is self-indexing for search iff using docbook or mallard for content (specifically not if using HTML for content), and has very specific path requirements (and can't handle multiple instances of JMRI at once)
  • The Apache HTTP configuration documented in our help content to load our website gets reset on even minor updates of macOS (I don't know about various linux distributions), is likely not to be supported in the next major macOS release, and is undocumented for Windows users.

This has led to the following conclusions on my part:

  • We should change from using SSI to using static site generation from templates so that the in browser help shipped with JMRI is navigable in browser (like when a user can't start JMRI and opens help/en/index.html )
  • We should have only one sidebar for all help content and it should be the Table of Contents for all help content (its easy to use CSS and a little javascript to allow the user to show or hide the TOC
  • We should move our local help content from JavaHelp to being displayed in the browser
  • We should switch from writing documentation in HTML to using AsciiDoc, as GitHub and some IDEs can do a live preview of this (AsciiDoc instead of Markdown because AsciiDoc has useful documentation-oriented features that Markdown does not)
  • We should investigate search mechanisms that work in the browser and implement one
  • Once we migrate to Java 9+, we should evaluate using Apple's help viewer on macOS

I have begun working on the infrastructure to switch from SSI to using static site generation using AsciiDoc or Markdown or HTML as the source format, Freemarker as the templating engine, and JBake as the build tool (but don't have it PR ready yet).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609799871, or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAIIL55ILR6IHVINFHXFCD3RLHLM3ANCNFSM4GSHBT4Q

.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609928015, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL557ZF6EYTRXC7R7N5DRLIFX3ANCNFSM4GSHBT4Q .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

KenC57 commented 4 years ago

It is still a strong requirement from the users that standalone JMRI will work. Meaning no internet connection. The help must work without the internet connection. -ken c

jerryg2003 commented 4 years ago

Gentlemen:

I am likely not qualified to comment on the technical parts of this discussion, but as someone who has been updating help/web content (and using it extensively myself), I can comment on some of Randall’s proposals:

Hope these thoughts are helpful in terms of “user requests” (I hesitate to use the word “requirements”) as you think through the technical options.

Thanks for listening. Jerry

plocher commented 4 years ago

Randall,

You eloquently state that the current doc/help system is on its last legs and needs to change. You also point at a desirable end state of "a static html site" that can be served by a local-to-JMRI help system that does not require end users to have an internet connection, possibly in conjunction with native Win, Linux an Mac help systems...

You will find absolutely no disagreement from me there.

My focus is on the associated costs of/to the build system that creates those delivered-to-the-user bits.

There are several venn diagram circles here - end users, buildmasters, developers, doc writers, .... and not all need the same type of solution. Case in point, while the end user shouldn't see any disruption based on this conversation, help system developers might have to change how they do things (either with new code or new tools...), and the build system that creates the end user packages for download will certainly change. This is true however this conversation ends.

Your objections seem to come from the perspective of JMRI developers who build their own "help/web" docs, and the concern that they might need to install updated build environment tools. Mine comes from the maturity and complexity of the tool chain used to implement this change...

OK, so lets quantify the cost of updating a build environment in both scenarios;

The tradeoff - to me - looks like this

Jekyll: Pro: Has all the completed, production quality tooling, structure, support and templates in place, ready to install and use today. If configured as part of the JMRI GitHub repo, this could extend to using the built-in-to-github doc system with a forked JMRI repo and get the build and test environment f'or free'... Jekyll: Con: For local-only development, need to do a 1-time install of a Ruby-based infrastructure locally, which might include a compiler

Randall: Pro: uses JMRI/JVM tool chain Randall: Con: requires the invention of a new Java based help system toolchain, tools, libraries, templates and structure from mostly-scratch, because the rest of the world has moved on/away from pure-Java based documentation solutions.

Again, for me, your milage will obviously vary, the metric is

Cost(install Ruby) -vs- Cost(invent new tools, toolchain, code, templates) + Cost(bugs in new toolchain/code/templates) + Cost(time to implement/deploy)

With my sample size of 1, and Dunning Kruger firmly on my side (humor!), I'm absolutely convinced that inventing, building and maintaining a new pure Java environment solution is orders of magnitude harder/costlier than reusing an existing, production quality framework like Jekyll/Liquid, even if it requires a dozen JMRI developers to install Ruby and learn how to type "make" :-)

-John

On Mon, Apr 6, 2020 at 11:00 AM Randall Wood notifications@github.com wrote:

I followed the installation instructions on the Jekyll website and one of the gems refused to install without compiling native code.

I am also concerned about a build process for something that ships as part of JMRI, not content that resides only on the JMRI.org website, or are you seriously suggesting that the help content we currently ship with JMRI should just be ripped out without replacement since it “can be done on GitHub”?

Randall Sent from my iPhone

On Apr 6, 2020, at 13:33, John Plocher notifications@github.com wrote:

 My $0.02, which is probably worth even less than that, because I'm not the one implementing this...

This constraint feels arbitrary and short sighted.

Installing these things is trivial, and, for what I did with it ( www.spcoast.com) does not require a compiler unless you insist on installing the ruby stuff from sources. In fact, everything can be done on Github, with nothing installed locally on your computer, if so desired.

But, go ahead and reinvent these wheels and make all the developers invest in installing and learning bespoke-to-JMRI inventions just so they don't need to install a ruby runtime...

-John

On Mon, Apr 6, 2020 at 10:23 AM Randall Wood notifications@github.com wrote:

I have looked at Jekyll.

There is one requirement that I did not articulate: the build tools have to work within the JVM (i.e. JMRI developers should not have to learn how to maintain the Ruby build chain).

I rejected Jekyll because not only can’t it run in the JVM, it’s installation requires a C compiler to be installed as well as Ruby.

Randall Sent from my iPhone

On Apr 6, 2020, at 12:41, John Plocher notifications@github.com wrote:

 Take a look at Jekyll / Liquid and the various github-enabled Documentation "themes" it supports.

Pretty much everything on your list of druthers is supported out of the box:

  • static site generation
  • automatically generated multi-level help sidebar that is context sensitive
  • Markdown or html or your choice of markup...
  • built in search

-John

On Mon, Apr 6, 2020 at 6:38 AM Randall Wood < notifications@github.com> wrote:

I've done a lot of research concerning how help is provided, and have learned the following:

  • The only actively maintained in-app Help viewer for Java is the Eclipse help viewer, for which documentation on how to use outside an Eclipse SWT-based app is sparse. It does require that content be provided from a web server
  • JavaHelp is not only no longer maintained, it does not build under Java 8 or newer (the initial fix for that seems trivial, but then we are stuck maintaining that fork, and I don't know what else is broken and hidden by that first failure)
  • Microsoft has removed all "native" / specialized help viewers from Windows (they announced this change to developers in 2006, but only implemented in Windows 10); Microsoft's position on user assistance is that if it can't be displayed in a browser, it needs to be tightly integrated into the app (as tooltips, messages integrated into the UI, or a panel/pane/tab in the window for which it is providing help)
  • Apple recommends using its built-in help viewer, but building the search index for that can only be done on macOS
  • Java 9 and newer have built-in support for opening help content from a Java application in the Apple help viewer if on macOS (and do nothing if not on that platform)
  • GNOME has a built-in help viewer, is self-indexing for search iff using docbook or mallard for content (specifically not if using HTML for content), and has very specific path requirements (and can't handle multiple instances of JMRI at once)
  • The Apache HTTP configuration documented in our help content to load our website gets reset on even minor updates of macOS (I don't know about various linux distributions), is likely not to be supported in the next major macOS release, and is undocumented for Windows users.

This has led to the following conclusions on my part:

  • We should change from using SSI to using static site generation from templates so that the in browser help shipped with JMRI is navigable in browser (like when a user can't start JMRI and opens help/en/index.html )
  • We should have only one sidebar for all help content and it should be the Table of Contents for all help content (its easy to use CSS and a little javascript to allow the user to show or hide the TOC
  • We should move our local help content from JavaHelp to being displayed in the browser
  • We should switch from writing documentation in HTML to using AsciiDoc, as GitHub and some IDEs can do a live preview of this (AsciiDoc instead of Markdown because AsciiDoc has useful documentation-oriented features that Markdown does not)
  • We should investigate search mechanisms that work in the browser and implement one
  • Once we migrate to Java 9+, we should evaluate using Apple's help viewer on macOS

I have begun working on the infrastructure to switch from SSI to using static site generation using AsciiDoc or Markdown or HTML as the source format, Freemarker as the templating engine, and JBake as the build tool (but don't have it PR ready yet).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609799871, or unsubscribe <

https://github.com/notifications/unsubscribe-auth/AAIIL55ILR6IHVINFHXFCD3RLHLM3ANCNFSM4GSHBT4Q

.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609928015, or unsubscribe < https://github.com/notifications/unsubscribe-auth/AAIIL557ZF6EYTRXC7R7N5DRLIFX3ANCNFSM4GSHBT4Q

.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-609947491, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL57VWPYKR7WPPDRW5JTRLIKCJANCNFSM4GSHBT4Q .

rhwood commented 4 years ago

Gentlemen:

I am likely not qualified to comment on the technical parts of this discussion, but as someone who has been updating help/web content (and using it extensively myself), I can comment on some of Randall’s proposals:

  • ‘We should change from using SSI to using static site generation from templates so that the in browser help shipped with JMRI is navigable in browser’ My comment: would this also have a mechanism that I could use as a writer/maintainer of help files who does not run a development environment or a local web server? That would make it possible to see formatting changes before submitting them as PR’s.

This would make formatting changes easier to see as a concern for a writer, both within GitHub (the GitHub can preview AsciiDoc as a formatted document (albeit with GitHub’s formatting rules), and renders AsciiDoc files when browsed online[1]) and on a local change without having to install additional build tools.

  • ‘We should have only one sidebar for all help content and it should be the Table of Contents for all help content’ My comment: I don’t agree with this. As you may have noted, I have now put a link to the TOC and WebIndex at the bottom of sidebars throughout the site (if I missed any, let me know). OTOH, content of the sidebar is somewhat more specific to the web pages being displayed, sometimes just by category (e.g. hardware, tools, apps) and sometimes with the addition of a “local part” at the top of the sidebar that serves as additional navigation on the topic. The way I have now designed and set up Sidebar.shtml (in the many individual places it occurs) with included parts makes this very easy to do, but also very consistent and easy to maintain. I believe this make the help system easier to use. In my opinion, having a sidebar that is just the TOC doesn’t add to the user experience versus the link I have now put in.

The “sidebar” in the current help in JMRI is, by default, the TOC. If we switch from using a specialized help system to a browser, we need to retain that prominent and immediate access to the TOC, since it is the curated list of help topics. (I haven’t seen another help system that displays “sub-TOCs” that are not wholly part of the full TOC.)

In addition, we need to allow the sidebar to disappear when a user is attempting to view the help beside that part of JMRI she is reading the help content for and to allow for toggling between the TOC and content without requiring the user scroll through other content to find the TOC.

  • ‘We should move our local help content from JavaHelp to being displayed in the browser’ My comment: I almost exclusively look at content in the browser. I hope/suspect that even people without internet connection have browsers so could do the same.

That is an assumption being made in this discussion.

  • ‘We should switch from writing documentation in HTML to using AsciiDoc, ...’ My comment: I don’t know about AsciiDoc per se, but I would certainly like to be able to write HTML in some higher level editor. MS Word translates to HTML but that has so much to change that it is hardly better than just using Notepad++ and coding the tags manually.

See the examples I provided. The intent is have something that both complete and readable as edited and easily and automatically transformed into a final rendered state (be that HTML, PDF, ePUB, etc…) There should be zero manipulation of HTML tags to adjust formatting.

  • ‘We should investigate search mechanisms that work in the browser and implement one‘ My comment: for anyone connected to the internet, the current google search works fine. Even for those who are running JMRI on a non-internet connected machine, chances are they have a smart phone or other device handy to look something up if they need to.

We have a hard and inescapable requirement that help be accessible without Internet access. I am proposing that we attempt to relax for a short period of time so that any project to change how we present help does not get bogged down in having to be a complete change in a single PR.

[1]: For an example, see the rendered AsciiDoctorJ README and its raw source — while that is a complex AsciiDoc example, it illustrates GitHub’s rendering of AsciiDoc to HTML

rhwood commented 4 years ago

I should clarify: I am concerned only about having the TOC for the help content be prominent in the help content, not about having a single sidebar for the entire JMRI site.

I really don't need there to be links the "Contents" and "Index" for the "JMRI Web Site" throughout the website, especially when those links are not to a TOC or the Index for the JMRI web site.

rhwood commented 4 years ago

Randall, You eloquently state that the current doc/help system is on its last legs and needs to change. You also point at a desirable end state of "a static html site" that can be served by a local-to-JMRI help system that does not require end users to have an internet connection, possibly in conjunction with native Win, Linux an Mac help systems... You will find absolutely no disagreement from me there. My focus is on the associated costs of/to the build system that creates those delivered-to-the-user bits. There are several venn diagram circles here - end users, buildmasters, developers, doc writers, .... and not all need the same type of solution. Case in point, while the end user shouldn't see any disruption based on this conversation, help system developers might have to change how they do things (either with new code or new tools...), and the build system that creates the end user packages for download will certainly change. This is true however this conversation ends. Your objections seem to come from the perspective of JMRI developers who build their own "help/web" docs, and the concern that they might need to install updated build environment tools. Mine comes from the maturity and complexity of the tool chain used to implement this change... OK, so lets quantify the cost of updating a build environment in both scenarios; The tradeoff - to me - looks like this Jekyll: Pro: Has all the completed, production quality tooling, structure, support and templates in place, ready to install and use today. If configured as part of the JMRI GitHub repo, this could extend to using the built-in-to-github doc system with a forked JMRI repo and get the build and test environment f'or free'... Jekyll: Con: For local-only development, need to do a 1-time install of a Ruby-based infrastructure locally, which might include a compiler Randall: Pro: uses JMRI/JVM tool chain Randall: Con: requires the invention of a new Java based help system toolchain, tools, libraries, templates and structure from mostly-scratch, because the rest of the world has moved on/away from pure-Java based documentation solutions. Again, for me, your milage will obviously vary, the metric is Cost(install Ruby) -vs- Cost(invent new tools, toolchain, code, templates) + Cost(bugs in new toolchain/code/templates) + Cost(time to implement/deploy) With my sample size of 1, and Dunning Kruger firmly on my side (humor!), I'm absolutely convinced that inventing, building and maintaining a new pure Java environment solution is orders of magnitude harder/costlier than reusing an existing, production quality framework like Jekyll/Liquid, even if it requires a dozen JMRI developers to install Ruby and learn how to type "make" :-) -John On Mon, Apr 6, 2020 at 11:00 AM Randall Wood notifications@github.com wrote: …

Show me how embedding Jekyll into the process of building the JMRI application would be easier than embedding JBake in that same build process.

At this point, by every argument you present, Jekyll is a worse solution that the pure-Java JBake solution.

jerryg2003 commented 4 years ago

Randall:

Thanks for your explanations. I think I understand better the distinction you are making between the current Help System and the Web Site, although of course the source is the same set of files. If I now understand correctly, the Help System and the Web Site would indeed be the same once we move to a new system where the Help System is displayed in a browser. I agree with that as there really isn’t any reason for them to be different that I can see.

As to AsciiDoctorJ examples, unfortunately I’m more confused by the examples. In fact, I could not understand their most basic installation instruction! As in:

“ To start using AsciidoctorJ, you need to add the required dependency to the dependency management system of your choice, Maven, Gradle or Apache Ivy. If you don't use a Dependency Management system please check the dependency graph and add all jars in it to your classpath.”

Makes no sense to me at all (remember that I’m just an HTML documentation person, not a Java developer).

Finally, as to your additional comment, I can (because of my changes to the strategy for Sidebar.shtml) change “JMRI Web Site” to “JMRI Help” with a single line change to an included part (which I will do). Note also that the TOC and Index are somewhat out of date since they require manual updating when Help/Web content Is changed. It’s on my ToDo list but hopefully others will look at it too.

Thanks again for listening (and explaining) to this novice, Jerry

rhwood commented 4 years ago

The point is not that you need to install that tool, its that the readme (while being a complex example) is in AsciiDoc (and can be read as plain text once you skip over their headers), but is rendered as HTML in GitHub.

bobjacobsen commented 4 years ago

I've been away from JMRI for 10 days, catching up on this discussion. May have missed some details.

Two things:

rhwood commented 4 years ago

I’ve looked for a Java servlet that handles SSI and haven’t found one; nor do I want to write one. There are servlets that can do other live formatting techniques. The Java standard equivalent of SSI is JSP.

The advantages of using static content over SSI or other live formatting are:

The advantage of using a static formatter is that we get the advantages of (most) live formatting with the advantages of static content.

Sent from my iPhone

On Apr 8, 2020, at 10:59, Bob Jacobsen notifications@github.com wrote:

 I've been away from JMRI for 10 days, catching up on this discussion. May have missed some details.

Two things:

JMRI now has a web server. I wrote the instructions in the development pages for recreating our production server so that developers could have that locally. But that's not needed for viewing the help pages because the internal JMRI web server could do it. It could do it particularly well is support for SSI was added to it. (There's also a bit of PHP when browsing the resources/ tree, but that's not part of the local help)

Could somebody please explain the advantages of static web site content over content that is dynamically constructed by e.g. using includes via SSI? We switched from a static-edit-every-file site to a static-after-Perl-scripts-merge-includes site in 2004 (John Plocher did that setup and also added CSS, which was a huge improvement!) Having separate files that were (statically, by a tools pass) included was a Huge Step Forward because things like footers and sidebars could be edited just once. But there was another HSF when SSI came along (2008?) and we didn't have to run the static Perl step before committing updates for the web site. What's the value of having a manual step, i.e. of not having includes done automatically? (When I first started using BCPL, there was a separate 'merge includes' program and step; part of the delight the first time I used C was that compilation was quick and friendly because all the separate steps were automatic)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

plocher commented 4 years ago

TL;DR - Jekyll and JBake (and others) are all static-after-tools-pass systems, similar to what I did with SSI and perl, but different tools and better templating support.

The only "tension" here, and I freely defer to Randall's boots on the ground judgement and decisions here, is which "tools system" to run with. IMHO, Jekyll is very widely used and supported natively by Github's pages doc system, while JBake feels (N.B. I have not used JBake!) to be more of a lift.

-John

On Wed, Apr 8, 2020 at 7:59 AM Bob Jacobsen notifications@github.com wrote:

I've been away from JMRI for 10 days, catching up on this discussion. May have missed some details.

Two things:

-

JMRI now has a web server. I wrote the instructions in the development pages for recreating our production server so that developers could have that locally. But that's not needed for viewing the help pages because the internal JMRI web server could do it. It could do it particularly well is support for SSI was added to it. (There's also a bit of PHP when browsing the resources/ tree, but that's not part of the local help)

Could somebody please explain the advantages of static web site content over content that is dynamically constructed by e.g. using includes via SSI? We switched from a static-edit-every-file site to a static-after-Perl-scripts-merge-includes site in 2004 (John Plocher did that setup and also added CSS, which was a huge improvement!) Having separate files that were (statically, by a tools pass) included was a Huge Step Forward because things like footers and sidebars could be edited just once. But there was another HSF when SSI came along (2008?) and we didn't have to run the static Perl step before committing updates for the web site. What's the value of having a manual step, i.e. of not having includes done automatically? (When I first started using BCPL, there was a separate 'merge includes' program and step; part of the delight the first time I used C was that compilation was quick and friendly because all the separate steps were automatic)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/JMRI/JMRI/issues/6497#issuecomment-611009173, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIIL55S2K247J42MQO64STRLSGMTANCNFSM4GSHBT4Q .

stale[bot] commented 3 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. JMRI is governed by a small group of maintainers which means not all opened issues may receive direct feedback.

stale[bot] commented 3 years ago

This issue has been automatically closed due to lack of activity. In an effort to reduce noise, please do not comment any further. Note that the maintainers may elect to reopen this issue at a later date if deemed necessary.