diff options
36 files changed, 77 insertions, 204 deletions
diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md index cb2e6a3..d60fcbf 100644 --- a/AGENTS/ARCH.md +++ b/AGENTS/ARCH.md @@ -179,14 +179,9 @@ they are pure data with virtual destructors only — no codegen/visitor methods. | `AGENTS/EXTENDING.md` | Adding a statement, builtin, operator, type, runtime check, or libc dependency — exact recipes | | `AGENTS/SUBSYSTEMS.md` | Working on arrays, functions/procedures, or runtime checks | | `AGENTS/PITFALLS.md` | Verified sharp edges (they *will* bite) and the list of unimplemented 9618 features | +| `AGENTS/MAN.md` | Editing man Markdown, language manual layout, generation and installation | ## Language manuals -`doc/cpsc.1.md` documents the command-line interface. Short language manuals live -in `doc/language/keyword/` as `cpsc-keyword-NAME.7.md` and -`doc/language/function/` as `cpsc-function-NAME.7.md`; the overview remains -`doc/language/cpsc-language-overview.7.md`. Filenames are lowercase and preserve underscores. -Document auxiliary/closing keywords with the main construct, not in separate -pages. Keep examples small and describe actual compiler support, noting relevant -differences from the 2026 Cambridge guide in `reference/`. All project text is -English. +See [MAN.md](MAN.md) before editing the command or syntax manuals. It defines +source layout, naming, prose formatting and the small checks needed for changes. diff --git a/AGENTS/MAN.md b/AGENTS/MAN.md new file mode 100644 index 0000000..b942674 --- /dev/null +++ b/AGENTS/MAN.md @@ -0,0 +1,26 @@ +# Man documentation + +Read this file before editing the manual sources or their build, packaging and installation paths. All project text is English. + +## Sources and naming + +- `doc/cpsc.1.md`: command-line manual, section 1. +- `doc/language/cpsc-language-overview.7.md`: syntax overview and index, section 7. +- `doc/language/keyword/cpsc-keyword-NAME.7.md`: keyword manuals. +- `doc/language/function/cpsc-function-NAME.7.md`: built-in function manuals. + +Use lowercase filenames and preserve underscores: `NUM_TO_STR` becomes `cpsc-function-num_to_str.7.md`. Keep closing and auxiliary keywords with the main construct; for example, IF includes THEN, ELSE and ENDIF. + +## Writing + +Write each prose paragraph on one source line. Never manually wrap prose to a column limit or split it into lines just because it looks long. man chooses line wrapping from the terminal width. Separate paragraphs with blank lines; preserve structural lines for headings, lists and definition lists, and meaningful line breaks/indentation inside syntax and example code blocks. Apply this rule to both `doc/cpsc.1.md` and every language manual. + +Keep pages short: NAME, SYNOPSIS, DESCRIPTION, a small EXAMPLE and SEE ALSO. Describe actual compiler support and necessary limitations. Check `reference/697401-2026-pseudocode-guide-for-teachers.pdf` for official syntax; briefly note relevant differences instead of promising unsupported features. + +Use relative Markdown links between source pages, including `../` when crossing categories. Keep the page name and section in the label, such as `cpsc-keyword-if(7)`. `cmake/ManualLinks.lua` renders these as man references or local HTML links. + +## Build and verification + +`doc`, `install` and `release` generate all manuals with Pandoc; ordinary builds do not need it. CMake discovers language sources recursively and preserves categories in generated files and release packages. Windows installs HTML with the same category layout. Unix installs all section 7 pages together in `PREFIX/share/cpsc/man/man7`, alongside the command page in `man1`; manpath registration is handled by the installer. + +Before committing, run `cmake --build build --target doc`, check the affected links and render a changed page with `man -l build/doc/language/keyword/cpsc-keyword-if.7` (use the relevant path). For formatting-only edits, a comparison of Pandoc's man output before and after is sufficient. For path changes, also check HTML links, package contents and a DESTDIR installation. Keep verification simple; do not add a test framework for manual edits. diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md index 7005fa0..a471854 100644 --- a/doc/language/cpsc-language-overview.7.md +++ b/doc/language/cpsc-language-overview.7.md @@ -6,26 +6,15 @@ cpsc-language-overview - supported cpsc pseudocode syntax # DESCRIPTION -Keywords and built-in function names are uppercase and case-sensitive. -Indentation is for readability; blocks use explicit closing keywords. -Identifiers begin with a letter and continue with letters, -digits, or underscores. +Keywords and built-in function names are uppercase and case-sensitive. Indentation is for readability; blocks use explicit closing keywords. Identifiers begin with a letter and continue with letters, digits, or underscores. -Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, -`<`, `>`, `<=`, and `>=`. STRING comparisons compare contents, -case-sensitively. Use `+`, `-`, `*`, and `/` for arithmetic; -`/` always returns REAL. Use `&` to join strings. +Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`, `<=`, and `>=`. STRING comparisons compare contents, case-sensitively. Use `+`, `-`, `*`, and `/` for arithmetic; `/` always returns REAL. Use `&` to join strings. -Precedence, from highest to lowest: unary operators, `* / DIV MOD`, -`+ - &`, comparisons, AND, OR. Parentheses override precedence. +Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence. -Literals include integers, decimal real numbers, TRUE/FALSE, strings in -double quotes, and single-byte characters in single quotes. Negative -numbers use unary minus. There are no string or character escape sequences. -Comments begin with `//` and continue to the end of the line. +Literals include integers, decimal real numbers, TRUE/FALSE, strings in double quotes, and single-byte characters in single quotes. Negative numbers use unary minus. There are no string or character escape sequences. Comments begin with `//` and continue to the end of the line. -Declare variables before use. See DECLARE for built-in types and arrays, -TYPE for records/enumerations/pointers, and CLASS for public/private fields. +Declare variables before use. See DECLARE for built-in types and arrays, TYPE for records/enumerations/pointers, and CLASS for public/private fields. # KEYWORDS @@ -51,13 +40,7 @@ TYPE for records/enumerations/pointers, and CLASS for public/private fields. - [cpsc-keyword-div(7)](keyword/cpsc-keyword-div.7.md): perform integer division. - [cpsc-keyword-mod(7)](keyword/cpsc-keyword-mod.7.md): find the integer division remainder. -Closing and auxiliary keywords are documented with their main constructs: -THEN/ELSE/ENDIF with IF; DO/ENDWHILE with WHILE; UNTIL with REPEAT; -TO/STEP/NEXT with FOR; RETURN/RETURNS/BYVAL/BYREF and function/procedure -closing keywords with FUNCTION/PROCEDURE; READ/WRITE/APPEND with OPENFILE; -ARRAY/OF and INTEGER/REAL/BOOLEAN/CHAR/STRING with DECLARE; -ENDTYPE with TYPE; PUBLIC/PRIVATE/ENDCLASS with CLASS. -TRUE/FALSE are BOOLEAN literals. +Closing and auxiliary keywords are documented with their main constructs: THEN/ELSE/ENDIF with IF; DO/ENDWHILE with WHILE; UNTIL with REPEAT; TO/STEP/NEXT with FOR; RETURN/RETURNS/BYVAL/BYREF and function/procedure closing keywords with FUNCTION/PROCEDURE; READ/WRITE/APPEND with OPENFILE; ARRAY/OF and INTEGER/REAL/BOOLEAN/CHAR/STRING with DECLARE; ENDTYPE with TYPE; PUBLIC/PRIVATE/ENDCLASS with CLASS. TRUE/FALSE are BOOLEAN literals. # BUILT-IN FUNCTIONS @@ -76,13 +59,9 @@ TRUE/FALSE are BOOLEAN literals. # UNSUPPORTED FEATURES -CASE OF, CONSTANT, DATE, SET types and DEFINE, random-file operations -(RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, INPUT into array elements or -fields, string escapes, whole-array assignment or return, array fields, -and class methods/constructors/destructors/inheritance (NEW/INHERITS/SUPER). +CASE OF, CONSTANT, DATE, SET types and DEFINE, random-file operations (RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, INPUT into array elements or fields, string escapes, whole-array assignment or return, array fields, and class methods/constructors/destructors/inheritance (NEW/INHERITS/SUPER). -The individual pages note relevant differences from the Cambridge 2026 -pseudocode guide. This manual describes the compiler's current support. +The individual pages note relevant differences from the Cambridge 2026 pseudocode guide. This manual describes the compiler's current support. # EXAMPLE @@ -97,4 +76,3 @@ ENDIF # SEE ALSO [cpsc(1)](../cpsc.1.md). - diff --git a/doc/language/function/cpsc-function-asc.7.md b/doc/language/function/cpsc-function-asc.7.md index 72403a7..17ba8fe 100644 --- a/doc/language/function/cpsc-function-asc.7.md +++ b/doc/language/function/cpsc-function-asc.7.md @@ -13,8 +13,7 @@ ASC(text : STRING) RETURNS INTEGER # DESCRIPTION -Return the unsigned byte code of the character, or of the first byte of a -string. Use a nonempty string; for ASCII characters this is the ASCII code. +Return the unsigned byte code of the character, or of the first byte of a string. Use a nonempty string; for ASCII characters this is the ASCII code. # EXAMPLE @@ -25,4 +24,3 @@ OUTPUT ASC('A') # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-chr(7)](cpsc-function-chr.7.md). - diff --git a/doc/language/function/cpsc-function-chr.7.md b/doc/language/function/cpsc-function-chr.7.md index 59b3121..1eab413 100644 --- a/doc/language/function/cpsc-function-chr.7.md +++ b/doc/language/function/cpsc-function-chr.7.md @@ -12,9 +12,7 @@ CHR(code : INTEGER) RETURNS STRING # DESCRIPTION -Convert the low eight bits of code to a one-byte string. -The result is STRING, not CHAR. Use ASCII codes 1 to 127 for -ordinary text; code 0 produces an empty string. +Convert the low eight bits of code to a one-byte string. The result is STRING, not CHAR. Use ASCII codes 1 to 127 for ordinary text; code 0 produces an empty string. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT CHR(65) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-asc(7)](cpsc-function-asc.7.md). - diff --git a/doc/language/function/cpsc-function-eof.7.md b/doc/language/function/cpsc-function-eof.7.md index 3ab2d31..397c713 100644 --- a/doc/language/function/cpsc-function-eof.7.md +++ b/doc/language/function/cpsc-function-eof.7.md @@ -12,9 +12,7 @@ EOF(filename : STRING) RETURNS BOOLEAN # DESCRIPTION -Return true when no further characters remain in a file opened FOR READ. -The test does not consume the next character. Testing an unopened file or -a file in the wrong mode terminates execution. +Return true when no further characters remain in a file opened FOR READ. The test does not consume the next character. Testing an unopened file or a file in the wrong mode terminates execution. # EXAMPLE @@ -31,4 +29,3 @@ CLOSEFILE "notes.txt" # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](../keyword/cpsc-keyword-openfile.7.md), [cpsc-keyword-readfile(7)](../keyword/cpsc-keyword-readfile.7.md), [cpsc-keyword-closefile(7)](../keyword/cpsc-keyword-closefile.7.md). - diff --git a/doc/language/function/cpsc-function-is_num.7.md b/doc/language/function/cpsc-function-is_num.7.md index a85acfe..a1fe34e 100644 --- a/doc/language/function/cpsc-function-is_num.7.md +++ b/doc/language/function/cpsc-function-is_num.7.md @@ -12,9 +12,7 @@ IS_NUM(text : STRING) RETURNS BOOLEAN # DESCRIPTION -Return true for a nonempty string fully consumed by the runtime's -numeric conversion. Leading whitespace is accepted; trailing whitespace -or other trailing text is rejected. +Return true for a nonempty string fully consumed by the runtime's numeric conversion. Leading whitespace is accepted; trailing whitespace or other trailing text is rejected. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT IS_NUM("12.5") # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md). - diff --git a/doc/language/function/cpsc-function-lcase.7.md b/doc/language/function/cpsc-function-lcase.7.md index c8c7db9..a2cbf44 100644 --- a/doc/language/function/cpsc-function-lcase.7.md +++ b/doc/language/function/cpsc-function-lcase.7.md @@ -12,9 +12,7 @@ LCASE(text : STRING) RETURNS STRING # DESCRIPTION -Return a copy with letters converted to lower case. Unlike guide section 5.5's -CHAR-to-CHAR signature, cpsc accepts text and returns STRING. Use ASCII -text for predictable character conversion. +Return a copy with letters converted to lower case. Unlike guide section 5.5's CHAR-to-CHAR signature, cpsc accepts text and returns STRING. Use ASCII text for predictable character conversion. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT LCASE("HELLO") # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-ucase(7)](cpsc-function-ucase.7.md). - diff --git a/doc/language/function/cpsc-function-left.7.md b/doc/language/function/cpsc-function-left.7.md index 38a703e..8f27e24 100644 --- a/doc/language/function/cpsc-function-left.7.md +++ b/doc/language/function/cpsc-function-left.7.md @@ -12,8 +12,7 @@ LEFT(text : STRING, count : INTEGER) RETURNS STRING # DESCRIPTION -Return up to count bytes from the beginning. Counts larger than the string -length return the whole string; negative counts return an empty string. +Return up to count bytes from the beginning. Counts larger than the string length return the whole string; negative counts return an empty string. # EXAMPLE @@ -24,4 +23,3 @@ OUTPUT LEFT("Hello", 2) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-right(7)](cpsc-function-right.7.md), [cpsc-function-mid(7)](cpsc-function-mid.7.md). - diff --git a/doc/language/function/cpsc-function-length.7.md b/doc/language/function/cpsc-function-length.7.md index 9730798..fcdc47a 100644 --- a/doc/language/function/cpsc-function-length.7.md +++ b/doc/language/function/cpsc-function-length.7.md @@ -12,8 +12,7 @@ LENGTH(text : STRING) RETURNS INTEGER # DESCRIPTION -Return the number of bytes before the string terminator. String operations -are byte-based, so this is not a Unicode character count. +Return the number of bytes before the string terminator. String operations are byte-based, so this is not a Unicode character count. # EXAMPLE @@ -24,4 +23,3 @@ OUTPUT LENGTH("Hello") # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-mid(7)](cpsc-function-mid.7.md), [cpsc-function-left(7)](cpsc-function-left.7.md), [cpsc-function-right(7)](cpsc-function-right.7.md). - diff --git a/doc/language/function/cpsc-function-mid.7.md b/doc/language/function/cpsc-function-mid.7.md index 66f7294..0956b43 100644 --- a/doc/language/function/cpsc-function-mid.7.md +++ b/doc/language/function/cpsc-function-mid.7.md @@ -12,9 +12,7 @@ MID(text : STRING, start : INTEGER, count : INTEGER) RETURNS STRING # DESCRIPTION -Return up to count bytes starting at the one-based position start. -Positions below 1 clamp to 1; positions beyond the end return an empty string. -The count clamps to the available bytes; negative counts return an empty string. +Return up to count bytes starting at the one-based position start. Positions below 1 clamp to 1; positions beyond the end return an empty string. The count clamps to the available bytes; negative counts return an empty string. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT MID("ABCDEFGH", 2, 3) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-left(7)](cpsc-function-left.7.md), [cpsc-function-right(7)](cpsc-function-right.7.md), [cpsc-function-length(7)](cpsc-function-length.7.md). - diff --git a/doc/language/function/cpsc-function-num_to_str.7.md b/doc/language/function/cpsc-function-num_to_str.7.md index fb4f6fc..fb8e6fd 100644 --- a/doc/language/function/cpsc-function-num_to_str.7.md +++ b/doc/language/function/cpsc-function-num_to_str.7.md @@ -12,8 +12,7 @@ NUM_TO_STR(number : INTEGER or REAL) RETURNS STRING # DESCRIPTION -Format INTEGER as signed decimal text and REAL with six digits after the -decimal point. +Format INTEGER as signed decimal text and REAL with six digits after the decimal point. # EXAMPLE @@ -24,4 +23,3 @@ OUTPUT NUM_TO_STR(42), " ", NUM_TO_STR(3.5) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md). - diff --git a/doc/language/function/cpsc-function-right.7.md b/doc/language/function/cpsc-function-right.7.md index 9aa10e6..2f70fbd 100644 --- a/doc/language/function/cpsc-function-right.7.md +++ b/doc/language/function/cpsc-function-right.7.md @@ -12,8 +12,7 @@ RIGHT(text : STRING, count : INTEGER) RETURNS STRING # DESCRIPTION -Return up to count bytes from the end. Use a nonnegative count. -Counts larger than the string length return the whole string. +Return up to count bytes from the end. Use a nonnegative count. Counts larger than the string length return the whole string. # EXAMPLE @@ -24,4 +23,3 @@ OUTPUT RIGHT("Hello", 2) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-left(7)](cpsc-function-left.7.md), [cpsc-function-mid(7)](cpsc-function-mid.7.md). - diff --git a/doc/language/function/cpsc-function-str_to_num.7.md b/doc/language/function/cpsc-function-str_to_num.7.md index 341b757..b0ceef2 100644 --- a/doc/language/function/cpsc-function-str_to_num.7.md +++ b/doc/language/function/cpsc-function-str_to_num.7.md @@ -12,9 +12,7 @@ STR_TO_NUM(text : STRING) RETURNS REAL # DESCRIPTION -Return REAL, including for integer-looking text. Conversion can stop at -trailing text; invalid text returns zero. Use IS_NUM first when the whole -string must be a valid number. +Return REAL, including for integer-looking text. Conversion can stop at trailing text; invalid text returns zero. Use IS_NUM first when the whole string must be a valid number. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT STR_TO_NUM("12.5") # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-is_num(7)](cpsc-function-is_num.7.md), [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md). - diff --git a/doc/language/function/cpsc-function-ucase.7.md b/doc/language/function/cpsc-function-ucase.7.md index 6356f48..728ae14 100644 --- a/doc/language/function/cpsc-function-ucase.7.md +++ b/doc/language/function/cpsc-function-ucase.7.md @@ -12,9 +12,7 @@ UCASE(text : STRING) RETURNS STRING # DESCRIPTION -Return a copy with letters converted to upper case. Unlike guide section 5.5's -CHAR-to-CHAR signature, cpsc accepts text and returns STRING. Use ASCII -text for predictable character conversion. +Return a copy with letters converted to upper case. Unlike guide section 5.5's CHAR-to-CHAR signature, cpsc accepts text and returns STRING. Use ASCII text for predictable character conversion. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT UCASE("Hello") # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-lcase(7)](cpsc-function-lcase.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-and.7.md b/doc/language/keyword/cpsc-keyword-and.7.md index 8df8c56..1577798 100644 --- a/doc/language/keyword/cpsc-keyword-and.7.md +++ b/doc/language/keyword/cpsc-keyword-and.7.md @@ -12,9 +12,7 @@ left AND right # DESCRIPTION -Return BOOLEAN: true when both operands are true. Both operands are -evaluated; AND does not short-circuit. AND binds more tightly than OR -and less tightly than comparisons. Use parentheses for clarity. +Return BOOLEAN: true when both operands are true. Both operands are evaluated; AND does not short-circuit. AND binds more tightly than OR and less tightly than comparisons. Use parentheses for clarity. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT (3 > 2) AND (4 > 1) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-or(7)](cpsc-keyword-or.7.md), [cpsc-keyword-not(7)](cpsc-keyword-not.7.md), [cpsc-keyword-if(7)](cpsc-keyword-if.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-call.7.md b/doc/language/keyword/cpsc-keyword-call.7.md index e999a8b..0972e5e 100644 --- a/doc/language/keyword/cpsc-keyword-call.7.md +++ b/doc/language/keyword/cpsc-keyword-call.7.md @@ -12,9 +12,7 @@ CALL name(arguments) # DESCRIPTION -Invoke a previously declared procedure with its parameters. Empty argument -lists may be written `CALL name()` or `CALL name`. -Use function calls in expressions to obtain their results. +Invoke a previously declared procedure with its parameters. Empty argument lists may be written `CALL name()` or `CALL name`. Use function calls in expressions to obtain their results. # EXAMPLE @@ -28,4 +26,3 @@ CALL Hello() # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-class.7.md b/doc/language/keyword/cpsc-keyword-class.7.md index d7ec12f..7e8f6e3 100644 --- a/doc/language/keyword/cpsc-keyword-class.7.md +++ b/doc/language/keyword/cpsc-keyword-class.7.md @@ -15,15 +15,9 @@ ENDCLASS # DESCRIPTION -Declare a class at top level with at least one field. Every field explicitly -requires PUBLIC or PRIVATE, without DECLARE. This differs from guide -section 10's default-public rule. ENDCLASS closes the declaration. +Declare a class at top level with at least one field. Every field explicitly requires PUBLIC or PRIVATE, without DECLARE. This differs from guide section 10's default-public rule. ENDCLASS closes the declaration. -Classes use record value semantics: zero initialization, whole-value copying, -arrays, pointers, and ordinary function/procedure parameters. Only PUBLIC -fields can be accessed externally. PRIVATE fields still initialize and copy -with the whole value. Methods, constructors, destructors, NEW, INHERITS, -and array fields are unsupported. +Classes use record value semantics: zero initialization, whole-value copying, arrays, pointers, and ordinary function/procedure parameters. Only PUBLIC fields can be accessed externally. PRIVATE fields still initialize and copy with the whole value. Methods, constructors, destructors, NEW, INHERITS, and array fields are unsupported. # EXAMPLE @@ -40,4 +34,3 @@ OUTPUT PersonValue.Name # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-type(7)](cpsc-keyword-type.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-closefile.7.md b/doc/language/keyword/cpsc-keyword-closefile.7.md index 381ae56..2359b82 100644 --- a/doc/language/keyword/cpsc-keyword-closefile.7.md +++ b/doc/language/keyword/cpsc-keyword-closefile.7.md @@ -12,8 +12,7 @@ CLOSEFILE filename # DESCRIPTION -Close the file associated with this filename string and release its open-file -slot. Closing a filename that is not open terminates execution. +Close the file associated with this filename string and release its open-file slot. Closing a filename that is not open terminates execution. # EXAMPLE @@ -26,4 +25,3 @@ CLOSEFILE "notes.txt" # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-readfile(7)](cpsc-keyword-readfile.7.md), [cpsc-keyword-writefile(7)](cpsc-keyword-writefile.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-declare.7.md b/doc/language/keyword/cpsc-keyword-declare.7.md index 7fe1cf6..0c4ea28 100644 --- a/doc/language/keyword/cpsc-keyword-declare.7.md +++ b/doc/language/keyword/cpsc-keyword-declare.7.md @@ -13,16 +13,9 @@ DECLARE name : ARRAY[lower:upper, ...] OF type # DESCRIPTION -Declare one variable per statement. Built-in types are INTEGER (signed 64-bit), -REAL, BOOLEAN, CHAR (one byte), and STRING. User-defined TYPE and CLASS names -are also accepted. Variables start with zero, FALSE, an empty string, or a -zero-initialized user-defined value. +Declare one variable per statement. Built-in types are INTEGER (signed 64-bit), REAL, BOOLEAN, CHAR (one byte), and STRING. User-defined TYPE and CLASS names are also accepted. Variables start with zero, FALSE, an empty string, or a zero-initialized user-defined value. -ARRAY bounds are inclusive and may be expressions; multiple ranges create -multiple dimensions. Access elements with `name[index, ...]`. Bounds are -checked at run time. Whole-array assignment is unsupported. Declare arrays -before using them; arrays declared inside a control-flow block stay in that -block. +ARRAY bounds are inclusive and may be expressions; multiple ranges create multiple dimensions. Access elements with `name[index, ...]`. Bounds are checked at run time. Whole-array assignment is unsupported. Declare arrays before using them; arrays declared inside a control-flow block stay in that block. # EXAMPLE @@ -37,4 +30,3 @@ OUTPUT Names[Count] # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-type(7)](cpsc-keyword-type.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-output(7)](cpsc-keyword-output.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-div.7.md b/doc/language/keyword/cpsc-keyword-div.7.md index 6adb23d..f033633 100644 --- a/doc/language/keyword/cpsc-keyword-div.7.md +++ b/doc/language/keyword/cpsc-keyword-div.7.md @@ -12,9 +12,7 @@ left DIV right # DESCRIPTION -Both operands must be INTEGER. Return the quotient truncated toward zero. -A zero divisor terminates execution. DIV has the same precedence as -multiplication. Use `/` for division returning REAL. +Both operands must be INTEGER. Return the quotient truncated toward zero. A zero divisor terminates execution. DIV has the same precedence as multiplication. Use `/` for division returning REAL. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT 7 DIV 2 # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-mod(7)](cpsc-keyword-mod.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-for.7.md b/doc/language/keyword/cpsc-keyword-for.7.md index 57b5632..3906e18 100644 --- a/doc/language/keyword/cpsc-keyword-for.7.md +++ b/doc/language/keyword/cpsc-keyword-for.7.md @@ -14,11 +14,7 @@ NEXT variable # DESCRIPTION -The loop variable must already be declared INTEGER. Both endpoints are -inclusive. STEP defaults to 1; use a negative value to count down. -STEP is evaluated once, while the finish expression is evaluated each -iteration. NEXT must name the same variable. Use a nonzero STEP. -TO, STEP, and NEXT belong to this syntax. +The loop variable must already be declared INTEGER. Both endpoints are inclusive. STEP defaults to 1; use a negative value to count down. STEP is evaluated once, while the finish expression is evaluated each iteration. NEXT must name the same variable. Use a nonzero STEP. TO, STEP, and NEXT belong to this syntax. # EXAMPLE @@ -32,4 +28,3 @@ NEXT Index # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-while(7)](cpsc-keyword-while.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-function.7.md b/doc/language/keyword/cpsc-keyword-function.7.md index d687ba9..85347b1 100644 --- a/doc/language/keyword/cpsc-keyword-function.7.md +++ b/doc/language/keyword/cpsc-keyword-function.7.md @@ -15,16 +15,9 @@ ENDFUNCTION # DESCRIPTION -Call a function in an expression as `name(arguments)`. A call may precede its -top-level definition. RETURNS specifies the result type; omitting it defaults -to INTEGER. RETURN supplies a value of that type. Whole-array results are -unsupported. +Call a function in an expression as `name(arguments)`. A call may precede its top-level definition. RETURNS specifies the result type; omitting it defaults to INTEGER. RETURN supplies a value of that type. Whole-array results are unsupported. -Parameters use `name : type`, optionally prefixed by BYVAL. BYVAL is the -default; BYREF is forbidden for functions (guide section 8.3). -Array parameters accept `ARRAY OF type` (one dimension) or -`ARRAY[lower:upper, ...] OF type` (integer literal bounds). -BYVAL arrays are copied. RETURNS, RETURN, BYVAL, and ENDFUNCTION belong here. +Parameters use `name : type`, optionally prefixed by BYVAL. BYVAL is the default; BYREF is forbidden for functions (guide section 8.3). Array parameters accept `ARRAY OF type` (one dimension) or `ARRAY[lower:upper, ...] OF type` (integer literal bounds). BYVAL arrays are copied. RETURNS, RETURN, BYVAL, and ENDFUNCTION belong here. # EXAMPLE @@ -38,4 +31,3 @@ OUTPUT Double(4) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-if.7.md b/doc/language/keyword/cpsc-keyword-if.7.md index a934922..a7d13ad 100644 --- a/doc/language/keyword/cpsc-keyword-if.7.md +++ b/doc/language/keyword/cpsc-keyword-if.7.md @@ -16,8 +16,7 @@ ENDIF # DESCRIPTION -Execute the THEN branch when the condition is true, otherwise the optional -ELSE branch. Blocks may be nested. THEN, ELSE, and ENDIF belong to this syntax. +Execute the THEN branch when the condition is true, otherwise the optional ELSE branch. Blocks may be nested. THEN, ELSE, and ENDIF belong to this syntax. # EXAMPLE @@ -32,4 +31,3 @@ ENDIF # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-and(7)](cpsc-keyword-and.7.md), [cpsc-keyword-or(7)](cpsc-keyword-or.7.md), [cpsc-keyword-not(7)](cpsc-keyword-not.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-input.7.md b/doc/language/keyword/cpsc-keyword-input.7.md index c14fac1..7bc1c73 100644 --- a/doc/language/keyword/cpsc-keyword-input.7.md +++ b/doc/language/keyword/cpsc-keyword-input.7.md @@ -12,10 +12,7 @@ INPUT variable # DESCRIPTION -Read into a previously declared INTEGER, REAL, BOOLEAN, CHAR, or STRING -variable. STRING input reads one whitespace-delimited word. The target must -be a plain variable; array elements and record/class fields are unsupported, -unlike the wider INPUT syntax in guide section 5.1. +Read into a previously declared INTEGER, REAL, BOOLEAN, CHAR, or STRING variable. STRING input reads one whitespace-delimited word. The target must be a plain variable; array elements and record/class fields are unsupported, unlike the wider INPUT syntax in guide section 5.1. # EXAMPLE @@ -28,4 +25,3 @@ OUTPUT Name # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-output(7)](cpsc-keyword-output.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-mod.7.md b/doc/language/keyword/cpsc-keyword-mod.7.md index 2eceeb5..ea1b431 100644 --- a/doc/language/keyword/cpsc-keyword-mod.7.md +++ b/doc/language/keyword/cpsc-keyword-mod.7.md @@ -12,10 +12,7 @@ left MOD right # DESCRIPTION -Both operands must be INTEGER. Return the remainder after division truncated -toward zero; a nonzero remainder has the dividend's sign. -A zero divisor terminates execution. MOD has the same precedence as -multiplication. +Both operands must be INTEGER. Return the remainder after division truncated toward zero; a nonzero remainder has the dividend's sign. A zero divisor terminates execution. MOD has the same precedence as multiplication. # EXAMPLE @@ -26,4 +23,3 @@ OUTPUT 7 MOD 2 # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-div(7)](cpsc-keyword-div.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-not.7.md b/doc/language/keyword/cpsc-keyword-not.7.md index 0ada425..36a051d 100644 --- a/doc/language/keyword/cpsc-keyword-not.7.md +++ b/doc/language/keyword/cpsc-keyword-not.7.md @@ -12,8 +12,7 @@ NOT expression # DESCRIPTION -Return BOOLEAN with the opposite truth value. NOT is a unary operator; -parenthesize comparisons, for example `NOT (Count = 0)`. +Return BOOLEAN with the opposite truth value. NOT is a unary operator; parenthesize comparisons, for example `NOT (Count = 0)`. # EXAMPLE @@ -24,4 +23,3 @@ OUTPUT NOT (3 = 2) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-and(7)](cpsc-keyword-and.7.md), [cpsc-keyword-or(7)](cpsc-keyword-or.7.md), [cpsc-keyword-if(7)](cpsc-keyword-if.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-openfile.7.md b/doc/language/keyword/cpsc-keyword-openfile.7.md index 2aa2b44..c2c3743 100644 --- a/doc/language/keyword/cpsc-keyword-openfile.7.md +++ b/doc/language/keyword/cpsc-keyword-openfile.7.md @@ -14,14 +14,9 @@ OPENFILE filename FOR APPEND # DESCRIPTION -The filename is a STRING expression. READ opens an existing file for reading; -WRITE creates or truncates a file; APPEND writes at the end, creating the file -if needed. READ, WRITE, APPEND, and this use of FOR belong here. +The filename is a STRING expression. READ opens an existing file for reading; WRITE creates or truncates a file; APPEND writes at the end, creating the file if needed. READ, WRITE, APPEND, and this use of FOR belong here. -At most 16 files may be open at once. Use the same filename string for -subsequent operations. Reopening an open filename, failed opens, and wrong-mode -operations terminate execution with a fatal diagnostic. RANDOM is reserved -but unsupported. +At most 16 files may be open at once. Use the same filename string for subsequent operations. Reopening an open filename, failed opens, and wrong-mode operations terminate execution with a fatal diagnostic. RANDOM is reserved but unsupported. # EXAMPLE @@ -34,4 +29,3 @@ CLOSEFILE "notes.txt" # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-readfile(7)](cpsc-keyword-readfile.7.md), [cpsc-keyword-writefile(7)](cpsc-keyword-writefile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-or.7.md b/doc/language/keyword/cpsc-keyword-or.7.md index 4594215..df861de 100644 --- a/doc/language/keyword/cpsc-keyword-or.7.md +++ b/doc/language/keyword/cpsc-keyword-or.7.md @@ -12,9 +12,7 @@ left OR right # DESCRIPTION -Return BOOLEAN: true when either operand is true. Both operands are -evaluated; OR does not short-circuit. OR binds less tightly than AND -and comparisons. +Return BOOLEAN: true when either operand is true. Both operands are evaluated; OR does not short-circuit. OR binds less tightly than AND and comparisons. # EXAMPLE @@ -25,4 +23,3 @@ OUTPUT (3 < 2) OR (4 > 1) # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-and(7)](cpsc-keyword-and.7.md), [cpsc-keyword-not(7)](cpsc-keyword-not.7.md), [cpsc-keyword-if(7)](cpsc-keyword-if.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-output.7.md b/doc/language/keyword/cpsc-keyword-output.7.md index a1c2d2a..90d4e82 100644 --- a/doc/language/keyword/cpsc-keyword-output.7.md +++ b/doc/language/keyword/cpsc-keyword-output.7.md @@ -12,11 +12,7 @@ OUTPUT expression, ... # DESCRIPTION -Print expressions from left to right without automatic separators, then add -a newline. Strings print their contents; BOOLEAN prints TRUE or FALSE. -Whole arrays and partially indexed arrays print their elements one per line; -a final array adds no extra newline. Records, classes, and pointers cannot -be printed directly. +Print expressions from left to right without automatic separators, then add a newline. Strings print their contents; BOOLEAN prints TRUE or FALSE. Whole arrays and partially indexed arrays print their elements one per line; a final array adds no extra newline. Records, classes, and pointers cannot be printed directly. # EXAMPLE @@ -29,4 +25,3 @@ OUTPUT "Score: ", Score # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-input(7)](cpsc-keyword-input.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-procedure.7.md b/doc/language/keyword/cpsc-keyword-procedure.7.md index d8be9f4..2880f11 100644 --- a/doc/language/keyword/cpsc-keyword-procedure.7.md +++ b/doc/language/keyword/cpsc-keyword-procedure.7.md @@ -14,17 +14,9 @@ ENDPROCEDURE # DESCRIPTION -Invoke with CALL. Parameters use `name : type`, optionally prefixed by -BYVAL or BYREF. The default is BYVAL (copy); BYREF modifies the caller's -variable and requires an exact type match. Scalar BYREF arguments must be -plain variables. A mode remains in effect for following parameters until -another mode is specified. +Invoke with CALL. Parameters use `name : type`, optionally prefixed by BYVAL or BYREF. The default is BYVAL (copy); BYREF modifies the caller's variable and requires an exact type match. Scalar BYREF arguments must be plain variables. A mode remains in effect for following parameters until another mode is specified. -Arrays accept `ARRAY OF type` or `ARRAY[lower:upper, ...] OF type`; -explicit bounds must be integer literals. BYVAL copies the array; BYREF -shares it. Bare RETURN can exit a procedure before a block terminator; -RETURN with a value is invalid. BYVAL, BYREF, RETURN, and ENDPROCEDURE -belong here. Calls may precede top-level definitions. +Arrays accept `ARRAY OF type` or `ARRAY[lower:upper, ...] OF type`; explicit bounds must be integer literals. BYVAL copies the array; BYREF shares it. Bare RETURN can exit a procedure before a block terminator; RETURN with a value is invalid. BYVAL, BYREF, RETURN, and ENDPROCEDURE belong here. Calls may precede top-level definitions. # EXAMPLE @@ -40,4 +32,3 @@ OUTPUT Count # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-readfile.7.md b/doc/language/keyword/cpsc-keyword-readfile.7.md index 8260dd2..de0e849 100644 --- a/doc/language/keyword/cpsc-keyword-readfile.7.md +++ b/doc/language/keyword/cpsc-keyword-readfile.7.md @@ -12,9 +12,7 @@ READFILE filename, variable # DESCRIPTION -Read one line from a file opened FOR READ, removing the line ending. -The target must be a plain, previously declared STRING variable. -Guard reads with EOF; reading past the end terminates execution. +Read one line from a file opened FOR READ, removing the line ending. The target must be a plain, previously declared STRING variable. Guard reads with EOF; reading past the end terminates execution. # EXAMPLE @@ -31,4 +29,3 @@ CLOSEFILE "notes.txt" # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md), [cpsc-function-eof(7)](../function/cpsc-function-eof.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-repeat.7.md b/doc/language/keyword/cpsc-keyword-repeat.7.md index b1a73c2..222fd17 100644 --- a/doc/language/keyword/cpsc-keyword-repeat.7.md +++ b/doc/language/keyword/cpsc-keyword-repeat.7.md @@ -14,8 +14,7 @@ UNTIL condition # DESCRIPTION -Test after each iteration, so the body runs at least once. -Stop when the condition becomes true. UNTIL belongs to this syntax. +Test after each iteration, so the body runs at least once. Stop when the condition becomes true. UNTIL belongs to this syntax. # EXAMPLE @@ -31,4 +30,3 @@ UNTIL Count = 3 # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-while(7)](cpsc-keyword-while.7.md), [cpsc-keyword-for(7)](cpsc-keyword-for.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-type.7.md b/doc/language/keyword/cpsc-keyword-type.7.md index 9dd4c73..5159dd5 100644 --- a/doc/language/keyword/cpsc-keyword-type.7.md +++ b/doc/language/keyword/cpsc-keyword-type.7.md @@ -16,21 +16,11 @@ ENDTYPE # DESCRIPTION -Define types at top level. Enumeration values have globally reserved names; -OUTPUT prints their zero-based ordinals. Enumerations support comparisons -with the same type and addition/subtraction of INTEGER offsets; invalid -ordinals terminate execution. +Define types at top level. Enumeration values have globally reserved names; OUTPUT prints their zero-based ordinals. Enumerations support comparisons with the same type and addition/subtraction of INTEGER offsets; invalid ordinals terminate execution. -A prefix caret takes an address (`^variable`); a suffix caret dereferences -a pointer (`pointer^`). Pointee types must match exactly, even where guide -section 4.2's example mixes types. Pointers start null; dereferencing null -terminates execution. There is no NULL literal. Avoid pointers to local -variables after the function returns. +A prefix caret takes an address (`^variable`); a suffix caret dereferences a pointer (`pointer^`). Pointee types must match exactly, even where guide section 4.2's example mixes types. Pointers start null; dereferencing null terminates execution. There is no NULL literal. Avoid pointers to local variables after the function returns. -Records contain one or more DECLARE fields and end with ENDTYPE. Access -fields with a dot. Whole records copy by value; array fields are unsupported. -Distinct user-defined type names remain distinct types. SET/DEFINE are -reserved but unsupported. +Records contain one or more DECLARE fields and end with ENDTYPE. Access fields with a dot. Whole records copy by value; array fields are unsupported. Distinct user-defined type names remain distinct types. SET/DEFINE are reserved but unsupported. # EXAMPLE @@ -50,4 +40,3 @@ OUTPUT Position.X # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-while.7.md b/doc/language/keyword/cpsc-keyword-while.7.md index c6d8721..5e6656f 100644 --- a/doc/language/keyword/cpsc-keyword-while.7.md +++ b/doc/language/keyword/cpsc-keyword-while.7.md @@ -14,8 +14,7 @@ ENDWHILE # DESCRIPTION -Test before each iteration; the body may run zero times. -DO and ENDWHILE belong to this syntax. +Test before each iteration; the body may run zero times. DO and ENDWHILE belong to this syntax. # EXAMPLE @@ -31,4 +30,3 @@ ENDWHILE # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-repeat(7)](cpsc-keyword-repeat.7.md), [cpsc-keyword-for(7)](cpsc-keyword-for.7.md). - diff --git a/doc/language/keyword/cpsc-keyword-writefile.7.md b/doc/language/keyword/cpsc-keyword-writefile.7.md index caeafe7..d3ce2c4 100644 --- a/doc/language/keyword/cpsc-keyword-writefile.7.md +++ b/doc/language/keyword/cpsc-keyword-writefile.7.md @@ -12,9 +12,7 @@ WRITEFILE filename, expression # DESCRIPTION -Write one value as text followed by a newline. Open the file FOR WRITE or -APPEND first. Exactly one data expression is accepted; join strings with -`&` when needed. Records, classes, and pointers are unsupported as data. +Write one value as text followed by a newline. Open the file FOR WRITE or APPEND first. Exactly one data expression is accepted; join strings with `&` when needed. Records, classes, and pointers are unsupported as data. # EXAMPLE @@ -27,4 +25,3 @@ CLOSEFILE "notes.txt" # SEE ALSO [cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md), [cpsc-function-num_to_str(7)](../function/cpsc-function-num_to_str.7.md). - |