Should there be a manpage for `gsh`?

[phyver]

It could be installed somewhere and MANPATH be updated.
(POSIX specifically mentions this variable is not standardized but that many system use it...)

[rlepigre]

Sounds like an easy enough thing to add!
We could even think about replacing gsh help by man gsh (not sure that is a good idea though).

[phyver]

I'd prefer keeping gsh help, but a manpage could replace gsh HELP.

[rlepigre]

Indeed, good idea!

[Aierbote]

Maybe it's a bit off topic, but I was wondering what was the difference between gsh help and gsh HELP

I hope there will be soon a man gsh, becasue I've already checked it on my own before reading this.

[rlepigre]

Both gsh help and gsh HELP show you a list of available commands of the form gsh <command>. The difference is that gsh help lists commands that are useful to play the game, while gsh HELP lists all available commands. Some commands are not intended to be used by the player, for example commands that skip a mission (it can be used in a teaching context when a student is stuck for too long, or when there is a bug in a mission that makes it unsolvable) or that are useful for debugging.

[phyver]

What would you put in the man page?
. The equivalent of gsh help,
. the equivalent of gsh HELP,
. the equivalent of bash gameshell.sh -h,
. all of the above?

Putting everything makes sense, but for newcomers, that will be too long.

The output of ./gameshell.sh -h doesn't really make sense on its own, as this man page will only be accessible from inside GameShell, when you're not supposed to run another version of GameShell.

Maybe just the equivalent of gsh help, with the addition of a description of gsh HELP?

[rlepigre]

Maybe we want more than one man page? One that is intended for users (accessed with man gsh and containing roughly the same thing as gsh help), and one that is more complete (accessed with man gsh-commands or something similar).

[rlepigre]

But in all cases, we want to share as much text as possible to avoid too much duplication when translating the game.

[phyver]

@rlepigre, @Mte90 and anyone reading this...

I just pushed some commits on the devel branch with a first version of a manpage for gsh, generated with asciidoc. It mostly contains the same information as the gsh HELP command but tries to follow standard manpage style.

I would welcome any remark, comment, criticism, idea or suggestion about it.

If you pull the devel branch, you can simply run

  $ man ./man/man1/gsh.1

from the root of the repository. (Note that I regularly force-push on this branch!)

The output of gsh HELP is generated at the same time and can be found in the files /i18n/gsh-full-help /{en,fr}.txt. (The Italian version is, hasn't changed at this time...)

There also is a manpage for gameshell.sh, but that's not very relevant for a player inside a GameShell session. It is intended to replace the doc/gameshell.md file at some point... A pure text version is also in ./i18n/source/gameshell/en.txt.

[Mte90]

Can you just ping when it is time to localize as it is finished?

[rlepigre]

@phyver I had a look and this looks pretty good. I have not read the full contents really carefully, so there might be typos. Actually I just remembered one: "where it was left of" should be "where it was left off" I believe. I like the idea of using a manpage for gameshell.sh to replace doc/gameshell.md (or at least generate both from the same sources).