fix #277903: new manpage #4265
fix #277903: new manpage #4265
Conversation
|
https://musescore.org/en/node/277903#comment-872505 has a preview of how the new manpage looks, to ease review. |
|
Nice job! It would be great if the online handbook's command line options page simply rendered the latest version of the man page from the repository, like CMake's does. |
|
Peter Jonas dixit:
Nice job!
Thanks!
It would be great if the online handbook's command line options page
simply [rendered the latest version of the man
page](https://stackoverflow.com/a/13434016) from the repository, [like
I’ll have to talk to someone (thomasbonte?) about what Drupal can do.
mdocml makes for a better converter to HTML than GNU groff; in MirBSD
we use regular nroff plus a set of regexes to convert from catmanpages
to XHTML, so we have at least three possible ways, if not displaying
the rendered PDF version inline, or just linking to (for example)
https://manpages.debian.org/unstable/musescore/mscore.1.en.html
(Yes, I already ship the new manpage in Debian. Hm, the options there
look ugly in lynx, but looking at the source code it’s obvious why,
they’re using block-level elements, but styled with CSS it should
look alright).
On the other hand, the manpage currently (both old and new) links to
the handbook page for “further reading”, in case options are explained
there in more detail. Perhaps we should then remove that and just en‐
sure that the manpage is kept up to date (I can have an eye on it, I
have massive practice writing them, almost two decades).
This would also work better for having different versions around, as
every version has its own manpage, and we can easily document in the
manpage much more verbosely (as you have seen me do for the new -j
option from PR 4166).
|
|
A short term solution might be to convert to Markdown (possibly via HTML) and just paste that into the handbook.
The solution to this could be to have the latest development version in the developer's handbook and the latest stable release in the ordinary handbook. Or we could do what CMake do and make every version available (see the dropdown in the top-left). |
mirabilos
force-pushed
the
new-manpage
branch
from
205f0ab
to
322204f
Compare
|
Hmm. https://musescore.org/en/handbook/command-line-options contains a couple things more I cannot or won’t map in the manpage:
It also contains some of the automatic QT command line options. @shoogle how about I just keep these two in sync manually? Perhaps using the Markdown output of mdocml as a base, but integrating the handbook-specific things. I’ve updated the PR with some information found on https://musescore.org/en/handbook/command-line-options I did not yet have in the manpage (very minor things only). |
I'd be more than happy with this! The automated updates was more of a wish than a serious suggestion. By the way, if we did go down the automation route, platform specific options could be documented or commented out using CMake's |
|
Peter Jonas dixit:
> @shoogle how about I just keep these two in sync manually? Perhaps
> @using the Markdown output of mdocml as a base, but integrating the
> @handbook-specific things.
I'd be more than happy with this! The automated updates was more of a
wish than a serious suggestion.
OK.
By the way, if we did go down the automation route, platform specific
options could be documented or commented out using CMake's
`configure_file()`, [as is
We’re already using this. But a Unix manual page has a somewhat defined
“scope”, such as, that the executable is already in $PATH. I believe it
is better to use a different “format” of documentation for Windows users
(which can link to the manpage or rather the handbook page just as well,
or even _be_ the handbook page), especially given that there’s normally
no mandoc formatter or manual page database on Windows systems, so I’d
definitively *not* add this to the manpage.
|
I'm more interested in putting information in the most logical place, and preferably all in once place, rather than how things are usually done. It makes no difference to me whether the Unix man page is generated from the handbook or the handbook generated from the man page, as long as there is one definitive source of information about command line usage, rather than two conflicting sources as there are now. Windows users would obviously use the online PDF/HTML version rather than a local version. But I should have been more clear when I said "there is room for a how-to [...] that is separate to the manpage, but they can stay together for now". When I said that I wasn't suggesting you should put the Windows information in the man file right away. All I was saying is that when you paste Markdown into the Handbook you can leave the Windows stuff intact at the top, but if we ever do decide to automate the process then the Windows stuff will need to go either in the manpage itself, or on a separate page in the Handbook, so it doesn't get overwritten each time the script runs to update the Unix documentation. |
|
No need to auto sync. A manual sync is fine and also link from the handbook
to the manpage.
|
|
@shoogle that’s close to what I was planning, ok, so we use different words but seem to mean roughly the same thing ;-) @thomasbonte ok, works for me |
mirabilos
force-pushed
the
new-manpage
branch
from
322204f
to
0297e34
Compare
|
Need to extend this, due to c63d1c4 |
mirabilos
force-pushed
the
new-manpage
branch
from
0297e34
to
0bf6540
Compare
|
Extended it with the new options. |
mirabilos
force-pushed
the
new-manpage
branch
from
0bf6540
to
1d084b8
Compare
|
I’ve updated Handbook 3: Command line options with this… it was massively manual editing work because MuseScore.org does not implement Markdown correctly. Manually keeping them in sync, it is, then. |
mirabilos
force-pushed
the
new-manpage
branch
from
1d084b8
to
504b32e
Compare
mirabilos
force-pushed
the
new-manpage
branch
from
504b32e
to
8352976
Compare
|
In sync with 3.0.1 (plus PR #4166 ) now |
mirabilos
force-pushed
the
new-manpage
branch
from
8352976
to
0985e57
Compare
|
That manpage can't get synced with the online manual, because the latter needs to cover Windows and Mac too, not just Linux, like the former does |
mirabilos
force-pushed
the
new-manpage
branch
from
0985e57
to
ea0a4d4
Compare
|
It would actually be possible to extend QCommandLineParser and have it generate a manual directly from the C++ source code. This way it would always be up to date, and it would even be fully translatable via the existing translation infrastructure. It would take a bit of effort to setup though, so it will have to wait for another day. |
|
Peter Jonas dixit:
It would actually be possible to extend
[QCommandLineParser](https://doc.qt.io/qt-5/qcommandlineparser.html)
and have it generate a manual directly from the C++ source code. This
For a manual, perhaps.
In Debian, Policy still requires a regular manpage, and I take some
pride in actively maintaining them instead of just doing the equi‐
valent of “foo --help | help2man >foo.1” (which looks absolutely
ugly and often lacks sufficient information).
So I postulate that that is out of the scope.
Windows is out of the scope of this *anyway*, Jojo; we already
agreed to maintain the handbook page separately (although most
of the info in the new manpage and its structure is merged).
|
|
A proper implementation would extend But I agree that is definitely out of scope for this PR. |
|
Joachim Schmitz dixit:
So which Linux uses `musescore` rather than `mscore`?
All of them, MuseScore installs itself under both names,
and mscore used to be used by the 1.x versions, whereas
as of 2.x people use the musescore command.
|
|
@anatoly-os ping? |
mirabilos
force-pushed
the
new-manpage
branch
from
ea0a4d4
to
3356c0e
Compare
|
ping? |
|
@anatoly-os ping? |
|
I believe Anatoly is working through the PRs primarily in order, oldest first, as there are still some open from November and before. BTW @mirabilos, you should definitely join the MuseScore Telegram chat as that's where all discussions take place now. It's actually really busy - almost too busy in fact, but fortunately you can disable all notifications except when someone @mentions you, a bit like in IRC. It's open source and works on mobile too, plus there is no spam. |
|
Peter Jonas dixit:
I believe Anatoly is working through the PRs primarily in order,
oldest first, as there are still some open from November and before.
It appears “newest first” to me, but, okay.
BTW @mirabilos, you should definitely join the [MuseScore Telegram
chat](https://t.me/musescoreeditorchat) as that's where all
Absolutely not. It asks for my PHONE number, and wants to install
all kinds of software. (Also, I never chat on mobile, I can’t stand
those small keyboards and only have 100 MiB/month traffic.)
|
|
There's a desktop client for telegram too |
|
The phone number thing is a bit of a bummer but it does prevent people from creating lots of fake accounts and spamming everywhere like in IRC. If you value privacy Telegram has end-to-end encryption in secret chats (though not in public chats for the reasons explained here). It's basically an open source version of WhatsApp. |
|
Peter Jonas dixit:
It's basically an open source version of WhatsApp.
Which I also never used. (Incidentally, thanks to the EU-DSGVO/GDPR,
I can (and do) legally forbid people who have that installed to store
my phone number on their smartphones. Are you saying Telegram does
that, too?)
IRC works for me, and I know for a fact that enough developers still
hang around in IRC, so it’s easy enough to keep everyone informed.
(Enough is currently 3 developers and a few contributors, but there
are more on the occasion.) IRC is also where the GSoC hopefuls still
come to. Plus, the IRC presence is not going away, even if it gets
less used. The spamwaves also have stopped.
|
|
@dmitrio95 could you please review and give your opinion? |
There was a problem hiding this comment.
The new manpage looks great, thanks @mirabilos!
I left just one question regarding MuseScore directories placement, maybe the listed path needs a correction.
|
Dmitri Ovodok dixit:
This renders for me to `~/MuseScore3/` but the actual directory for
that data has always been `~/Documents/MuseScore3/` for me (on Debian
Oh, interesting. For me, it’s ~/MuseScore3/ but…
9). Is the `Documents` part missing here or does MuseScore really
place its data directory directly to the home directory in most common
cases?
if that’s the case, I know exactly where it comes from:
$ fgrep DOCUMENTS ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs
XDG_DOCUMENTS_DIR="$HOME/"
With this information I’m able to update this with the correct
information. I’ll do so after the weekend (probably not before
Tuesday) because I’m at a conference, though.
(I’ve, interestingly enough, never run MuseScore on a system
that did not have the above config file, although this was
not deliberate.)
|
Completely rewritten manpage, with improved documentation for most aspects of the program, and documentation of the better batch con‐ version (see PR 4166). The new mscore.1.preview.sh shell script is intended to be used for previewing changes, by developers.
|
@dmitrio95 fixed and rebased, thanks for the review! |
|
@anatoly-os ready for merge? ☻ |
Completely rewritten manpage, with improved documentation for most aspects of the program, and documentation of the better batch conversion (see PR 4166)
Fixes: https://musescore.org/en/node/277903