source: project/eformat/doc.scm @ 8252

Last change on this file since 8252 was 8252, checked in by elf, 12 years ago

path fix

File size: 20.4 KB
Line 
1;;;; egg:       eformat
2;;;; file:      doc.scm
3;;;; author:    elf <elf@ephemeral.net>
4;;;; date:      24 Jan 2008
5;;;; licence:   BSD (see LICENCE)
6;;;; dialect:   r5rs
7;;;; requires:  chicken build tools, eggdoc
8;;;; version:   3.0
9;;;; purpose:   eggdoc-formatted documentation for eformat
10;;;;
11;;;; history:   3.0  First public release
12;;;;            2.x  Added many options
13;;;;            1.0  Initial release
14
15
16
17
18(use utils)     ; utility procedures
19(use eggdoc)    ; egg documentation facility
20
21
22
23;; (table-conc DATA...)
24;; helper macro for constructing data
25;(define-macro (table-conc . data)
26;    (cond ((null? data)
27;              `"")
28;          ((list? (car data))
29;              `(conc "<" ',(caar data) ">"
30;                     (table-conc ,@(cdar data))
31;                     "</" ',(caar data) ">"
32;                     (table-conc ,@(cdr data))))
33;          (else
34;              `(conc ,(car data) (table-conc ,@(cdr data))))))
35
36;; (table-make FORMAT-WRAPPERS HEADERS ROWS...)
37;; helper macro for constructing tables
38(define-macro (table-make fmtw hdrs . rows)
39    `'(
40        table
41            (tr ,@(map (lambda (h) `(th ,h)) hdrs))
42            ,@(map
43                (lambda (r)
44                    `(tr
45                        ,@(map
46                            (lambda (f d)
47                                `(td (,f ,d)))
48                            fmtw r)))
49                rows)))
50
51(define doc
52    `((eggdoc:begin
53        (name         "eformat")
54        (description  "extended formatting procedures")
55        (author       (url "mailto:elf@ephemeral.net" "elf"))
56
57        (history
58            (version "3.0" "(eformat)   First public release")
59            (version "2.1" "(eformat)   New float (D), pad-char (C) directives")
60            (version "2.0" "(eformat)   General text wrapping functionality")
61            (version "1.5" "(eformat)   New subformat (F) directive")
62            (version "1.4" "(eformat)   New list subformat (T) directive")
63            (version "1.3" "(eformat)   New integer radix (BOXH) directives")
64            (version "1.2" "(eformat)   New list (LW) directives")
65            (version "1.1" "(eformat)   New padding (P) directive")
66            (version "1.0" "(eformat)   Initial version"))
67
68        (requires
69            (url "numbers.html" "numbers")
70            (url "srfi-60.html" "srfi-60"))
71
72        (usage)
73        (download "eformat.egg")
74
75
76        (documentation
77
78            (p "This extension provides extended formatting procedures.  It "
79               "is intended as a high-speed, simpler replacement for "
80               "traditional text formatting procedures while keeping much "
81               "of the same feel and functionality.  While not every directive "
82               "from Common Lisp's " (code "(format)") " is implemented, those "
83               "directives that are should cover most of the use cases.  "
84               "In addition, there are several new directives to simplify "
85               "frequently occurring patterns.  Any suggestions for "
86               "additional functionality are welcomed.")
87            (p "The " (code "eformat") " package has two major components: "
88               (code "eformat") " and " (code "wrap-text") ".  "
89               (code "eformat") " outputs formatted text according to a "
90               "format-string and a list of arguments.  " (code "wrap-text") 
91               " is a flexible means of wrapping and indenting arbitrary "
92               "blocks of text.  Several useful auxiliary procedures have "
93               "also been exported.  All procedures should be thread-safe.")
94           
95            (subsection "Core Procedures"
96                (p "These procedures form the core of the " (code "eformat")
97                   " functionality.  See [Output Directives] for a list "
98                   "and explanation of all valid " (code "eformat") 
99                   " format-string directives.")
100                (group
101                    (procedure
102                        "(eformat DESTINATION FMTSTRING [ARG ...])"
103                        (p "Creates an output string from the "
104                           (code "FMTSTRING") ", substituting " (code "ARG")
105                           "s for the corresponding format directives.  The "
106                           "number of " (code "ARG") " values must be "
107                           "equivalent to the number required by "
108                           (code "FMTSTRING") " or an error is signalled.  "
109                           "See [Output Directives] for an explanation of all "
110                           "valid output directives and the number of "
111                           "arguments each requires.  " (code "FMTSTRING")
112                           " must be a non-null string or an error is "
113                           "signalled.")
114                        (p (code "DESTINATION") " determines how the final "
115                           "generated string (<ostr>) is handled according "
116                           "to the following table:")
117                        ,(table-make
118                            (code code p p)
119                            ("DESTINATION" "Handler" "Return Val" "Description")
120                            ("#f" "<ostr>"
121                             "string"
122                             "returns the generated string")
123                            ("#t" "(display <ostr>)"
124                             "unspecified"
125                             "displays <ostr> to (current-output-port)")
126                            ("2" "(display <ostr> (current-error-port))"
127                             "unspecified"
128                             "displays <ostr> to (current-error-port)")
129                            ("<output-port>" "(display <ostr> <output-port>)"
130                             "unspecified"
131                             "displays <ostr> to the given output-port")
132                            ("<anything else>" "error"
133                             "error"
134                             "signals an error")))
135                    (procedure
136                        "(wrap-text STRING WRAP-COLUMN [INDENT-SPACES 0] [PRESERVE-STRUCTURE #t])"
137                        (p "Wraps (i.e., adds implicit newlines to) "
138                           (code "STRING") " at the whitespace character "
139                           "nearest to (equivalent or less than) " 
140                           (code "WRAP-COLUMN") ".  Implicit newlines cause "
141                           "the following line to be indented by "
142                           (code "INDENT-SPACES") ".  An error is signalled if "
143                           (code "INDENT-SPACES") " is not strictly less than "
144                           (code "WRAP-COLUMN") ".")
145                        (p "Explicit newlines are any newline (or "
146                           "newline-equivalent) characters in the initial "
147                           (code "STRING") ".  See the table below for "
148                           "descriptions of all newline-equiv whitespace.  "
149                           "If the optional " (code "PRESERVE-STRUCTURE")
150                           " argument is given and " (code "#f") ", all "
151                           "whitespace chars are converted to spaces before "
152                           "processing.  Excess whitespace is always removed "
153                           "from the ends of lines.  After implicit newlines, "
154                           "whitespace is removed from the beginning of "
155                           "the following line as well (before adding "
156                           (code "INDENT-SPACES") " spaces).  All whitespace "
157                           "characters are correctly handled, including "
158                           "vertical tabs and form-feeds."))))
159
160            (subsection "Output Directives"
161                (p "All directives start with a " (code "~") " (tilde).  All "
162                   "text besides directives is added to the output-string via " 
163                   (code "display") ".  It is an error for a tilde to appear "
164                   "in the format string except as the start of a directive.")
165                (p "All modifiers are optional except where otherwise "
166                   "indicated.  All directives are of the following form "
167                   "(without whitespace or brackets) and have the given "
168                   "default semantics:")
169                (p (code "~ [ - ] [ @ ] [ 0 ] [ & ] [ M ] [ , X ] [ . C ] D"))
170                ,(table-make
171                    (code p code code code code p)
172                    ("Symbol" "Name" "Input Value" "Default Value"
173                     "Requires" "Forbids" "Description")
174                    ("~ (tilde)" "start-indicator" "~" "NONE" "NONE" "NONE"
175                     ("Indicates the beginning of a format directive."))
176                    ("- (hyphen)" "right-justify-modifier" "-" "NONE" "M" "@"
177                     ("Aligns the directive's output with the right field "
178                      "margin (default is left).  Requires the "
179                      (code "min-length-modifier") " to be given."))
180                    ("@ (at-sign)" "center-justify-modifier" "@" "NONE" "M" "-"
181                     ("Aligns the directive's output in the center of the "
182                      "field (default is left).  Requires the "
183                      (code "min-length-modifier") " to be given."))
184                    ("0 (zero)" "zero-pad-modifier" "0" "NONE" "M" "&"
185                     ("Pads with zeros (default is spaces).  Requires the "
186                      (code "min-length-modifier") " to be given."))
187                    ("& (ampersand)" "char-pad-modifier" "&" "NONE" "M" "0"
188                     ("Pads with a character given on the command line "
189                      "(default is spaces).  Requires the "
190                      (code "min-length-modifier") " to be given."))
191                    ("M" "min-length-modifier" "exact int > 0 OR *" "NONE"
192                     "NONE" "NONE"
193                     ("Minimum field length.  Will pad with the pad character "
194                      "(above, default is space) if the field is smaller than "
195                      "the size.  If given as " (code "*") ", length is read "
196                      "from the argument list."))
197                    ("X" "max-length-modifier" "exact int > 0 OR *" "NONE"
198                     "NONE" "NONE"
199                     ("Maximum field length.  Trims a field to a maximum "
200                      "length of the given argument.  If given as " (code "*")
201                      ", length is read from the argument list.  If "
202                      (code "min-length-modifier") " is also given and larger "
203                      "than " (code "max-length-modifier") ", "
204                      (code "max-length-modifier") " takes precedence."))
205                    ("C" "count-repeat-modifier" "exact int > 0 OR *" "1"
206                     "NONE" "NONE"
207                     ("Repetition count modifier.  After applying all other "
208                      "modifiers, displays final string count times.  If given "
209                      "as " (code "*") ", count is read from the argument "
210                      "list."))
211                    ("D" "format-directive" "(see below)" "NONE" "NONE" "NONE"
212                     ("Format directive.  REQUIRED in all cases.  The table "
213                      "below gives all format directives and their meanings.")))
214                (p "Each valid output directive is given below:")
215                ,(table-make
216                    (code p code code code code p)
217                    ("Directive" "Mnemonic" "Requires" "Forbids" "Ignores"
218                     "Args Read" "Action")
219                    ("A or a" "display" "NONE" "NONE" "NONE" "1" 
220                     ("Adds the next argument to the output string via "
221                      (code "display") "."))
222                    ("S or s" "write" "NONE" "NONE" "NONE" "1"
223                     ("Adds the next argument to the output string via "
224                      (code "write") "."))
225                    ("P or p" "pad" "M" "XC" "-@" "0"
226                     ("Adds " (code "M") " pad-characters (space by default, "
227                      "or as given by " (code "0") " or " (code "&") ") to the "
228                      "output string via " (code "display") "."))
229                    ("L or l" "list display" "NONE" "NONE" "NONE" "2"
230                     ("First arg must be a list/pair/vector (LPV).  Second arg "
231                      "is any object to be used as a separator (SEP).  Each "
232                      "element of LPV is added to the output string via "
233                      (code "display") ", with SEP added between elements."))
234                    ("W or w" "list write" "NONE" "NONE" "NONE" "2"
235                     ("Equivalent to " (code "L or l") " above, except that "
236                      "elements are added via " (code "write") " instead of "
237                      (code "display") ".  SEP is still added via "
238                      (code "display") "."))
239                    ("B or b" "binary" "NONE" "NONE" "NONE" "1"
240                     ("Adds the next argument (an exact integer) to the "
241                      "output string as its binary representation.  Negative "
242                      "numbers are translated to their twos-complement form.  "
243                      "The number is padded to a multiple of 8 characters."))
244                    ("O or o" "octal" "NONE" "NONE" "NONE" "1"
245                     ("Adds the next argument (an exact integer) to the "
246                      "output string as its octal representation.  Negative "
247                      "numbers are translated to their twos-complement form.  "
248                      "The number is padded to a multiple of 3 characters.  "
249                      "If given as " (code "O") ", a zero or seven (depending "
250                      "on sign) is always prepended to the number."))
251                    ("X or x" "hex" "NONE" "NONE" "NONE" "1"
252                     ("Adds the next argument (an exact integer) to the "
253                      "output string as its hexadecimal representation.  "
254                      "Negative numbers are translated to their "
255                      "twos-complement form.  The number is padded to a "
256                      "multiple of 2 characters.  If given as " (code "X") 
257                      ", the output will be in upper case."))
258                    ("H or h" "hex-prefix" "NONE" "NONE" "NONE" "1"
259                     ("Equivalent to " (code "X or x") " above, except that "
260                      "a " (code "0x") " is prepended before case checking."))
261                    ("D or d" "decimal" "NONE" "NONE" "NONE" "1"
262                     ("Adds the next argument (an exact integer) to the "
263                      "output string as its decimal representation."))
264                    ("I or i" "unsigned decimal" "NONE" "NONE" "NONE" "1"
265                     ("Adds the next argument (an exact integer) to the "
266                      "output string as its decimal representation.  Negative "
267                      "numbers are translated to their twos-complement form."))
268                    ("G or g" "float" "MXC" "NONE" "NONE" "1"
269                     ("Adds the next argument (a real number) to the output "
270                      "string.  The " (code "M") " modifier determines the "
271                      "minimum field length of the integral digits.  The "
272                      (code "X") " modifier determines the maximum field "
273                      "length of the integral digits.  The " (code "C") 
274                      " modifier determines the minimum number of fractional "
275                      "digits."))
276                    ("F or f" "subformat" "C" "NONE" "NONE" "1+C"
277                     ("Recursive format call.  First argument must be a "
278                      "valid format-string.  The " (code "C") " modifier "
279                      "determines the number of extra arguments to take from "
280                      "the list for the subformat, and may be zero."))
281                    ("T or t" "list subformat" "C" "NONE" "NONE" "3"
282                     ("Recursive list/vector/pair format call.  First argument "
283                      "must be a list/vector/pair.  Second argument must be "
284                      "any object to act as separator.  Third argument must be "
285                      "a valid format-string.  If the element(s) of LVP are "
286                      "LVPs, then " (code "eformat") " is applied to the "
287                      "format-string arg with the sub-LVP elements as args.  "
288                      "Otherwise, " (code "eformat") " is applied to the "
289                      "format-string arg with the LVP arg as a single "
290                      "argument."))
291                    ("R or r" "text wrap" "MXC" "NONE" "NONE" "0"
292                     ("Wraps text.  This can only occur once, and only as "
293                      "the first element in the format-string.  (However, "
294                      "as subformat directives are separate calls, it may "
295                      "occur in subformat strings as well.)  The modifiers are "
296                      "mapped to the arguments for " (code "wrap-text") 
297                      ", above, in the same order."))
298                    ("~" "tilde" "NONE" "-@0&MXC" "NONE" "0"
299                     ("Adds a literal tilde to the output string."))))
300
301            (subsection "Whitespace Sequences"
302                        (p "The following table describes the whitespace "
303                           "characters/sequences recognised and how they "
304                           "are handled.  The " (em "Column") " heading "
305                           "is the output column value after the whitespace "
306                           "is processed.  All newline-equivalent sequences"
307                           "generate explicit newlines (" (code "#\\newline")
308                           ") rather than the original char(s).")
309                        ,(table-make
310                            (code p code p)
311                            ("Char(s)" "newline-equiv" "Column" "Description")
312                            ("#\\space" "N"
313                             "(+ column 1)"
314                             "adds a single space")
315                            ("#\\htab" "N"
316                             "(+ column (- 8 (modulo column 8)))"
317                             "adds spaces until an 8-space mark")
318                            ("#\\newline" "Y"
319                             "0"
320                             "adds a single newline")
321                            ("#\\return" "Y"
322                             "0"
323                             "adds a single newline")
324                            ("#\\return#\\newline" "Y"
325                             "0"
326                             "special case: adds only one newline")
327                            ("#\\formfeed" "Y"
328                             "column"
329                             "adds a newline, then pads to <column> spaces")
330                            ("#\\vtab" "Y"
331                             "column"
332                             "adds a newline, then pads to <column> spaces")))
333
334            (subsection "Utility Procedures"
335                (p "These are some (hopefully useful) utility procedures built "
336                   "from the " (code "eformat") " functionality.")
337                (group
338                    (procedure
339                        "(char->num DIGIT [(ORIG 0) [(OP +)]])"
340                        (p "Applies " (code "OP") " to the numeric "
341                           "representation of DIGIT (a char in the range #\\0 "
342                           "to #\\9) and (10 * " (code "ORIG") ").  The "
343                           "default behaviour (if " (code "OP") " is not "
344                           "given) allows a sequence of character digits to "
345                           "be translated into their numeric equivalent, "
346                           "respecting order of magnitude."))
347                    (procedure
348                        "(errformat CALLING-PROC RETURN-ARGS FMTSTR [ARG ...])"
349                        (p "Creates nicely-formatted error messages and "
350                           "signals an error.  Equivalent to ")
351                        (code "(apply error (string-append \"(\" CALLING-PROC "
352                              "\")  \" (eformat #f FMTSTR [ARG ...])) "
353                              "RETURN-ARGS)")
354                        (p "except that " (code "CALLING-PROC") " may be an "
355                           "object other than a string."))))
356
357            (subsection "Bugs"
358                (p "None known"))
359
360            (subsection "Licence"
361                (pre ,(read-all "eformat/LICENCE")))
362        ))))
363
364
365(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.