Proposal to use the Issues functionality here to track migration of legacy LMS embedded Help pages
Daksol opened this issue · 19 comments
Recent discussion in forums indicates that we should be planning to migrate the HTML Help pages which were embedded in the LMS distribution to this new Lyrion.org repository.
These pages linked on any LMS install via base url: http://lms-server:LMSPORT/html/docs/
There are about 15 of these pages, excluding menus, of which one has been done.
The content of each page does need a bit of thought:
- if info is up to date does this go to its own new page, or merge with page already migrated from the legacy wiki
- if info obsolete do we just not migrate it - or do we set up a graveyard (as per separate discussion about obsolete plugins).
So proposal (following up other discussions with @Lauret etc) is:-
- to create a separate Issue for each of these files.
- we can discuss best option
- someone can allocate themselves the task
- and once page is migrated the issue can be closed.
This will generate a few issues; on other hand the discussions should be short and easy to follow.
Hope this sounds ok. Respond asap if not!
HELP MENU
- remote.html - Remote Control Reference This is about Infra Red remote controls
- remotestreaming.html - Remote Streaming
- softsqueeze/index.html - SoftSqueeze - Now a short page, mostly just links, link label and page title better 'Software Players' perhaps
TECHNICAL INFORMATION MENU
- artwork.html - Artwork Setup
- radio-compatibility.html - Squeezebox Radio & Logitech Media Server 8+
- http.html - The Logitech Media Server Remote Control This is mostly about how to use the CLI, not about Infra Red remote controls
- cli-api.html - The Logitech Media Server Command Line Interface - DONE
- skins.html - Skin Creation The page says it is out of date
- xpl.html - The Logitech Media Server xPL Interface
- plugins.html - Logitech Media Server Plugins
- buttons.html - Button Mapping
- input.html - Input Modes
- fonts.html - Font Files
- display.html - Display API
- slimproto.html - The Squeezebox Client Protocol
Excellent initiative! I've created a project at the org level: https://github.com/orgs/LMS-Community/projects/2/views/1. Can you access that? Please add all the issues you create to that project. As it's not limited to this repository it also allows us to create issues on slimserver to remember to clean up the links etc.
Link you have provided gives me a 404 error.
I can see https://github.com/orgs/LMS-Community/projects
But this shows only a single project, The Great Renaming Project.
(I had created a couple of HTML doc migration issues here just to indicate what I was suggesting. Once I get access to your new project I will close the issues here and recreate them in that location).
You should have received an invite by now. And no need to close these issues: they can be assigned to the project!
Yes I have access now. And I see that the issues created here (LMS-Community/lms-community.github.io) are showing there,
One more small info. Not familiar with this Github project mechanism. What option does one use to create an item in the Project directly?
Haven't used this before, either... It's a relatively new feature on Github.
At the bottom of the columns there's an 'Add Item' button. Those items later can be converted to issues in the various repositories.
Not seeing an Add item button so far on the Projects page.
You have to accept the invite you received.
Invite accepted, pages refreshed. Sorry, still not seeing the add button.
You had to accept the invite before I was able to add you to the project. Which I now did. Better?
Got it now!! thanks.
It is very joined up. I created a new item in the Project for the Remote Control reference page.
I then allocated it to a Repository (lms-community.github.io )
And it (magically) created an Issue here in the lms-community.github.io repository.
That is probably the right way round to do things - because there will be issues raised in the lms-community.github.io repository which will NOT necessarily be part of the documentation cleanup project.
@terual @mherger
I have now created an Issue for each of the unmigrated pages in the legacy HTML docs.
Some already have been assigned and moved to the in progress category.
However there remain a few which (IMHO) need people with much deeper knowledge to check before they get worked on.
Could I ask that you open these issues and add a comment to confirm that the migration proposed is ok etc.
Thanks
@terual - I think these two can be merged into material you already migrated
-
Legacy-HTML migration: Squeezebox Radio & Logitech Media Server 8+ radio-compatability.html Open issue 32
-
SlimProto TCP Protocol Open issue 33
Could you make a quick comment into each of these in order to confirm that the material is appropriate to migrate
- Plugins Open issue 35
- Display API Open issue 39
- Font Files Open issue 38
- LMS Web interface (CLI via http commands) Open issue 40
- Input Modes Open issue 37
- LMS xPL Interface Open issue 36 - quick Googling showed a UK site declaring XPL project closed in 2016, but maye some other way forward?
This one is labelled as being out of date. What to do with this page? Have a special "obsolete information" section?
- Skin Creation Open issue 34
Proposal for handling material from this /docs/html area we are not going to migrate.
We now have an Issue for each chunk of not-migrated content which is documenting the decision not to migrate. And that Issue would be a good place to hang things, so to speak.
So to wrap up such items, something on these lines:-
- ONE:- make a posting to the non-migrated content chunk's Issue which includes an attachment containing the actual HTML (An alternative might be to include a permalink to the relevant file within an appropriate release of the code repository, but tbh that seems like more work to produce something less helpful, and works less well for situation like the CLI docs where only specific portions of source file were not migrated).
- TWO:- add a tag "Not Migrated - Content from LMS distro /html/docs/"
- THREE: Close the Issue
That would make it pretty easy for any future retro-tech historian to review the backwaters of the technical legacy.
Sound ok?
Thanks a ton! I've commented on most of them, but haven't taken any decision or other action yet. What you suggest makes sense. Though I would go with a permalink, rather than copy/paste of content. The link doesn't need to be tied to a release, just whatever is in there before we remove it.
OK. will do a Permalink as standard. Tho I would suggest the CLI sufficiently complex that it would warrant the actual unmigrated content (as an attached file, not code pasted in).
but why copy content, when a link would point at the exact same? The presentation in the linked document would be infinitely better than when pasted here.
Take your point wrt most situations - links to LMS v8.5 included.
Thought an exception worth making for the unmigrated sections cli-api.html given that it is 13,000 lines or so, quite an expedition to get one's head around.
Target locations for migrated material which is not part of the mainstream current generation of kit, protocols etc
Material which is essentially OK, but related to legacy kit etc
- Target in document tree: /reference/development/legacy
- Include a short explanatory page in /reference/development/legacy explaining that content in this section mostly of historical use, relevant to Boom/Transporter/Classic, the ip3k based UI
- Examples will include:-
- Display API
- Input Modes
Material which is being retained, though needs to be udpated
- Target in document tree: /reference/development/to-be-updated
- Short explanatory page in /reference/development/to-be-updated explaining status of material in the section
- Examples will include:-
- Plugins