You can edit this page using wiki syntax for markup.

Article contents:== chalk-bin Generate in-source documentation [[toc:]] === Introduction [[https://wiki.call-cc.org/eggref/6/chalk|chalk]] (syntax) + [[https://wiki.call-cc.org/eggref/6/chalk-bin|chalk-bin]] (doc generation) attempts to be a simpler alternative to Chicken 4's [[https://wiki.call-cc.org/eggref/4/hahn|hahn]] + [[https://wiki.call-cc.org/eggref/4/hahn-utils|hahn-utils]], generating wiki output with support for procedure, variables, syntax, modules, include files,and egg files. It tries to be as basic as possible, performing almost no code analysis and no evaluation, while making it easy to generate documentation from one or more files. The following is hahn's fibonacci example, rewritten for chalk. Note key differences: The example is simply a string (and therefore not evaluated), whith the option of a {{@pre}} or {{@post}} caption. <enscript highlight="scheme"> (define (fibonacci n) @("Computes the nth [[http://en.wikipedia.org/wiki/Fibonacci_number|Fibonacci]]. This naïve algorithm runs in ''O(2^n)''; using e.g. memoization, we could bring it down to ''O(n)''." (n "The nth number to calculate") (@to "integer") (@example (@pre "For example, computing the 6th Fibonnaci number (starting from 0)") "(fibonacci 6) ; => 8")) (case n ((0) 0) ((1) 1) (else (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))) </enscript> Which produces the following wiki output: <procedure>(fibonacci n) -> integer</procedure> Computes the nth [[http://en.wikipedia.org/wiki/Fibonacci_number|Fibonacci]]. This naïve algorithm runs in ''O(2^n)''; using e.g. memoization, we could bring it down to ''O(n)''. ; n : The nth number to calculate For example, computing the 6th Fibonnaci number (starting from 0) <enscript highlight="scheme"> (fibonacci 6) ; => 8 </enscript> === Syntax Most expressions of the following form can be documented to varying degrees of automation, where {{SIGNATURE}} can be a pair (as in a procedure definition). <enscript> (DEFINE SIGNATURE BODY ...) </enscript> {{DEFINE}} can be the literal symbol {{define}} or a symbol that starts with it. Documentation entails inserting a docexpr of the following form before the {{BODY}}: <enscript> @("Description" ... [OPTION] ...) </enscript> Strings and options can appear in any order. Top-level strings in the docexpr are turned into separate wiki paragraphs. As a shorthand for a single-paragraph description with no options, you can use: <enscript> @"Single-paragraph description" </enscript> ==== Variables Variables are documented as follows, ignoring potentially disastrous rounding practices: <enscript> (define pi @("The ratio of a circle's circumference to its diameter.") 3.14) </enscript> The special tag {{@internal}} can be used to suppress output, and is useful for documenting unexported variables internally: <enscript> (define counter @("How many times thing has happened." (@internal))) </enscript> Chalk will also recognize {{define-foreign-variable}} definitions as variables. ==== Procedures Procedures are documented similarly, but can contain the tags {{@to}}, and {{@example}}, as well as listing function parameters: <enscript highlight="scheme"> (define (foobar a b) @("Does baz." (a "An input") (b "Another input") (@to integer) (@example (@pre "For example, to do baz with foobar:") "(foobar blarg arg) ; => 4")) (baz)) </enscript> Chalk can also recognize procedures defined by directly using {{make-parameter}}, {{lambda}},and the variants of {{foreign-lambda}}. In other cases, for example using {{define}} with bespoke macros or functions, chalk has no way of knowing they are procedures and considers them variables by default, using the function name as a signature. In any case, you can override the default signature with the tag {{@sig}}, and you can specify that it is indeed a procedure as follows: <enscript> (define function? @(procedure "This is definitely a procedure" (@sig (function? a b c))) (procedure-generating-macro)) </enscript> You can specify that a variable is a procedure by using the symbol {{procedure}} as the first position of the docexpr. Tags behave as follows: ; {{@to}} : A string or expression to be inserted as {{→ expr}} ; {{@example}} : A string to be enscripted with scheme highlighting, with optional {{@pre}} or {{@post}} caption. ; {{@sig}} : A string or expression that override the procedure signature ; {{@internal}} : Suppress output, documented fro internal use ==== Syntax definitions Syntax definitions accept the same tags and are defined equivalently to procedures, provided that it they are defined using {{define-syntax}}. The {{@sig}} tag is especially useful for specifying syntax usage, since chalk won't automatically detect the signature. Here's a rather silly example: <enscript highlight="scheme"> (define-syntax hello @("Hello there!" (@sig (hello a b c))) (syntax-rules () ((_ a b c) "Hello there!"))) </enscript> Otherwise, you can specify that a definition is syntax like so: <enscript highlight="scheme"> (define-syntax-rule (hello a b c) @(syntax "Hello") "Hello there") </enscript> You can specify that a definition is syntax with either {{syntax}} or {{macro}} in the first position of the docexpr. ==== Records Currently, two types of record definitions are supported - {{define-record}} and {{define-record-type}} from {{chicken.base}}. Records can be documented internally by specifying a {{@internal}} file, and they additionally accept the tag {{@full}}. When specified, it generates a list of all of the procedures associated with that record definition. Otherwise, only the record name is documented, and procedure documentation can be added manually. For example: <enscript highlight="scheme"> (define-record point @("A point" (@full)) x y) </enscript> Produces the following output: <record>record</record> <procedure>(make-point x y)</procedure> <procedure>point?</procedure> <procedure>point-x</procedure> <procedure>point-y</procedure> A point ==== Standalone definition documentation If you need to document an arbitrary definition that doesn't fit neatly into a form that chalk recognizes, you can use a "free signature" declaration: <enscript> @(procedure (@sig "(my-special-procedure)") "Chalk didn't recognize this, so I inserted it manually...") </enscript> Which renders as: <procedure>(my-special-procedure)</procedure> Chalk didn't recognize this, so I inserted it manually... All of the definition tags documented in [[/edit-help|Editing help]] are supported. ==== Top-level documentation ===== Paragraph A docexpr outside of a definition can be used to insert arbitrary text. <enscript highlight="scheme"> @("First paragraph" "Second paragraph" "Third paragraph") @"Single paragraph" </enscript> ===== {{script}} Generate an enscript block, with optional highlight tag. Can contain multiple strings. <enscript highlight="scheme"> @(script (@highlight "scheme") "(print \"hello\")" "(print 4)") </enscript> ===== {{==}} and subheadings A title, with several supported variants. <enscript highlight="scheme"> @(== "A title") @(=== "A subheading") @(== 1 "Same level subheading") </enscript> ; {{heading}}, {{subtitle}}, {{==}} : Optionally takes a number as the second element to specify heading level (0-indexed). ; {{subheading}}, {{subtitle}}, {{===}} : ; {{subsubheading}}, subsubtitle, {{====}} : ; {{subsubsubheading}}, {{subsubsubtitle}}, {{=====}} : ===== {{deflist}} A definition list. <enscript highlight="scheme"> @(deflist (key "value") (definitionless-term) (term "definition")) </enscript> ===== {{list}}, {{numlist}} A list or numbered list, which may be nested! For example, the following: <enscript highlight="scheme"> @(list "foo" "bar" "baz" ("cat" (list "dog" "mouse")) ("frisbee" (numlist "Yes" "no"))) </enscript> Produces the nested list: * foo * bar * baz * cat ** dog ** mouse * frisbee *# Yes *# no ===== {{table}} A table with an optional header <enscript highlight="scheme"> @(table (@header ("A" "B" "C")) ("It's" "Easy" "As") ("1" "2" "3")) </enscript> Renderd as: <table> <tr><th>A</th><th>B</th><th>C</th></tr> <tr><td>It's</td><td>Easy</td><td>As</td></tr> <tr><td>1</td><td>2</td><td>3</td></tr> </table> ==== Inline markup Inline markup like bold, italic, code, and links can be specified using svnwiki syntax. These are converted to other formats using [[/eggref/6/svnwiki-sxml|svnwiki-sxml]] === Chalk program usage The chalk program generates output to stdout or a specified output file based on the given input file(s), and optionally: a {{.egg}} file, a {{.release-info}} file, and/or a {{LICENSE}} file. For more info, see {{chalk --help}}: <enscript> Usage: chalk [OPTION]... [FILE]... -h, --help Print usage -o, --output=FILE Write out to file. Repeateable, extension determines format. -i, --ignore-egg Ignore .egg file -d, --def-heading[=LEVEL]Generate a heading for each definition -r, --ignore-release Ignore .release-info file -n, --no-toc Don't add a toc -e, --email=EMAIL Include EMAIL with maintainer -H, --head=FILE File to add to beginning of documentation -P, --prologue=FILE File to add after synopsis -E, --epilogue=FILE File to add before maintainer info -T, --tail=FILE File to add to end of documentation -L, --no-license Don't insert a license file -l, --license=FILE File to use as license (defaults to LICENSE if unspecified) </enscript> ==== Release-info format A {{.release-info}} file can contain optional comments following {{release}} expressions (on the same line), which are used as version descriptions when generating a version history section of the documentation, for example: <enscript highlight="scheme"> (uri targz "https://example-url.com") (release "0.3.1") ; Fixes bug (release "0.3.0") ; Adds feature (release "0.2.0") (release "0.1.0") ; Initial version </enscript> ==== Org-mode and Markdown You can specify multiple files to write output to by repeating the {{-o}} flag. Currently, the {{.org}} and {{.md}} extensions are supported to generate Org-mode and Markdown files, respectively. Svnwiki output will always go to stdout unless a file with the {{.svnwiki}} extension is specified. === Full Examples ==== In source See the [[https://code.dieggsy.com/icu/tree/|ICU egg source code]] and [[https://wiki.call-cc.org/eggref/5/icu|documentation]] for a full example of a project using chalk. ==== Separate docs Chalk can also be used on documentation-only files without attached scheme code. For example, here is the chalk-only source for this document [[https://git.sr.ht/~dieggsy/chalk-bin/blob/main/chalk-bin.chalk|chalk-bin.chalk]] === Author Diego A. Mundo === Version History ; 1.0.2 : Fix inline bold/italic for Org/Markdown ; 1.0.1 : Bug fix and revert some incompatible args ; 1.0.0 : Initial release splitting syntax from executable === License BSD Copyright (c) 2020 Diego A. Mundo All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Description of your changes:

I would like to authenticate

Spam control

What do you get when you multiply 8 by 4?