[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 03/12] Markup code types
From: |
John Darrington |
Subject: |
[PATCH 03/12] Markup code types |
Date: |
Mon, 2 Dec 2019 17:51:04 +0100 |
---
doc/poke.texi | 31 ++++++++++++++++++++++++++-----
1 file changed, 26 insertions(+), 5 deletions(-)
diff --git a/doc/poke.texi b/doc/poke.texi
index e1ed57a..df8b8ab 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -428,6 +428,7 @@ print "Hello world!\n";
@node load command
@chapter @code{.load}
+@cindex @code{.load}
The @command{.load} command loads a file containing Poke code and
compiles and executes it. These files usually have the extension
@@ -445,6 +446,7 @@ If an absolute path is provided, it is used as-is.
@node file command
@chapter @code{.file}
+@cindex @code{.file}
@cindex opening files
@cindex IO space
The @command{.file} command opens a new IO space backed by a file, or
@@ -486,6 +488,7 @@ The current file is now `foo.o'.
@node close command
@chapter @code{.close}
+@cindex @code{.close}
@cindex IO space
The @command{.close} command closes the selected IO space. The syntax
@@ -499,6 +502,7 @@ Where @var{#tag} is a tag identifying an open IO stream.
@node editor command
@chapter @code{.editor}
+@cindex @code{.editor}
@cindex editor
The @command{.editor} command (usually abbreviated as @command{.edit})
invokes an external text editor on a temporary file. You can then
@@ -511,6 +515,7 @@ variable.
@node info command
@chapter @code{.info}
+@cindex @code{.info}
The @command{.info} command provides information about several kinds
of entities. The recognized sub commands are:
@@ -553,6 +558,7 @@ location where the functions were defined.
@node set command
@chapter @code{.set}
+@cindex @code{.set}
@cindex global settings
The @command{.set} command allows you to inspect and set the value of
@@ -596,6 +602,7 @@ Default value is @code{no}.
@node vm command
@chapter @code{.vm}
+@cindex @code{.vm}
@cindex virtual machine
The Poke Virtual Machine (PVM) executes the programs that are the
@@ -633,8 +640,9 @@ whatever architecture running poke.
@node exit command
@chapter @code{.exit}
+@cindex @code{.exit}
@cindex quitting
-@cindex exit
+@cindex @code{exit}
The @code{.exit} command exits poke.
@node dump
@@ -1361,6 +1369,8 @@ to denote offsets in the file you are editing):
1024#Kb
@end example
+@cindex magnitude
+@cindex kilobytes
The offsets above denote twelve bytes, seven bits and one thousand
twenty four kilobytes, respectively. The unit can be separated from
the magnitude by blank characters, so you can write the following
@@ -1461,6 +1471,7 @@ shdr.sh_size = 10#Elf64_Rela;
@noindent
Instead of doing the conversion to bytes explicitly.
+@cindex magnitude
If the magnitude of an offset is 1 then it is allowed to omit it
entirely. To denote one kilobyte, for example, we can write
@code{#KB}.
@@ -1479,6 +1490,7 @@ The unit specification should be one of the unit
identifiers that are
allowed in offset literals (see above) or the name of a Poke type
whose size is known as compile time.
+@cindex kilobits
Let's see some examples. A signed 32-bit offset expressed in bytes
has type @code{offset<int<32>,B>}. An unsigned 12-bit offset
expressed in kilobits has type @code{offset<uint<12>,Kb>}. Finally, a
@@ -1501,6 +1513,7 @@ units bytes:
(int<12>) 128#B
@end example
+@cindex magnitude
The same rules governing conversion of integers apply for the
magnitude part. Depending on the unit, there can be truncation, like
in:
@@ -1565,6 +1578,7 @@ Dividing offsets is the Pokish way of converting memory
magnitudes
between different units: just use units like you do when doing physics
or working with units in other contexts.
+@cindex kilobits
For example, using the syntactic trick of omitting the magnitude (in
which case it is assumed to be 1) it is very natural to write
something like the following to convert from kilobits to bytes:
@@ -2401,7 +2415,7 @@ XXX
@node deftype
@section @code{deftype}
-@cindex deftype
+@cindex @code{deftype}
The @code{deftype} directive allows you to declare named types. The
syntax is:
@@ -2590,6 +2604,7 @@ Where @var{exp} is an expression that should evaluate to
a boolean
(@i{i.e.} to an integer) and @var{stmt} is an statement that will be
executed until @var{exp} holds false.
+@cindex @code{break}
It is possible to leave the loop from within @var{stmt} using the
@code{break} statement. Example:
@@ -2628,6 +2643,7 @@ example:
1 3
@end example
+@cindex @code{break}
It is possible to leave the loop from within @var{stmt} using the
@code{break} statement.
@@ -2667,7 +2683,7 @@ The value computed by the expression will be discarded.
@section Function Declarations
@cindex declarations, function declarations
A function is declared using the following syntax:
-@cindex defun
+@cindex @code{defun}
@example
defun @var{name} = [(@var{formal},@dots{})] @var{ret_type}:
@@ -3114,6 +3130,7 @@ will raise an @code{E_no_ios} exception.
@node close
@subsection @code{close}
+@cindex @code{close}
The @code{close} builtin allows you to destroy IO spaces, closing the
underlying IO device. The prototype is:
@@ -3130,6 +3147,7 @@ If the IO space specified to @code{close} doesn't exist
then an
@node get_ios
@subsection @code{get_ios}
+@cindex @code{get_ios}
GNU poke maintains a @dfn{current IO space}, which is the last created
IO space (this includes IO spaces opened and selected using a
@@ -3145,6 +3163,7 @@ exception.
@node set_ios
@subsection @code{set_ios}
+@cindex @code{set_ios}
The @code{set_ios} builtin allows you to set a specific IO space as the
new current IO space. It has the following prototype:
@@ -3594,7 +3613,7 @@ Generic IO exception.
@node try-catch
@section @code{try-catch}
-@cindex try-catch
+@cindex @code{try-catch}
The @code{try-catch} statement provides a way to catch exceptions and
handle them.
@@ -3631,7 +3650,7 @@ type when @var{compound_stmt} is executed.
@node try-until
@section @code{try-until}
-@cindex try-until
+@cindex @code{try-until}
The @code{try-until} statement allows you to execute instructions until
some exception is caught. The syntax is:
@@ -3804,6 +3823,8 @@ XXX
@node __LINE__ and __FILE__
@chapter @code{__LINE__} and @code{__FILE__}
+@cindex @code{__FILE__}
+@cindex @code{__LINE__}
@cindex location
@cindex tracing
When printing traces it is often useful to include a description of
--
2.11.0
- Numerous small documentation changes., John Darrington, 2019/12/02
- [PATCH 04/12] Fix typo, John Darrington, 2019/12/02
- [PATCH 02/12] Add links to Mapping node, John Darrington, 2019/12/02
- [PATCH 05/12] Add some indeces and correct typo, John Darrington, 2019/12/02
- [PATCH 06/12] Downcase rouge capital, John Darrington, 2019/12/02
- [PATCH 03/12] Markup code types,
John Darrington <=
- [PATCH 07/12] Document the argument to .exit, John Darrington, 2019/12/02
- [PATCH 08/12] Doc fix typo, John Darrington, 2019/12/02
- [PATCH 09/12] DOC: Remove redundant comment, John Darrington, 2019/12/02
- [PATCH 01/12] "allows to" --> "allows you to", John Darrington, 2019/12/02
- [PATCH 10/12] DOC: Add markup, John Darrington, 2019/12/02
- [PATCH 11/12] DOC: fix typo, John Darrington, 2019/12/02
- [PATCH 12/12] Doc: change 'than' to 'as' where appropriate, John Darrington, 2019/12/02
- Re: Numerous small documentation changes., Jose E. Marchesi, 2019/12/02