Skip to content

Commit 02ee939

Browse files
Rangi42Rangi42
committed
Document obsolete syntax in rgbasm-old(5)
1 parent 573e044 commit 02ee939

File tree

9 files changed

+342
-4
lines changed

9 files changed

+342
-4
lines changed

Diff for: ‎.github/scripts/install.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
install -d /usr/local/bin/ /usr/local/share/man/man1/ /usr/local/share/man/man5/ /usr/local/share/man/man7/
44
install -s -m 755 rgbasm rgblink rgbfix rgbgfx /usr/local/bin/
55
install -m 644 rgbasm.1 rgblink.1 rgbfix.1 rgbgfx.1 /usr/local/share/man/man1/
6-
install -m 644 rgbds.5 rgbasm.5 rgblink.5 /usr/local/share/man/man5/
6+
install -m 644 rgbds.5 rgbasm.5 rgblink.5 rgbasm-old.5 /usr/local/share/man/man5/
77
install -m 644 rgbds.7 gbz80.7 /usr/local/share/man/man7/

Diff for: ‎.github/workflows/update-master-docs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ on:
99
- man/rgbds.7
1010
- man/rgbasm.1
1111
- man/rgbasm.5
12+
- man/rgbasm-old.5
1213
- man/rgblink.1
1314
- man/rgblink.5
1415
- man/rgbfix.1

Diff for: ‎CMakeLists.txt

+1
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ set(man1 "man/rgbasm.1"
126126
"man/rgbgfx.1"
127127
"man/rgblink.1")
128128
set(man5 "man/rgbasm.5"
129+
"man/rgbasm-old.5"
129130
"man/rgblink.5"
130131
"man/rgbds.5")
131132
set(man7 "man/gbz80.7"

Diff for: ‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ install: all
185185
$Qinstall ${STRIP} -m ${BINMODE} rgbfix ${DESTDIR}${bindir}/rgbfix${SUFFIX}
186186
$Qinstall ${STRIP} -m ${BINMODE} rgbgfx ${DESTDIR}${bindir}/rgbgfx${SUFFIX}
187187
$Qinstall -m ${MANMODE} man/rgbasm.1 man/rgblink.1 man/rgbfix.1 man/rgbgfx.1 ${DESTDIR}${mandir}/man1/
188-
$Qinstall -m ${MANMODE} man/rgbds.5 man/rgbasm.5 man/rgblink.5 ${DESTDIR}${mandir}/man5/
188+
$Qinstall -m ${MANMODE} man/rgbds.5 man/rgbasm.5 man/rgbasm-old.5 man/rgblink.5 ${DESTDIR}${mandir}/man5/
189189
$Qinstall -m ${MANMODE} man/rgbds.7 man/gbz80.7 ${DESTDIR}${mandir}/man7/
190190

191191
# Target used to check for suspiciously missing changed files.

Diff for: ‎RELEASE.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ GitHub.
5555

5656
If you do not have `groff` installed, you can change
5757
`groff -Tpdf -mdoc -wall` to `mandoc -Tpdf -I os=Linux` in
58-
[.github/actions/get-pages.sh](.github/actions/get-pages.sh) and it
59-
will suffice.
58+
[maintainer/man_to_html.sh](https://github.com/gbdev/rgbds-www/blob/master/maintainer/man_to_html.sh)
59+
and it will suffice.
6060

6161
4. Commit and push the documentation. You can use <code>git commit -m
6262
"Create RGBDS <i>&lt;tag&gt;</i> documentation"</code> and `git push origin master`

Diff for: ‎man/gbz80.7

+1
Original file line numberDiff line numberDiff line change
@@ -2083,6 +2083,7 @@ Flags: See
20832083
.Xr rgblink 1 ,
20842084
.Xr rgbfix 1 ,
20852085
.Xr rgbgfx 1 ,
2086+
.Xr rgbasm-old 5 ,
20862087
.Xr rgbds 7
20872088
.Sh HISTORY
20882089
.Xr rgbasm 1

Diff for: ‎man/rgbasm-old.5

+333
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
'\" e
2+
.\"
3+
.\" SPDX-License-Identifier: MIT
4+
.\"
5+
.Dd October 21, 2024
6+
.Dt RGBASM-OLD 5
7+
.Os
8+
.Sh NAME
9+
.Nm rgbasm-old
10+
.Nd obsolete language documentation
11+
.Sh DESCRIPTION
12+
This is the list of features that have been removed from the
13+
.Xr rgbasm 5
14+
assembly language over its decades of evolution, along with their modern alternatives.
15+
Its goal is to be a reference for backwards incompatibility, when upgrading an old assembly codebase to work with the latest RGBDS release.
16+
It does
17+
.Em not
18+
attempt to list syntax bugs that were fixed, nor new reserved keywords that may conflict with old identifiers.
19+
.Sh REMOVED
20+
.Ss Global labels without colons
21+
Deprecated in 0.4.0, removed in 0.5.0.
22+
.Pp
23+
Labels used to be definable with just a name, but had to be typed in column 1.
24+
.Pp
25+
Instead, use explicit colons; for example,
26+
.Ql Label:
27+
or exported
28+
.Ql Label:: .
29+
.Ss Automatic LD to LDH conversion (rgbasm -l)
30+
Deprecated in 0.7.0, removed in 0.8.0.
31+
.Pp
32+
.Xr rgbasm 1
33+
used to automatically treat
34+
.Ql LD
35+
as
36+
.Ql LDH
37+
if the address was known to be in the
38+
.Ad $FF00-$FFFF
39+
range, with the
40+
.Fl L
41+
flag to opt out.
42+
.Xr rgbasm 1
43+
0.6.0 added a
44+
.Fl l
45+
flag to opt in instead.
46+
.Pp
47+
Instead, use
48+
.Ql LDH ,
49+
and remove the
50+
.Fl L
51+
and
52+
.Fl l
53+
flags from
54+
.Xr rgbasm 1 .
55+
.Ss Automatic NOP after HALT (rgbasm -H)
56+
Deprecated in 0.7.0, removed in 0.8.0.
57+
.Pp
58+
.Xr rgbasm 1
59+
used to automatically insert a
60+
.Ql NOP
61+
after
62+
.Ql HALT ,
63+
with the
64+
.Fl h
65+
flag to opt out.
66+
.Xr rgbasm 1
67+
0.6.0 added a
68+
.Fl H
69+
flag to opt in instead.
70+
.Pp
71+
Instead, use an explicit
72+
.Ql NOP
73+
after
74+
.Ql HALT ,
75+
and remove the
76+
.Fl h
77+
and
78+
.Fl H
79+
flags from
80+
.Xr rgbasm 1 .
81+
.Ss IMPORT and XREF
82+
Removed in 0.4.0.
83+
.Pp
84+
Symbols are now automatically resolved if they were exported from elsewhere.
85+
.Pp
86+
Instead, just remove these directives.
87+
.Ss __FILE__ and __LINE__
88+
Deprecated in 0.6.0, removed in 0.7.0.
89+
.Pp
90+
Instead, use
91+
.Ic WARN
92+
or
93+
.Ic FAIL
94+
to print a complete trace of filenames and line numbers.
95+
.Ss _PI
96+
Deprecated in 0.5.0, removed in 0.6.0.
97+
.Pp
98+
Instead, use
99+
.Ql DEF _PI EQU 3.141592653 .
100+
.Ss '\e,' in strings in macro arguments
101+
Deprecated in 0.5.0, removed in 0.7.0.
102+
.Pp
103+
Macro arguments now handle quoted strings and parenthesized expressions as single arguments, so commas inside them are not argument separators and do not need escaping.
104+
.Pp
105+
Instead, just use commas without backslashes.
106+
.Ss '*' comments
107+
Deprecated in 0.4.1, removed in 0.5.0.
108+
.Pp
109+
Instead, use
110+
.Ql \&;
111+
comments.
112+
.Ss Nested macro definitions
113+
Removed in 0.4.2.
114+
.Pp
115+
Instead, put the nested macro definition inside a quoted string (making sure that none of its lines start with
116+
.Ic ENDM ) ,
117+
then interpolate that string.
118+
For example:
119+
.Bd -literal -offset indent
120+
MACRO outer
121+
DEF definition EQUS """
122+
MACRO inner
123+
println (\1) - (\\1)
124+
\enENDM"""
125+
{definition}
126+
PURGE definition
127+
ENDM
128+
outer 10
129+
inner 3 ; prints 7
130+
.Ed
131+
.Ss Negative DS
132+
Removed in 0.3.2.
133+
.Pp
134+
This was used to "rewind" the value of
135+
.Ic @
136+
in RAM sections, allowing labeled space allocations to overlap.
137+
.Pp
138+
Instead, use
139+
.Ic UNION .
140+
.Ss Treating multi-character strings as numbers
141+
Deprecated in 0.9.0.
142+
.Pp
143+
Instead, use a multi-value
144+
.Ic CHARMAP ,
145+
or explicitly combine the values of individual characters.
146+
.Ss rgbgfx -f/--fix and -F/--fix-and-save
147+
Removed in 0.6.0.
148+
.Pp
149+
Instead, use
150+
.Ql rgbgfx -c/--colors
151+
to explicitly specify a color palette.
152+
If using
153+
.Ql -c embedded ,
154+
arrange the PNG's indexed palette in a separate graphics editor.
155+
.Ss rgbgfx -D/--debug
156+
Removed in 0.6.0.
157+
.Sh REPLACED
158+
.Ss Defining constants and variables without DEF
159+
Deprecated in 0.7.0, removed in 0.8.0.
160+
.Pp
161+
.Ic EQU , EQUS , = , RB , RW ,
162+
and
163+
.Ic RL
164+
definitions used to just start with the symbol name, but had to be typed in column 1.
165+
.Pp
166+
Instead, use
167+
.Ic DEF
168+
before constant and variable definitions.
169+
Note that
170+
.Ic EQUS
171+
expansion does not occur for the symbol name, so you have to use explicit
172+
.Ql {interpolation} .
173+
.Ss Defining macros like labels
174+
Deprecated in 0.6.0, removed in 0.7.0.
175+
.Pp
176+
Macros used to be defined as
177+
.Ql name: MACRO .
178+
.Pp
179+
Instead, use
180+
.Ql MACRO name .
181+
.Ss Defining variables with SET
182+
Deprecated in 0.5.2, removed in 0.6.0.
183+
.Pp
184+
Variables used to be defined as
185+
.Ql name SET value .
186+
.Pp
187+
Instead, use
188+
.Ql DEF name = value .
189+
.Ss PRINTT, PRINTI, PRINTV, and PRINTF
190+
Deprecated in 0.5.0, removed in 0.6.0.
191+
.Pp
192+
These directives were each specific to one type of value.
193+
.Pp
194+
Instead, use
195+
.Ic PRINT
196+
and
197+
.Ic PRINTLN ,
198+
with
199+
.Ic STRFMT
200+
or
201+
.Ql {interpolation}
202+
for type-specific formatting.
203+
.Ss GLOBAL and XDEF
204+
Deprecated in 0.4.2, removed in 0.5.0.
205+
.Pp
206+
Instead, use
207+
.Ic EXPORT .
208+
.Ss HOME, CODE, DATA, and BSS
209+
Deprecated in 0.3.0, removed in 0.4.0.
210+
.Pp
211+
Instead of
212+
.Ic HOME ,
213+
use
214+
.Ic ROM0 ;
215+
instead of
216+
.Ic CODE
217+
and
218+
.Ic DATA ,
219+
use
220+
.Ic ROMX ;
221+
instead of
222+
.Ic BSS ,
223+
use
224+
.Ic WRAM0 .
225+
.Ss JP [HL]
226+
Deprecated in 0.3.0, removed in ???.
227+
.Pp
228+
Instead, use
229+
.Ql JP HL .
230+
.Ss LDI A, HL and LDD A, HL
231+
Deprecated in 0.3.0, removed in ???.
232+
.Pp
233+
Instead, use
234+
.Ql LDI A, [HL]
235+
and
236+
LDD A, [HL]
237+
(or
238+
.Ql LD A, [HLI]
239+
and
240+
.Ql LD A, [HLD] ;
241+
or
242+
LD A, [HL+]
243+
and
244+
.Ql LD A, [HL-] ) .
245+
.Ss LD HL, [SP + e8]
246+
Removed in ???.
247+
.Pp
248+
Instead, use
249+
.Ql LD HL, SP + e8 .
250+
.Ss LDIO
251+
Deprecated in 0.9.0.
252+
.Pp
253+
Instead, use
254+
.Ql LDH .
255+
.Ss rgbasm -i
256+
Deprecated in 0.6.0, removed in 0.8.0.
257+
.Pp
258+
Instead, use
259+
.Fl I
260+
or
261+
.Fl -include .
262+
.Ss rgbgfx -h
263+
Removed in 0.6.0.
264+
.Pp
265+
Instead, use
266+
.Fl Z
267+
or
268+
.Fl -columns .
269+
.Ss rgbgfx --output-*
270+
Deprecated in 0.7.0, removed in 0.8.0.
271+
.Pp
272+
Instead, use
273+
.Fl -auto-* .
274+
.Sh CHANGED
275+
.Ss Trigonometry function units
276+
Changed in 0.6.0.
277+
.Pp
278+
Instead of dividing a circle into 65536.0 "binary degrees", it is now divided into 1.0 "turns".
279+
.Pp
280+
For example, previously we had:
281+
.EQ
282+
delim $$
283+
.EN
284+
.Bl -bullet -offset indent
285+
.It
286+
.Ql SIN(0.25) == 0.00002 ,
287+
because 0.25 binary degrees = $0.25 / 65536.0$ turns = $0.000004 tau$ radians = $0.000008 pi$ radians, and $sin ( 0.000008 pi ) = 0.00002$
288+
.It
289+
.Ql SIN(16384.0) == 1.0 ,
290+
because 16384.0 binary degrees = $16384.0 / 65536.0$ turns = $0.25 tau$ radians = $pi / 2$ radians, and $sin ( pi / 2 ) = 1$
291+
.It
292+
.Ql ASIN(1.0) == 16384.0
293+
.El
294+
.Pp
295+
Instead, now we have:
296+
.Bl -bullet -offset indent
297+
.It
298+
.Ql SIN(0.25) == 1.0 ,
299+
because $0.25$ turns = $0.25 tau$ radians = $pi / 2$ radians, and $sin ( pi / 2 ) = 1$
300+
.It
301+
.Ql SIN(16384.0) == 0.0 ,
302+
because $16384$ turns = $16384 tau$ radians = $32768 pi$ radians, and $sin ( 32768 pi ) = 0$
303+
.It
304+
.Ql ASIN(1.0) == 0.25
305+
.El
306+
.EQ
307+
delim off
308+
.EN
309+
.Ss ** operator associativity
310+
Changed in 0.9.0.
311+
.Pp
312+
Instead of being left-associative,
313+
.Ql **
314+
is now right-associative.
315+
.Pp
316+
Previously we had
317+
.Ql p ** q ** r == (p ** q) ** r .
318+
.Pp
319+
Instead, now we have
320+
.Ql p ** q ** r == p ** (q ** r) .
321+
.Sh SEE ALSO
322+
.Xr rgbasm 1 ,
323+
.Xr gbz80 7 ,
324+
.Xr rgbds 5 ,
325+
.Xr rgbds 7
326+
.Sh HISTORY
327+
.Xr rgbasm 1
328+
was originally written by
329+
.An Carsten S\(/orensen
330+
as part of the ASMotor package, and was later repackaged in RGBDS by
331+
.An Justin Lloyd .
332+
It is now maintained by a number of contributors at
333+
.Lk https://github.com/gbdev/rgbds .

Diff for: ‎man/rgbasm.1

+1
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,7 @@ Please report bugs on
427427
.Xr rgbfix 1 ,
428428
.Xr rgbgfx 1 ,
429429
.Xr gbz80 7 ,
430+
.Xr rgbasm-old 5 ,
430431
.Xr rgbds 5 ,
431432
.Xr rgbds 7
432433
.Sh HISTORY

0 commit comments

Comments
 (0)