Manual page

[vv221]

Currently julius does not provide a manual page. But I see there are already some usage instructions:

INFO: Usage: julius [ARGS] [DATA_DIR]
INFO: ARGS may be:
INFO: --display-scale NUMBER
INFO:           Scales the display by a factor of NUMBER. Number can be between 0.5 and 5
INFO: --cursor-scale NUMBER
INFO:           Scales the mouse cursor by a factor of NUMBER. Number can be 1, 1.5 or 2
INFO: --windowed
INFO:           Forces the game to start in windowed mode
INFO: The last argument, if present, is interpreted as data directory for the Caesar 3 installation

I can write basic manual pages based on this, both a default page in English and a localized one in French.

In addition to the command usage and the command-line switches, it could include information on the ~/.local/share/bvschaik/julius/data_dir.txt path used to set the path to Caesar 3 data files. And maybe some information about the need to run julius once from a terminal the first time, so it can prompt for this path, before the .desktop menu entry can be used.

While I can provide these files (and would obviously keep them updated if you add new command-line switches, as long as you give me a ping so I don’t miss them), I don’t really know how to work with CMake so for now I would not know how to include them in the list of files to install. I could provide the manual pages and let you integrate them into the installation process, or if you have some time to explain how it works I would be happy to handle this part too.

[crudelios]

Just a heads-up: it's possible you don't need to run Julius from the command line on your first run.

It should display a folder select dialog.

If it's not working then it's likely a bug of some kind, which I'll be more than happy to help fix.

[vv221]

It should display a folder select dialog.

I don’t get that, so something might be wrong indeed. I’m going to open another issue about that, so we can keep this one focused on the manual page.

---

Done, cf. #741.

[crudelios]

Since the #741 bug is not really a bug, I'm guessing the manual could mention that a select folder window should appear and if nothing happens the game should be run from the console so the directory can be picked.

[vv221]

the manual could mention that a select folder window should appear and if nothing happens the game should be run from the console

Yes, if I had this information I would not have thought the .desktop launcher was broken in some way. So it sounds like an useful piece of information.

Most users would not need this information, but the ones not having a supported GUI dialog alternative available are most probably the ones that are the most likely to read a manual page too.

[bvschaik]

I briefly looked into creating a man page: it sounds like quite a bit of hassle for not much benefit. Personally, I tend to go for --help before consulting a man page...

Considering you now have the dependencies set up to install tkinter so the select folder dialog is shown, do we still need the man page?

[vv221]

I briefly looked into creating a man page: it sounds like quite a bit of hassle for not much benefit.

The syntax is a pain to learn, I don’t suggest you go that way if you don’t need it outside of julius.

But I already know how to work with it, so for me the effort would be much lower. My proposal obviously include this page maintenance afterwards, not only its initial writing.

---

Personally, I tend to go for --help before consulting a man page...

I should report a bug about this one too, as it seems either --help is not really supported or not working as expected.

---

Considering you now have the dependencies set up to install tkinter so the select folder dialog is shown, do we still need the man page?

While it makes its lack less problematic, I still think it would be a worthwhile addition. Especially useful for people not installing the recommended dependencies, so could end up with Julius installed but without any of the path selectors available.

[bvschaik]

I did not even look at the syntax, just at adding it to the build and making sure it ends up where it needs to be. There's no standard way to do it. And we have to basically code a big "if-else" in the cmake file for which platforms need this. Since this is a GUI program and not a CLI one, I want to avoid adding files that are not useful for the majority of users.

--help should print the info you listed in the issue, so what is it doing that you don't expect?

[vv221]

I did not even look at the syntax, just at adding it to the build and making sure it ends up where it needs to be. There's no standard way to do it.

If it’s a pain to include in the build recipes I might include it at first only for the .deb package, and only contribute it back upstream after I find a clean and light way to include it. If there is no way to do that without big changes to the build process, it can stay as a Debian-specific addition.

---

--help should print the info you listed in the issue, so what is it doing that you don't expect?

It prints the usage information as expected, but does not stop here and then prompts me for the path to the game data (clearing up the terminal in the process, so the usage information is no longer shown) if ~/.local/share/bvschaik/julius/data_dir.txt is not already there.

I would have expected it to stop the execution right after showing the usage syntax.

[bvschaik]

If it’s a pain to include in the build recipes I might include it at first only for the .deb package, and only contribute it back upstream after I find a clean and light way to include it. If there is no way to do that without big changes to the build process, it can stay as a Debian-specific addition.

Sounds like a plan.
By the way, the data_dir.txt file is not meant to be edited by users. Julius expects to be the only one writing that file and does not do any error handling on the contents. For example, if you add a \n at the end of the file (like vi does), it will fail to find the directory. If you add anything in the manual about it, it should only be something like "this is where the directory is stored, remove the file to reset".

I would have expected it to stop the execution right after showing the usage syntax.

That's a bit of an oversight on our end. I just fixed that on master.

[vv221]

By the way, the data_dir.txt file is not meant to be edited by users.

OK, I’m going to take that into account and direct the reader to the installation of one of the supported path browsers. With probably an extra warning about not editing this file by hand.

[bvschaik]

@vv221 Any update on the manual page, or shall I close this issue?

[vv221]

I’ve been quite busy lately, so I have no news to share on this front. But this is still on my TODO.

I’m going to write a manual page for Debian anyway, so it would probably be better shared here so it can be included for everyone instead of being specific to Debian.