((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/cock-utils" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "cock-utils" (p "Translates in-source documentation from cock into wiki: deprecated for hahn-utils") (toc) (section 3 "Deprecation" (p (tt "Cock-utils") " has been deprecated for " (int-link "hahn-utils") ".")) (section 3 "Introduction" (p (tt "Cock-utils") " is mainly interesting because it provides the " (tt "cock") " program that takes code documented with " (int-link "cock") " and converts it into documentation.") (p (tt "Cock-utils") " is a soft-dependency and shouldn't be included in " (tt "depends") ".")) (section 3 "Invocation" (p (tt "Cock-utils") " is normally invoked from a " (tt ".setup") " file; see " (link "https://wiki.call-cc.org/eggref/4/cock#the-setupfile" "this example") ":") (highlight scheme "(use cock setup-helper-mod)\n(setup-shared-extension-module\n  'landauer\n  (extension-version \"0.0.1\")\n  compile-options:\n  '(-X cock))\n(run-cock -o landauer.wiki landauer.scm landauer-core.scm)") (p "It can also be run from the command line:") (pre " cock -o landauer.wiki landauer.scm landauer-core.scm") (p "See " (tt "cock --help") " for details.")) (section 3 "Documentation" (section 4 (tt "cock-utils") (p (b "[module]") " " (tt "cock-utils")) (p "The cock-parse module is responsible for the heavy lifting: creating docexprs (see below) from documented sources code; the drivers then write docexprs as e.g. wiki, LaTeX.") (ul (li (int-link "#parse-files" "parse-files")) (li (int-link "#tex-write-docexprs" "tex-write-docexprs")) (li (int-link "#wiki-write-docexprs" "wiki-write-docexprs")) (li (int-link "#with-working-directory" "with-working-directory")) (li (int-link "#version<=?" "version<=?")))) (section 4 (tt "current-docexpr") (def (sig (parameter "current-docexpr → #f" (id current-docexpr))) (p "Enables communication with the parsing @-reader") (highlight scheme "(define current-docexpr (make-parameter #f))"))) (section 4 (tt "docexpr") (def (sig (record "docexpr" (id docexpr))) (p "Composite documentation and adherent expression") (dl (dt (tt "doc")) (dd "Documentation for the expression") (dt (tt "expr")) (dd "Expression surrounding the documentation")) (highlight scheme "(define-record-and-printer docexpr doc expr)"))) (section 4 (tt "parse-files") (def (sig (procedure "(parse-files . files) → Resultant docexprs" (id parse-files))) (p "Parse files into docexprs.") (dl (dt (tt "files")) (dd "Cock-documented files to be parsed")) (highlight scheme "(define (parse-files . files)\n  (parameterize\n    ((docexprs (make-stack)))\n    (for-each\n      (lambda (file)\n        (with-input-from-file\n          file\n          (lambda ()\n            (let read-next ((expression (read)))\n              (if (not (eof-object? expression))\n                (begin\n                  (if (current-docexpr)\n                    (docexpr-expr-set! (stack-peek (docexprs)) expression))\n                  (current-docexpr #f)\n                  (read-next (read))))))))\n      files)\n    (docexprs)))"))) (section 4 (tt "with-working-directory") (def (sig (procedure "(with-working-directory directory thunk) → object" (id with-working-directory))) (p "Change to the " (tt "directory") ", execute " (tt "thunk") ", change back; returns the value of executing " (tt "thunk") ".") (dl (dt (tt "directory")) (dd "The directory to switch to") (dt (tt "thunk")) (dd "The thunk to execute")) (highlight scheme "(define (with-working-directory directory thunk)\n  (let ((original-directory (current-directory)))\n    (dynamic-wind\n      (lambda () (current-directory directory))\n      thunk\n      (lambda () (current-directory original-directory)))))"))) (section 4 (tt "write-example") (def (sig (procedure "(write-example data description expressions) → unspecified" (id write-example))) (p "Renders an example, evaluating the expressions; attempts to " (tt "require-extension") " all modules seen so far.") (highlight scheme "(define (write-example data description expressions)\n  (display description)\n  (newline)\n  (let ((env (interaction-environment))\n        (modules (hash-table-ref/default data 'modules '())))\n    (for-each\n      (lambda (module) (eval `(require-extension ,module) env))\n      modules)\n    (for-each\n      (lambda (expression)\n        (fmt #t (columnar \" \" (with-width 78 (pretty expression))))\n        (fmt #t\n             (columnar \"  => \" (with-width 74 (pretty (eval expression env))))\n             \" \"\n             nl))\n      expressions)))"))) (section 4 (tt "wiki-write-docexprs") (def (sig (procedure "(wiki-write-docexprs docexprs) → unspecified" (id wiki-write-docexprs)) (procedure "(wiki-write-docexprs docexprs metafile) → unspecified" (id wiki-write-docexprs)) (procedure "(wiki-write-docexprs docexprs metafile repo) → unspecified" (id wiki-write-docexprs)) (procedure "(wiki-write-docexprs docexprs metafile repo fragment?) → unspecified" (id wiki-write-docexprs))) (p "Write the source-derived docexprs as svnwiki.") (dl (dt (tt "docexprs")) (dd "The parsed docexprs") (dt (tt "metafile")) (dd "The egg's .meta file") (dt (tt "repo")) (dd "The e.g. git-repo") (dt (tt "fragment?")) (dd "Whether to produce a document-fragment as opposed to a whole document (useful for debugging)")) (highlight scheme "(define wiki-write-docexprs\n  (case-lambda\n    ((docexprs) (wiki-write-docexprs docexprs #f))\n    ((docexprs metafile) (wiki-write-docexprs docexprs #f #f))\n    ((docexprs metafile repo) (wiki-write-docexprs docexprs #f #f #f))\n    ((docexprs metafile repo fragment?)\n     (let* ((document (make-document (make-hash-table) (make-stack)))\n            (parsed-docexprs (wiki-parse-docexprs document docexprs)))\n       (let ((data (hash-table-merge\n                     (hash-table-merge\n                       (document-data document)\n                       (parse-metafile metafile))\n                     (repo-metadata repo))))\n         (let ((author (hash-table-ref/default data 'author (default-author)))\n               (username\n                 (or (hash-table-ref/default data 'username #f)\n                     (hash-table-ref/default data 'user #f)\n                     (default-user)))\n               (email (hash-table-ref/default data 'email (default-email)))\n               (repository\n                 (or (hash-table-ref/default data 'repository #f)\n                     (hash-table-ref/default data 'repo #f)))\n               (title (let ((title (hash-table-ref/default data 'title #f))\n                            (egg (hash-table-ref/default data 'egg #f)))\n                        (or title egg (default-title))))\n               (description\n                 (or (hash-table-ref/default data 'description #f)\n                     (hash-table-ref/default data 'synopsis #f)\n                     (default-synopsis)))\n               (dependencies\n                 (or (hash-table-ref/default data 'depends #f)\n                     (hash-table-ref/default data 'needs #f)\n                     '()))\n               (license (hash-table-ref/default data 'license #f))\n               (versions (hash-table-ref/default data 'versions '())))\n           (unless fragment? (display (wiki-preamble title description)))\n           (stack-for-each parsed-docexprs (lambda (docexpr) (docexpr)))\n           (unless\n             fragment?\n             (display\n               (wiki-postamble\n                 author\n                 username\n                 license\n                 repository\n                 dependencies\n                 versions)))))))))"))) (section 4 (tt "tex-write-docexprs") (def (sig (procedure "(tex-write-docexprs docexprs) → unspecified" (id tex-write-docexprs)) (procedure "(tex-write-docexprs docexprs metafile) → unspecified" (id tex-write-docexprs)) (procedure "(tex-write-docexprs docexprs metafile repo) → unspecified" (id tex-write-docexprs))) (p "Write the source-derived docexprs as LaTeX.") (dl (dt (tt "docexprs")) (dd "The parsed docexprs")) (highlight scheme "(define tex-write-docexprs\n  (case-lambda\n    ((docexprs) (tex-write-docexprs docexprs #f))\n    ((docexprs metafile) (tex-write-docexprs docexprs #f #f))\n    ((docexprs metafile repo)\n     (let* ((document (make-document (make-hash-table) (make-stack)))\n            (parsed-docexprs (tex-parse-docexprs document docexprs)))\n       (let ((data (document-data document)))\n         (write-template\n           tex-preamble\n           `((author unquote (hash-table-ref/default data 'author \"Anonymous\"))\n             (email unquote\n                    (hash-table-ref/default\n                      data\n                      'email\n                      \"anonymous@example.org\"))\n             (title unquote\n                    (hash-table-ref/default data 'title \"Documentation\")))))\n       (stack-for-each parsed-docexprs (lambda (docexpr) (docexpr)))\n       (display tex-footer)))))")))) (section 3 "About this egg" (section 4 "Author" (p (int-link "/users/(anonymous)" "Peter Danenberg"))) (section 4 "Repository" (p (link "https://github.com/klutometis/cock-utils"))) (section 4 "License" (p "BSD")) (section 4 "Dependencies" (ul (li (int-link "alist-lib")) (li (int-link "args")) (li (int-link "cock")) (li (int-link "debug")) (li (int-link "define-record-and-printer")) (li (int-link "fmt")) (li (int-link "git")) (li (int-link "matchable")) (li (int-link "miscmacros")) (li (int-link "shell")) (li (int-link "srfi-95")) (li (int-link "stack")) (li (int-link "usage")))) (section 4 "Versions" (dl (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.1.1" "0.1.1")) (dd "Add dependencies.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.1.2" "0.1.2")) (dd "Remove circular dependency on cock; use string->symbol to evade reader.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.2" "0.2")) (dd "@internal, @example, @noop, &c.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.2.1" "0.2.1")) (dd "Do string->symbol on @egg.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.2.2" "0.2.2")) (dd "Width-specifiers, noop.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.2.3" "0.2.3")) (dd "@example-no-eval") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.2.4" "0.2.4")) (dd "Add @no-source.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.3" "0.3")) (dd "Read egg- and repo-metadata.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.3.1" "0.3.1")) (dd "Fix the case of #f versions.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4" "0.4")) (dd "Setup-helper-like thing: run-cock") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.1" "0.4.1")) (dd "Add version<=?.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.2" "0.4.2")) (dd "Move to setup-helper-cock.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.3" "0.4.3")) (dd "Fix the version-sorting mechanism.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.4" "0.4.4")) (dd "Add links to releases.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.5" "0.4.5")) (dd "Actually fix the versioning order.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.6" "0.4.6")) (dd "Use setup-helper-mod.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.7" "0.4.7")) (dd "Remove debug.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.4.8" "0.4.8")) (dd "Legitimately tag a release.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.5" "0.5")) (dd "Fix evaluation of examples; make testable.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.5.1" "0.5.1")) (dd "Document; allow multiple expressions in source.") (dt (link "https://github.com/klutometis/cock-utils/releases/tag/0.5.2" "0.5.2")) (dd "Deprecate this for hahn-utils."))) (section 4 "Colophon" (p "Documented by " (int-link "/egg/cock" "cock") ".")))))