Which documentation is still current and should be installed? about documentation HOT 10 CLOSED

Should tutorial_*.html still be installed to /usr/share/hydrogen/data/new_tutorial ?

I'm a little bit on the fence regarding those. They are very old. But the overall UX of Hydrogen has been more or less stable throughout the years and they still might help users to get started. (Unfortunately, right now I don't have time to update them and there are plenty of more pressing things to do). In addition, those two translations have sufficient coverage.

Should manual_en.html still be installed to /usr/share/hydrogen/data/doc ?

Yes. It's cutting-edge since 1.2.0-beta1, keeps up with most recent changes, and I'm committed to keep it this way. In addition, it can be directly accessed (viewed) from the hydrogen application itself.

Should the other html files that aren't built from localised source just be ignored and/or removed at this time?

Since I updated the English version of the manual all translations have fallen into despair. They have so few coverage (the biggest one being about 30%) that I do not want to ship them anymore. On the other hand, committed translators wanting the update them shouldn't start from scratch. So, I chose to keep but ignore them.

Finally, is there any reason why the clean target doesn't remove the generated html files?

Excellent question! I removed the corresponding line a couple of years ago since the actual html files are part of the repo and should not get out of sync with their sources. Especially on release tags. But the cleanest solution would be to just remove those artifacts entirely.

from documentation.

from documentation.

I noticed that what appears to be the old tutorial is still being installed
as "/usr/share/doc/hydrogen-doc/new_tutorial"

Oh. I was not aware of this either. Seems there is yet another tutorial present in data folder of the main Hydrogen repo. Weird. I'll have a look at it and move in this repo.

I'm currently updating the Debian packaging to 1.2.2

Is there already a timeline and a date picked at which you should be done? We had a lot of fixes that went into what will become version 1.2.3. And right now there are no open tasks left. So, we could make the next releases pretty soon.

The only thing that is stalling it is that removal of the HTML artifacts from this repo broke the existing toolchain for installing the docs. Previously, HTML files were committed by the maintainers and cmake just copied them during the installation process of hydrogen. Right now, it would require a manual step to cd in the doc sources and make them. But I will integrate that into the CMake files of the main repo soon.

from documentation.

from documentation.

Debugging and fixing documentation-related bugs in a Debian
context has been the biggest time-sink for updating to any version newer
than 1.2.0~beta1

[...]

Oh good, I'm happy to hear you're moving in that direction :) Here's a
patch to 'git am'

https://salsa.debian.org/multimedia-team/hydrogen/-/blob/2d3755e2878e5337d8aefbba3be8ffd0656acd45/debian/patches/0004-Define-documentation-subdir.patch

I've also have to use this, will be fixed by the CMakeLists.txt you're
writing about:

https://salsa.debian.org/multimedia-team/hydrogen/-/blob/2d3755e2878e5337d8aefbba3be8ffd0656acd45/debian/rules#L20-L21

I really hope it is not the poor or outdated documentation in this repo that make you trouble.

The installation of the manual is handled in the CMakeLists.txt file of the hydrogen repo and not intended to be installed directly. It is integrated into the main repo via a submodule.

It also needs to reside in the data/doc folder installed on system level because the hydrogen binary will attempt to access it when clicking Info > User Manual in the main menu (or Ctrl + ?).

That being said, the build chain of the documentation repo is not stable right now. Removing the HTML artifacts does also require using the tools to generate them in our build pipeline instead. For the Linux one this is no problem. But let's see how the macOS and Windows ones will do. The tools required seem to be available, so it should be possible. But whether it will work as expected I can only tell after changing (and properly introducing myself into) the cmake setup.

Finally it would be nice if the following bogus file name could finally be fixed here:

https://salsa.debian.org/multimedia-team/hydrogen/-/blob/2d3755e2878e5337d8aefbba3be8ffd0656acd45/debian/rules#L24

and

https://salsa.debian.org/multimedia-team/hydrogen/-/blob/2d3755e2878e5337d8aefbba3be8ffd0656acd45/debian/patches/0003-use-h2-icon.png.patch

Alternatively, can the new svg be used instead, and thus can the
raster copy go away at this time?

Let me know if you prefer a PR for any of this!

Hmm.. This seems to be something Windows-specific. I have to read into and check with the Windows build pipeline first in order to avoid breaking. This might take some time.

Oh. I was not aware of this either. Seems there is yet another tutorial present in data folder of the main Hydrogen repo. Weird. I'll have a look at it and move in this repo.

The tutorial in the data/ folder is almost identical to the one in this repo. Probably a mistake no one noticed since the sources were ported to git 15 years ago. I will drop it and make this repo the single source of documentation.

Also, I will most probably give it some love and update it so it matches the most recent Hydrogen version.

from documentation.

Hey @sten0,

The installation of the manual is handled in the CMakeLists.txt file of the hydrogen repo and not intended to be installed directly. It is integrated into the main repo via a submodule.

It also needs to reside in the data/doc folder installed on system level because the hydrogen binary will attempt to access it when clicking Info > User Manual in the main menu (or Ctrl + ?).

That being said, the build chain of the documentation repo is not stable right now. Removing the HTML artifacts does also require using the tools to generate them in our build pipeline instead. For the Linux one this is no problem. But let's see how the macOS and Windows ones will do. The tools required seem to be available, so it should be possible. But whether it will work as expected I can only tell after changing (and properly introducing myself into) the cmake setup.

Big news. Porting the toolchain to Windows was such a pain that I draw a line and decided to port the documentation to a Markdown-based one and integrate it back into the web page again in the near future (between 1.3.0-beta and 1.3.0).

I also intend to just bundle and ship it with Hydrogen version 1.2.3 (and further potential 1.2.X) but stop doing so starting from version 1.3.0. Then Hydrogen will not attempt to access the HTML document locally anymore but just opens a browser with the online version.

So, I reverted the toolchain changes and the HTML artifacts are present again (so, I can bundle them in the different build pipelines).

Do you think it is worth the effort to extract a HTML version of the doc from the future web page-based approach? I have the feeling the online version is sufficient these days. (It will allow to access the manual of various versions). So, maybe the hydrogen-doc package can just die too and you save a lot of time. Sorry, in case this means even more work for you.

from documentation.

from documentation.

Ah... Rather than "more work"...truthfully I'm upset that this action
makes the hours of existing work pretty much worthless, and this
demotivates me.

I'm sorry. And I care. That's why I get in touch with you at this very early stage instead of telling you about the transition when it is already done. It wasn't an easy decision either. I spent weeks updating the Docbook toolchain from 4.0 to 4.5 and introducing nicer styling just 1-2.

I guess WSL is no good? If so, the way I would want to mitigate Windows
hell would be to execute a Linux-based "Documentation-PREP" stage in the
build pipeline. That stage would return a zip that would be passed to
the Windows-build-host stage for the actual build of Hydrogen. The next
best thing I'd try would be using Github Releases to include the "HTML
artifacts" (and associated resources) in hydrogen-docs-$release_version
zip files/release tarballs, and then download and unpack that during the
Hydrogen (application) build. Of course there are many solutions, and
once you eliminate bias it's a question of what you value enough to work
towards :)

I totally get where you are going and you named some good and plausible ways to resolve it. But in the end it would made an already unnecessary workflow/toolchain even more complicated. My main problem with Docbook is that it is less intuitive/more difficult to use than Markdown and that Windows users (which make up most of Hydrogen's user base) aren't able to build the docs. This makes a quite high entrance barrier and might keep them from contributing.

For the Windows build I have a AppVeyor pipeline someone else wrote. I'm very grateful for this since I do not know much about Windows. Porting the toolchain to Windows would probably require the same time for me as porting the whole documentation to a modern technology. (Where I do not have to learn XSLT to style a paragraph.)

Hydrogen 1.2.2 is currently in Debian experimental, and I plan to spend
my next window of free time for Hydrogen to add system-managed drumkit
upgrade triggers.

That's great to hear!

It sounds like importing 1.3.x will require:

1. Finding and removing all pre-build docs.

No. Artifacts will be gone after the toolchain update.

2. Readdapting and/or reimplementing the documentation build,
   installation, and integration.

Yes. But this will most probably just be a npm install && npm run build.

3. Ie integration will mean carrying a patch to use a local rather than a
   network copy of the new manual.

Nah. So, when there is a dedicated documentation and a portable, easy-to-use toolchain, I will continue bundling the docs with Hydrogen and you do not have to make further patches.

So, from what I get from your reply shipping the manual/tutorial is essential for the Debian philosophy, right? I think I will switch to e.g. https://docusaurus.io/ and fuse the docs with the web page again (which needs lots of love too). It's probably doable but some work to make just a single version of the doc available via a dedicated repo. Do you think this is worth the effort? (Open question as I never use local documentation resources for software which do also provide an online version)

from documentation.

from documentation.

Yes. But this will most probably just be a npm install && npm run build.

This requires network access, so can't be used to build Hydrogen docs
in Debian.

Well, scratch that. The npm run build would be used to build the whole page and I seem to have mixed things up here.

The thing I liked when skimming over docusaurus was that all content is contained in Markdown files. With some static CSS and JS all it needs to translate the docs into HTML is a tool like pandoc or blackfriday which would be way more easy to use on all our supported platforms than the current toolchain. And maybe the most important thing: the source .md files making up the doc could be separated from the overall page, like our current setup, and use a toolchain when translated into a stand-alone HTML page.

Also, it does not have to be docusaurus in case it does not support all those things above. My main objective is to get rid off our current, obscure toolchain as tweaking with it eats up so much time on my end. When porting is done things should be way more easy and straight-forward for both of us.

Debian supports off-grid users, and access to offline documentation is a
practical concern for these users, so we provide offline documentation.
Isn't this a scope question more than a philosophy question?

That said, yeah, I see how it becomes an ethical question if one says
that users have a[n aspirational] right to offline documentation, to
documentation and access to computing in one's mother tongue, to all
necessary accessibility features needed to mitigate [partial]
disability. Very few, if any, people can get any work done while
thinking of all this at once, so it's good enough to chose a modular
and extendable solution.

That's really nice! I don't want to change this (well, this thread is going on for quite a while, so, maybe I did want to at some point (?) but definitely not anymore).

Speaking of accessibility: would it be better to provide the plain .md files, a styled HTML, or both? E.g. a visually impaired college of mine always prefers plain text files.

You'll probably also want some kind of internationalisation
and string substitution support. Then you'll want some kind of
middleware to transform your source into a web site with minimal effort.

That's true. Although there is currently not a single translation of the manual. But it grew to such an intimidating size I totally get why no one attempts to translate it.

from documentation.