From ebdd54ec7a786657968bfdb0d083e87100bb8a3e Mon Sep 17 00:00:00 2001 From: Arun Isaac Date: Fri, 7 Oct 2022 17:41:11 +0530 Subject: tissue: Markup docstrings in texinfo syntax. * tissue/document.scm (slot-set): Markup docstring in texinfo syntax. * tissue/file-document.scm (read-gemtext-document): Markup docstring in texinfo syntax. * tissue/git.scm (git-tracked-files): Markup docstring in texinfo syntax. * tissue/issue.scm (read-gemtext-issue): Markup docstring in texinfo syntax. * tissue/tissue.scm (gemtext-files-in-directory): Markup docstring in texinfo syntax. * tissue/web/static.scm (exporter, copier, gemtext-exporter, skribe-exporter): Markup docstrings in texinfo syntax. --- tissue/document.scm | 5 +++-- tissue/file-document.scm | 3 ++- tissue/git.scm | 6 +++--- tissue/issue.scm | 3 ++- tissue/tissue.scm | 12 ++++++++---- tissue/web/static.scm | 14 ++++++++------ 6 files changed, 26 insertions(+), 17 deletions(-) diff --git a/tissue/document.scm b/tissue/document.scm index 48d82cc..65a68b6 100644 --- a/tissue/document.scm +++ b/tissue/document.scm @@ -47,8 +47,9 @@ document->sxml)) (define (slot-set object slot-name value) - "Set SLOT-NAME in OBJECT to VALUE. This is a purely functional setter -that operates on a copy of OBJECT. It does not mutate OBJECT." + "Set @var{slot-name} in @var{object} to @var{value}. This is a purely +functional setter that operates on a copy of @var{object}. It does not +mutate @var{object}." (let ((clone (shallow-clone object))) (slot-set! clone slot-name value) clone)) diff --git a/tissue/file-document.scm b/tissue/file-document.scm index b910131..847fb42 100644 --- a/tissue/file-document.scm +++ b/tissue/file-document.scm @@ -147,7 +147,8 @@ a list of search results." (cut file-modification-table (current-git-repository)))) (define (read-gemtext-document file) - "Read gemtext document from FILE. Return a object." + "Read gemtext document from @var{file} and return a +@code{} object." (make #:title (or (call-with-file-in-git (current-git-repository) file (lambda (port) diff --git a/tissue/git.scm b/tissue/git.scm index 764fba2..334ffbc 100644 --- a/tissue/git.scm +++ b/tissue/git.scm @@ -122,9 +122,9 @@ directory." path))) (define* (git-tracked-files #:optional (repository (current-git-repository))) - "Return a list of all files and directories tracked in REPOSITORY. The -returned paths are relative to the top-level directory of REPOSITORY -and do not have a leading slash." + "Return a list of all files and directories tracked in +@var{repository}. The returned paths are relative to the top-level +directory of @var{repository} and do not have a leading slash." (tree-list (head-tree repository))) (define (call-with-file-in-git repository path proc) diff --git a/tissue/issue.scm b/tissue/issue.scm index 469b033..869b0ed 100644 --- a/tissue/issue.scm +++ b/tissue/issue.scm @@ -350,7 +350,8 @@ gemtext file." result)) (define (read-gemtext-issue file) - "Read issue from gemtext FILE. Return an object." + "Read issue from gemtext @var{file} and return an @code{} +object." (let* ((file-document (read-gemtext-document file)) (file-details (call-with-file-in-git (current-git-repository) file file-details)) diff --git a/tissue/tissue.scm b/tissue/tissue.scm index e7637b4..61ef4b8 100644 --- a/tissue/tissue.scm +++ b/tissue/tissue.scm @@ -48,10 +48,14 @@ (compose force delayed-tissue-configuration-web-files)) (define* (gemtext-files-in-directory #:optional directory) - "Return a list of all gemtext files in DIRECTORY tracked in the -current git repository. If DIRECTORY is #f, return the list of all -gemtext files tracked in the current git repository regardless of -which directory they are in." + "Return a list of all gemtext files in @var{directory} tracked in the +current git repository. The returned paths are relative to the +top-level directory of the current repository and do not have a +leading slash. + +If @var{directory} is unspecified, return the list of all gemtext +files tracked in the current git repository regardless of which +directory they are in." (filter (lambda (filename) (and (or (not directory) (string-prefix? directory filename)) diff --git a/tissue/web/static.scm b/tissue/web/static.scm index 69a9d90..fc3a211 100644 --- a/tissue/web/static.scm +++ b/tissue/web/static.scm @@ -61,15 +61,15 @@ NEW-EXTENSION." new-extension)) (define (exporter file proc) - "Return a writer function that exports FILE using PROC. PROC is -passed two arguments---the input port to read from and the output port -to write to." + "Return a writer function that exports @var{file} using +@var{proc}. @var{proc} is passed two arguments---the input port to +read from and the output port to write to." (lambda (out) (call-with-file-in-git (current-git-repository) file (cut proc <> out)))) (define (copier file) - "Return a writer function that copies FILE." + "Return a writer function that copies @var{file}." (exporter file (lambda (in out) (port-transduce (tmap (cut put-bytevector out <>)) @@ -84,7 +84,8 @@ to write to." #:join-lines? #t)) (define* (gemtext-exporter file #:optional (reader (gemtext-reader))) - "Return a writer function that exports FILE, a gemtext file." + "Return a writer function that reads gemtext @var{file} using +@var{reader} and exports it." (exporter file (lambda (in out) (with-output-to-port out @@ -93,7 +94,8 @@ to write to." (find-engine 'html)))))) (define* (skribe-exporter file #:optional (reader (make-reader 'skribe))) - "Return a writer function that exports FILE, a skribe file." + "Return a writer function that reads skribe @var{file} using +@var{reader} and exports it." (exporter file (lambda (in out) (with-output-to-port out -- cgit v1.2.3