Skip to content

Commit 9c17b22

Browse files
phyverphyver
committed
testing asciidoc to generate a manpage, the help and HELP commands
1 parent dd6f09d commit 9c17b22

File tree

20 files changed

+1011
-48
lines changed

20 files changed

+1011
-48
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ TODO
88
.save
99
World
1010
locale/
11+
man/en
1112
*~
1213
/gameshell*
1314
game shell*

‎i18n/gameshell-commands/Makefile‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
all: en.1 en.help en.HELP
2+
3+
%.txt: %/*.txt
4+
awk -f make_man.awk $*/man_gsh.txt > $@
5+
6+
%.1: %.txt
7+
a2x --doctype manpage --format manpage $<
8+
[ -L ../../man/en ] || ln -sf ./ ../../man/en
9+
cp gsh.1 ../../man/man1/
10+
mv gsh.1 $@
11+
12+
%.HELP: %/*.txt
13+
awk -f make_man.awk $*/gsh_HELP.txt | sed -f clean.sed > $@
14+
cp $@ ../gameshell-full-help/$*.txt
15+
16+
%.help: %/*.txt
17+
awk -f make_man.awk $*/gsh_help.txt | sed -f clean.sed > $@
18+
cp $@ ../gameshell-help/$*.txt
19+
20+
clean:
21+
rm -f *.1 *.html *.txt *.help *.HELP ../../man/en
22+
23+
.PHONY: clean all

‎i18n/gameshell-commands/clean.sed‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/sed -f
2+
3+
# remove trailing '::' for asciidoc's descriptions
4+
s/::$//
5+
6+
# replace leading tabs used by asciidoc's descriptions by spaces
7+
s/^\t/ /
8+
9+
# remove asciidoc's bold
10+
s/\*\*//g
11+
12+
# remove asciidoc's italic
13+
s/__//g
14+
15+
# remove trailing ' +' for asciidoc hard linebreaks
16+
s/ +$//

‎i18n/gameshell-commands/en.1‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
'\" t
2+
.\" Title: gsh
3+
.\" Author: [see the "Authors" section]
4+
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5+
.\" Date: 11/19/2024
6+
.\" Manual: \ \&
7+
.\" Source: \ \&
8+
.\" Language: English
9+
.\"
10+
.TH "GSH" "1" "11/19/2024" "\ \&" "\ \&"
11+
.\" -----------------------------------------------------------------
12+
.\" * Define some portability stuff
13+
.\" -----------------------------------------------------------------
14+
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15+
.\" http://bugs.debian.org/507673
16+
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17+
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
.ie \n(.g .ds Aq \(aq
19+
.el .ds Aq '
20+
.\" -----------------------------------------------------------------
21+
.\" * set default formatting
22+
.\" -----------------------------------------------------------------
23+
.\" disable hyphenation
24+
.nh
25+
.\" disable justification (adjust text to left margin only)
26+
.ad l
27+
.\" -----------------------------------------------------------------
28+
.\" * MAIN CONTENT STARTS HERE *
29+
.\" -----------------------------------------------------------------
30+
.SH "NAME"
31+
gsh \- GameShell specific commands invocation
32+
.SH "SYNOPSIS"
33+
.sp
34+
\fBgsh\fR <\fICOMMAND\fR>
35+
.SH "DESCRIPTION"
36+
.sp
37+
GameShell is a game for learning (and teaching) how to use a POSIX shell\&.
38+
.sp
39+
Almost all the commands encountered during a game are standard Unix commands, with the notable exception of the commands needed to interact with GameShell itself\&. All those interaction start with \fBgsh\fR, followed by a subcommand\&.
40+
.SH "NOTE"
41+
.sp
42+
On standard Unix systems, you should be able to quit this manual by pressing the "q" key\&.
43+
.sp
44+
You should be able to scroll using the Space key or the arrow keys\&.
45+
.sp
46+
Youn can search through this page by pressing on the "/" key, followed by the pattern you are searching\&. Pressing "n" (for "next") or "p" (for "previous") will go the next / previous occurence of the search pattern\&.
47+
.SH "COMMANDS"
48+
.SS "Standard player commands"
49+
.sp
50+
Under normal circomstances, a player shouldn\(cqt need to use more than the following commands\&.
51+
.PP
52+
\fBgsh check\fR
53+
.RS 4
54+
check whether the current mission\(cqs goal has been achieved or not
55+
.RE
56+
.PP
57+
\fBgsh exit\fR
58+
.RS 4
59+
quit GameShell
60+
61+
(you can start from the current mission by running GameShell with the
62+
\fB\-C\fR
63+
flag)
64+
65+
Note that you can exit GameShell using Control\-d as well
66+
.RE
67+
.PP
68+
\fBgsh goal\fR [\fIN\fR]
69+
.RS 4
70+
show the current mission\(cqs goal if n is given, show the goal for mission
71+
\fIN\fR
72+
.RE
73+
.PP
74+
\fBgsh help\fR
75+
.RS 4
76+
short help message
77+
.RE
78+
.PP
79+
\fBgsh reset\fR
80+
.RS 4
81+
reset the current mission
82+
.RE
83+
.SS "Admin commands"
84+
.sp
85+
Some commands are only accessible when the player knows the secret "GameShell administrator password"\&. Those commands make it possible to skip some mission\&.
86+
.sp
87+
The password for the standard GameShell is simply "gsh" but if you\(cqre using GameShell in the classroom, your instructor has probably changed it to something else!
88+
.PP
89+
\fBgsh auto\fR
90+
.RS 4
91+
source the current mission\(cqs automatic script, if it exists
92+
.RE
93+
.PP
94+
\fBgsh goto\fR [\fIN\fR]
95+
.RS 4
96+
directly go to mission
97+
\fIN\fR
98+
(Note: no password necessary if
99+
\fIN\fR
100+
is a previous mission)
101+
.RE
102+
.PP
103+
\fBgsh skip\fR
104+
.RS 4
105+
give up on the current mission and go to the next one
106+
107+
(no password necessary if the mission was completed at least once)
108+
.RE
109+
.SS "Additional commands"
110+
.sp
111+
There are couple of additional commands that can give information about the game\&. Except for the \fBindex\fR subcommand, they aren\(cqt very interesting for the player\&.
112+
.PP
113+
\fBgsh index\fR
114+
.RS 4
115+
show list of missions, with their status
116+
.RE
117+
.PP
118+
\fBgsh stat\fR
119+
.RS 4
120+
display simple statistics about completed missions
121+
.RE
122+
.PP
123+
\fBgsh version\fR
124+
.RS 4
125+
show GameShell\(cqs version
126+
.RE
127+
.PP
128+
\fBgsh welcome\fR
129+
.RS 4
130+
show the welcome message
131+
.RE
132+
.SS "Developper and administration commands"
133+
.sp
134+
The following commands are only useful for GameShell developpers\&. Player should probably avoid them\&.
135+
.PP
136+
\fBgsh assert condition\fR [\fIMSG\fR]
137+
.RS 4
138+
check if the condition is true
139+
140+
if not, display an error message
141+
.RE
142+
.PP
143+
\fBgsh assert check true/false\fR [\fIMSG\fR]
144+
.RS 4
145+
check the current mission\(cqs goal has been achieved
146+
147+
if the result doesn\(cqt coincide with the expected result, display an error message
148+
.RE
149+
.PP
150+
\fBgsh env\fR
151+
.RS 4
152+
display internal environment variables
153+
.RE
154+
.PP
155+
\fBgsh hardreset\fR
156+
.RS 4
157+
reset the current mission by restarting the shell
158+
.RE
159+
.PP
160+
\fBgsh HELP\fR
161+
.RS 4
162+
this message
163+
.RE
164+
.PP
165+
\fBgsh log\fR [\fB\-v\fR]
166+
.RS 4
167+
show the log file of gsh commands
168+
.RE
169+
.PP
170+
\fBgsh pcm\fR
171+
.RS 4
172+
print the current mission number
173+
.RE
174+
.PP
175+
\fBgsh protect\fR and \fBgsh unprotect\fR
176+
.RS 4
177+
add / remove protection on GameShell directories
178+
.RE
179+
.PP
180+
\fBgsh resetstatic\fR
181+
.RS 4
182+
regenerate all the static parts of the world
183+
.RE
184+
.PP
185+
\fBgsh save\fR \fIFILENAME\fR
186+
.RS 4
187+
save the current game to file
188+
.RE
189+
.PP
190+
\fBgsh systemconfig\fR
191+
.RS 4
192+
display the system configuration
193+
.RE
194+
.PP
195+
\fBgsh test\fR
196+
.RS 4
197+
run the current mission\(cqs test script, if it exists
198+
.RE
199+
.SH "AUTHORS"
200+
.sp
201+
GameShell was originally developped by Pierre Hyvernat and Rodolphe Lepigre at Université Savoie Mont Blanc, based on an idea from Rodolphe Lepigre\&. Several people have contributed individual missions, bug reports, bug fixes and translations\&.
202+
.sp
203+
It is currently maintained and developped by Pierre Hyvernat\&.
204+
.SH "REPORTING BUGS"
205+
.sp
206+
The best way to report bug is by opening an issue on github: https://github\&.com/phyver/GameShell/issues
207+
.sp
208+
You can also send an email directly to <mailto:pierre\&.hyvernat@univ\-smb\&.fr> with a description of your problem\&.
209+
.sp
210+
Please include
211+
.sp
212+
.RS 4
213+
.ie n \{\
214+
\h'-04'\(bu\h'+03'\c
215+
.\}
216+
.el \{\
217+
.sp -1
218+
.IP \(bu 2.3
219+
.\}
220+
a description of the problem,
221+
.RE
222+
.sp
223+
.RS 4
224+
.ie n \{\
225+
\h'-04'\(bu\h'+03'\c
226+
.\}
227+
.el \{\
228+
.sp -1
229+
.IP \(bu 2.3
230+
.\}
231+
the version of GameShell you are using (cf
232+
\fBgsh version\fR, or the
233+
\fB\-V\fR
234+
option of the GameShell script),
235+
.RE
236+
.sp
237+
.RS 4
238+
.ie n \{\
239+
\h'-04'\(bu\h'+03'\c
240+
.\}
241+
.el \{\
242+
.sp -1
243+
.IP \(bu 2.3
244+
.\}
245+
the output of the
246+
\fBgsh env\fR
247+
commande,
248+
.RE
249+
.sp
250+
.RS 4
251+
.ie n \{\
252+
\h'-04'\(bu\h'+03'\c
253+
.\}
254+
.el \{\
255+
.sp -1
256+
.IP \(bu 2.3
257+
.\}
258+
any additional relevant information\&.
259+
.RE
260+
.SH "SEE ALSO"
261+
.sp
262+
\fIbash\fR(1), \fIzsh\fR(1), \fIsh\fR(1)
263+
.SH "GAMESHELL"
264+
.sp
265+
GameShell source code is hosted on github: https://github\&.com/phyver/GameShell
266+
.SH "LICENCE"
267+
.sp
268+
GNU General Public Licence version 3, "GPLV3", https://www\&.gnu\&.org/licenses/gpl\-3\&.0\&.html

0 commit comments

Comments
 (0)