Skip to content

Commit c1b8555

Browse files
Rangi42Rangi42
authored
Document obsolete syntax in rgbasm-old(5) (#1571)
1 parent b877c81 commit c1b8555

File tree

9 files changed

+351
-4
lines changed

9 files changed

+351
-4
lines changed

‎.github/scripts/install.sh‎

Lines changed: 1 addition & 1 deletion
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/

‎.github/workflows/update-master-docs.yml‎

Lines changed: 1 addition & 0 deletions
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

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
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"

‎Makefile‎

Lines changed: 1 addition & 1 deletion
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.

‎RELEASE.md‎

Lines changed: 2 additions & 2 deletions
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`

‎man/gbz80.7‎

Lines changed: 1 addition & 0 deletions
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

‎man/rgbasm-old.5‎

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

0 commit comments

Comments
 (0)