poke-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] Documentation: Numerous minor corrections.


From: John Darrington
Subject: [PATCH] Documentation: Numerous minor corrections.
Date: Mon, 2 Dec 2019 18:27:37 +0100

        * doc/poke.texi: Numerous changes.
---
 ChangeLog     |   4 +++
 doc/poke.texi | 112 ++++++++++++++++++++++++++++++++++++++--------------------
 2 files changed, 77 insertions(+), 39 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 439eecc..5e36821 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2019-12-01 John Darrington <address@hidden>
+
+       * doc/poke.texi (dump): Numerous minor changes.
+
 2019-12-01 Luca Saiu <address@hidden>
 
        * src/pkl-insn.def (PKL_INSN_TUCK): Define new instruction.
diff --git a/doc/poke.texi b/doc/poke.texi
index dffe912..25217a8 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -65,11 +65,11 @@ Using poke
 * Commanding poke::            Interactive and non-interactive usage.
 
 Dot-Commands
-* load command::               Loading pickles.
+* load command::               Loading pickles.
 * file command::               Opening and selecting IO spaces.
 * close command::              Closing IO spaces.
 * editor command::             Using an external editor for input.
-* info command::               Getting information about open files, etc.
+* info command::               Getting information about open files, @i{etc}.
 * set command::                        Querying and setting global options.
 * vm command::                 Poke Virtual Machine services.
 * exit command::               Exiting poke :(
@@ -350,7 +350,7 @@ using comma characters (@code{,}).  Spaces are generally 
ignored.
 @subsection Commands
 @cindex commands
 Regular poke commands are written in Poke and use different
-conventions.  The name of commands follow the same rules than normal
+conventions.  The name of commands follow the same rules as normal
 Poke identifiers, and do not start with a dot character.
 
 An example is the @command{dump} command:
@@ -416,7 +416,7 @@ The @file{~/.pokerc} startup file is also a poke script.
 Following the example of Guile Scheme, the Poke syntax includes
 support for multi-line comments using the @code{#!} and @code{!#}
 delimiters.  This, along with the @code{-L} command line option,
-allows to write Poke scripts and execute them in the command line like
+allows you to write Poke scripts and execute them in the command line like
 if they were normal programs.  Example of a script:
 
 @example
@@ -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,9 +558,10 @@ location where the functions were defined.
 
 @node set command
 @chapter @code{.set}
+@cindex @code{.set}
 
 @cindex global settings
-The @command{.set} command allows to inspect and set the value of
+The @command{.set} command allows you to inspect and set the value of
 global settings.  The syntax is:
 
 @example
@@ -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,9 +640,18 @@ whatever architecture running poke.
 
 @node exit command
 @chapter @code{.exit}
+@cindex @code{.exit}
 @cindex quitting
-@cindex exit
-The @code{.exit} command exits poke.
+@cindex @code{exit}
+The @code{.exit} command exits poke.  The syntax is:
+
+@example
+.exit [@var{status}]
+@end example
+
+@noindent
+Poke will terminate, returning the exit status @var{status}.
+If @var{status} is omitted, then the exit status zero will be returned.
 
 @node dump
 @chapter @command{dump}
@@ -770,7 +786,7 @@ will not need to explicitly pass them when you call the 
function.
 @cindex @file{.pokerc}
 Upon invocation poke will read and execute the commands of the file
 @file{~/.pokerc} if it exists in your home directory.  This can
-be disabling passing @code{-q} or @code{--no-init-file} in the command
+be disabled by passing @code{-q} or @code{--no-init-file} in the command
 line.
 
 The @file{.pokerc} file contains commands, not Poke code.  This means
@@ -856,9 +872,9 @@ minus operator as explained below.  Therefore the minus 
symbol
 @subsection The digits separator @code{_}
 @cindex digits separator
 @cindex separator, digits separator
-The character @code{_} can appear anywhere in a numeric literal other
-than leading them.  It is ignored, and its purpose is to make it
-easier for programmers to read them:
+The character @code{_} can appear anywhere in a numeric literal
+except as the first character.  It is ignored, and its purpose is to
+make it easier for programmers to read them:
 
 @example
 0xf000_0000_0000_0000
@@ -897,7 +913,7 @@ explicitly specified using the suffix @code{u} or @code{U} 
(the
 default are signed types).  For example @code{0xffff_ffffU} has type
 @code{uint<32>} and @code{0ub} has type @code{uint<8>}.  It is possible
 to combine width-indicating suffixes with signedness suffixes:
-@code{10UL} denotes the same literal than @code{10LU}.
+@code{10UL} denotes the same literal as @code{10LU}.
 
 The above rules guarantee that it is always possible to determine the
 width and signedness of an integer constant just by looking at it,
@@ -1168,7 +1184,7 @@ Gives 1 if the value is a signed integer, 0 otherwise.  
Examples:
 0
 @end example
 @item mapped
-Always 0 for integers.  See mapping.
+Always 0 for integers.  (@pxref{Mapping}).
 @end table
 
 
@@ -1361,6 +1377,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
@@ -1392,15 +1410,20 @@ bits.
 @item B
 bytes.
 @item Kb
+@cindex kilobits
 kilo bits (1024 bits.)
 @item KB
+@cindex kilobytes
 Kilo bytes (1024 bytes.)
 @item Mb
+@cindex megabits
 Mega bits.
 @item MB
+@cindex megabytes
 Mega bytes.
 @item Gb
-Mega bits.
+@cindex gigabits
+Giga bits.
 @end table
 
 However, it is also possible to express units in multiples of the base
@@ -1461,6 +1484,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 +1503,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 +1526,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:
@@ -1543,7 +1569,7 @@ Examples:
 0#MB
 @end example
 
-The unit of the result is the same than the unit of the offset
+The unit of the result is the same as the unit of the offset
 operand.
 
 Note that multiplying two offsets is not supported.  This makes sense,
@@ -1565,6 +1591,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:
@@ -1575,7 +1602,7 @@ something like the following to convert from kilobits to 
bytes:
 @end example
 
 There is also a ceil-division operator for offsets, with the same
-semantics than the ceil-division for integers:
+semantics as the ceil-division for integers:
 
 @example
 (poke) 10#B /^ 3#B
@@ -1632,7 +1659,7 @@ Examples:
 1UL
 @end example
 @item mapped
-Always 0 for offsets.  See mapping.
+Always 0 for offsets.  (@pxref{Mapping}).
 @end table
 
 
@@ -1773,7 +1800,7 @@ includes the terminating null.  Examples:
 8UL#b
 @end example
 @item mapped
-Always 0 for strings.  See mapping.
+Always 0 for strings.  (@pxref{Mapping}).
 @end table
 
 @node Arrays
@@ -1830,11 +1857,11 @@ arrays:
 
 It is possible to refer to specific elements when constructing array
 literals.  For example, @code{[1,2,3,.[3] = 4]} denotes the same
-array than @code{[1,2,3,4]}.
+array as @code{[1,2,3,4]}.
 
 This allows creating arrays without having to specify all its
 elements.  Unspecified elements have the next specified value.  For
-example, @code{[.[2] = 2]} denotes the same array than
+example, @code{[.[2] = 2]} denotes the same array as
 @code{[2,2,2]}.
 
 Note that an array element can be referenced more than once.  When
@@ -2014,7 +2041,7 @@ unhandled out of bounds exception
 @section Array Trimming
 
 Indexing is used to fetch elements from arrays.  Another operation,
-called @dfn{trimming}, allows to extract a subset of the array, as
+called @dfn{trimming}, allows you to extract a subset of the array, as
 another array.
 
 Trims use the following notation, where a range is specified between
@@ -2266,7 +2293,7 @@ deftype Ctf_Preamble =
 @end example
 
 The constraint expression will often include the field where it is
-installed, but that's no mandatory.
+installed, but that's not mandatory.
 
 Field constraints play an important role in mapping.  On one side,
 a map will fail if there is some constraint that fails.  On the other,
@@ -2401,8 +2428,8 @@ XXX
 
 @node deftype
 @section @code{deftype}
-@cindex deftype
-The @code{deftype} directive allows to declare named types.  The
+@cindex @code{deftype}
+The @code{deftype} directive allows you to declare named types.  The
 syntax is:
 
 @example
@@ -2464,7 +2491,7 @@ Arrays of @code{any}, @code{any[]}, are also supported:
 @node The isa Operator
 @section The @code{isa} Operator
 @cindex isa operator
-The binary operator @code{isa} allows to check for the type of a given
+The binary operator @code{isa} allows you to check for the type of a given
 value:
 
 @example
@@ -2590,6 +2617,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 +2656,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 +2696,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}:
@@ -2677,7 +2706,7 @@ defun @var{name} = [(@var{formal},@dots{})] 
@var{ret_type}:
 @end example
 
 Where @var{name} is the name of the function, which uses the same
-namespace than variables and types and @var{ret_type} is the type of
+namespace as variables and types and @var{ret_type} is the type of
 the value returned by the function.  If the function returns no value
 then it is @code{void}.
 
@@ -2873,7 +2902,7 @@ The current endianness can be obtained like this:
 little
 @end example
 
-We can easily see how changing The current endianness indeed impacts
+We can easily see how changing the current endianness indeed impacts
 the way integers are mapped:
 
 @example
@@ -3088,7 +3117,7 @@ memory of some process.
 @subsection @code{open}
 @cindex opening files
 @cindex IO space
-The @code{open} builtin allows to create new IO spaces, by opening an
+The @code{open} builtin allows you to create new IO spaces, by opening an
 IO device.  It has the following prototype:
 
 @example
@@ -3114,8 +3143,9 @@ will raise an @code{E_no_ios} exception.
 
 @node close
 @subsection @code{close}
+@cindex @code{close}
 
-The @code{close} builtin allows to destroy IO spaces, closing the
+The @code{close} builtin allows you to destroy IO spaces, closing the
 underlying IO device.  The prototype is:
 
 @example
@@ -3130,6 +3160,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,8 +3176,9 @@ exception.
 
 @node set_ios
 @subsection @code{set_ios}
+@cindex @code{set_ios}
 
-The @code{set_ios} builtin allows to set a specific IO space as the
+The @code{set_ios} builtin allows you to set a specific IO space as the
 new current IO space.  It has the following prototype:
 
 @example
@@ -3394,7 +3426,7 @@ would be good if the tool would tell us whether the 
specified size
 actually holds an exact number of the requested elements.
 
 A mapping bound by size is what we need.  Fortunately, as we saw when
-discussing array types, Poke allows to specify an offset instead of an
+discussing array types, Poke allows you to specify an offset instead of an
 integral value, in the array type specification.  The right amount of
 entities (in this case relocations) to strictly satisfy the provided
 size will be mapped in the IO space.  So, in order to obtain an array
@@ -3525,7 +3557,7 @@ It gets any value and produces the same value, making it 
not mapped in
 case it is a mapped value.
 
 This is useful when we want to read a data structure from the IO space
-(say, and array of integers) and then use it for storage without
+(say, an array of integers) and then use it for storage without
 changing the underlying IO space.  We would do something like:
 
 @example
@@ -3594,7 +3626,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.
 
@@ -3608,7 +3640,7 @@ Where @var{stmt} is any statement and @var{compound_stmt} 
is a
 compound statement.  @var{stmt} is executed.  If during its execution
 an exception is raised, then @var{compound_stmt} gets executed.
 
-The second form of the statement allows to catch just one type of
+The second form of the statement allows you to catch just one type of
 exceptions:
 
 @example
@@ -3631,8 +3663,8 @@ type when @var{compound_stmt} is executed.
 
 @node try-until
 @section @code{try-until}
-@cindex try-until
-The @code{try-until} statement allows to execute instructions until
+@cindex @code{try-until}
+The @code{try-until} statement allows you to execute instructions until
 some exception is caught.  The syntax is:
 
 @example
@@ -3751,7 +3783,7 @@ Print the integer as an ASCII character.  This only works 
with 8 bit
 integers.
 @end table
 @item %u
-Same than @code{%s}, but for unsigned integers.
+Same as @code{%s}, but for unsigned integers.
 @item %c
 A shorter way to write @code{%u8c}.
 @item %v
@@ -3804,6 +3836,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
@@ -4062,7 +4096,7 @@ XXX
 @c  LocalWords:  variadic args PDP programmatically PKL eBPF dst src
 @c  LocalWords:  BPF Insn Regs le ident ei ELFDATA LSB ELFDAT MSB ios
 @c  LocalWords:  Ehdr ELFDATANONE osabi abiversion nident Unmapping
-@c  LocalWords:  filesystem Comparator cmp relocations DIEs nelems
+@c  LocalWords:  Comparator cmp relocations DIEs nelems
 @c  LocalWords:  EOF Rela Addr Xword Sxword Shdr addr addralign fmt
 @c  LocalWords:  entsize relocs adoleces libtextstyle classname css
 @c  LocalWords:  ushort ulong uoff abc ltrim whitespace rtrim fdl
-- 
2.11.0




reply via email to

[Prev in Thread] Current Thread [Next in Thread]