add HTML docs and some guidance on scripts
svn: r8323
This commit is contained in:
Matthew Flatt
parent
83568dd0de
commit
19b142e67d
835
collects/html/html.scrbl
Normal file
835
collects/html/html.scrbl
Normal file
|
|
@ -0,0 +1,835 @@
|
|||
#lang scribble/doc
|
||||
@(require scribble/manual
|
||||
scribble/eval
|
||||
(for-label html/html)
|
||||
(for-label xml/xml))
|
||||
|
||||
@title{@bold{HTML}: Parsing Library}
|
||||
|
||||
|
||||
@defmodule[html/html]{The @schememodname[html/html] library provides
|
||||
functions to read html documents and structures to represent them.}
|
||||
|
||||
|
||||
@deftogether[(
|
||||
@defproc[(read-xhtml [port input-port?])
|
||||
html?]{}
|
||||
|
||||
@defproc[(read-html [port input-port?])
|
||||
html?]{}
|
||||
)]{
|
||||
|
||||
Reads (X)HTML from a port, producing an @scheme[html] instance.}
|
||||
|
||||
|
||||
@defproc[(read-html-as-xml [port input-port?])
|
||||
(listof content)]{
|
||||
|
||||
Reads HTML from a port, producing an xexpr compatible with the
|
||||
@schememodname[xml/xml] library (which defines @scheme[content]).}
|
||||
|
||||
|
||||
|
||||
@section{Example}
|
||||
@def+int[
|
||||
(module html-example scheme
|
||||
|
||||
(code:comment #, @t{Some of the symbols in html/html and xml/xml conflict with})
|
||||
(code:comment #, @t{each other and with scheme/base language, so we prefix})
|
||||
(code:comment #, @t{to avoid namespace conflict.})
|
||||
(require (prefix-in h: html/html)
|
||||
(prefix-in x: xml/xml))
|
||||
|
||||
(define an-html
|
||||
(h:read-xhtml
|
||||
(open-input-string
|
||||
(string-append
|
||||
"<html><head><title>My title</title></head><body>"
|
||||
"<p>Hello world</p><p><b>Testing</b>!</p>"
|
||||
"</body></html>"))))
|
||||
|
||||
(code:comment #, @t{extract-pcdata: html-content -> (listof string)})
|
||||
(code:comment #, @t{Pulls out the pcdata strings from some-content.})
|
||||
(define (extract-pcdata some-content)
|
||||
(cond [(x:pcdata? some-content)
|
||||
(list (x:pcdata-string some-content))]
|
||||
[(x:entity? some-content)
|
||||
(list)]
|
||||
[else
|
||||
(extract-pcdata-from-element some-content)]))
|
||||
|
||||
(code:comment #, @t{extract-pcdata-from-element: html-element -> (listof string)})
|
||||
(code:comment #, @t{Pulls out the pcdata strings from an-html-element.})
|
||||
(define (extract-pcdata-from-element an-html-element)
|
||||
(match an-html-element
|
||||
[(struct h:html-full (content))
|
||||
(apply append (map extract-pcdata content))]
|
||||
|
||||
[(struct h:html-element (attributes))
|
||||
'()]))
|
||||
|
||||
(printf "~s~n" (extract-pcdata an-html)))
|
||||
(require 'html-example)
|
||||
]
|
||||
|
||||
|
||||
|
||||
@section{HTML Structures}
|
||||
|
||||
@scheme[pcdata], @scheme[entity], and @scheme[attribute] are defined
|
||||
in the @schememodname[xml/xml] documentation.
|
||||
|
||||
A @scheme[html-content] is either
|
||||
@itemize[
|
||||
@item[@scheme[html-element]]
|
||||
@item[@scheme[pcdata]]
|
||||
@item[@scheme[entity]]]
|
||||
|
||||
|
||||
@defstruct[html-element ([attributes (listof attribute)])]{
|
||||
Any of the structures below inherits from @scheme[html-element].}
|
||||
|
||||
@defstruct[(html-full struct:html-element) ([content (listof html-content)])]{
|
||||
Any html tag that may include content also inherits from
|
||||
@scheme[html-full] without adding any additional fields.}
|
||||
|
||||
|
||||
|
||||
@defstruct[(html html-full) ()]{
|
||||
A @scheme[html] is
|
||||
@scheme[(make-html (listof attribute) (listof Contents-of-html))]
|
||||
}
|
||||
|
||||
A @scheme[Contents-of-html] is either
|
||||
@itemize{
|
||||
@item{@scheme[body]}
|
||||
@item{@scheme[head]}
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(div html-full)()]{
|
||||
A @scheme[div] is
|
||||
@scheme[(make-div (listof attribute) (listof G2))]}
|
||||
|
||||
|
||||
@defstruct[(center html-full)()]{
|
||||
A @scheme[center] is
|
||||
@scheme[(make-center (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(blockquote html-full) ()]{
|
||||
A @scheme[blockquote] is
|
||||
@scheme[(make-blockquote (listof attribute) G2)]
|
||||
}
|
||||
|
||||
@defstruct[(ins html-full) ()]{
|
||||
An Ins is
|
||||
@scheme[(make-ins (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(del html-full) ()]{
|
||||
A @scheme[del] is
|
||||
@scheme[(make-del (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(dd html-full) ()]{
|
||||
A @scheme[dd] is
|
||||
@scheme[(make-dd (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(li html-full) ()]{
|
||||
A @scheme[li] is
|
||||
@scheme[(make-li (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(th html-full) ()]{
|
||||
A @scheme[th] is
|
||||
@scheme[(make-th (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(td html-full) ()]{
|
||||
A @scheme[td] is
|
||||
@scheme[(make-td (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(iframe html-full) ()]{
|
||||
An @scheme[iframe] is
|
||||
@scheme[(make-iframe (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
@defstruct[(noframes html-full) ()]{
|
||||
A @scheme[noframes] is
|
||||
@scheme[(make-noframes (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(noscript html-full) ()]{
|
||||
A @scheme[noscript] is
|
||||
@scheme[(make-noscript (listof attribute) (listof G2))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(style html-full) ()]{
|
||||
A @scheme[style] is
|
||||
@scheme[(make-style (listof attribute) (listof pcdata))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(script html-full) ()]{
|
||||
A @scheme[script] is
|
||||
@scheme[(make-script (listof attribute) (listof pcdata))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(basefont html-element) ()]{
|
||||
A @scheme[basefont] is
|
||||
@scheme[(make-basefont (listof attribute))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(br html-element) ()]{
|
||||
A @scheme[br] is
|
||||
@scheme[(make-br (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(area html-element) ()]{
|
||||
An @scheme[area] is
|
||||
@scheme[(make-area (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(link html-element) ()]{
|
||||
A @scheme[link] is
|
||||
@scheme[(make-link (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(img html-element) ()]{
|
||||
An @scheme[img] is
|
||||
@scheme[(make-img (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(param html-element) ()]{
|
||||
A @scheme[param] is
|
||||
@scheme[(make-param (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(hr html-element) ()]{
|
||||
A @scheme[hr] is
|
||||
@scheme[(make-hr (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(input html-element) ()]{
|
||||
An @scheme[input] is
|
||||
@scheme[(make-input (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(col html-element) ()]{
|
||||
A @scheme[col] is
|
||||
@scheme[(make-col (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(isindex html-element) ()]{
|
||||
An @scheme[isindex] is
|
||||
@scheme[(make-isindex (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(base html-element) ()]{
|
||||
A @scheme[base] is
|
||||
@scheme[(make-base (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(meta html-element) ()]{
|
||||
A @scheme[meta] is
|
||||
@scheme[(make-meta (listof attribute))]
|
||||
}
|
||||
|
||||
@defstruct[(option html-full) ()]{
|
||||
An @scheme[option] is
|
||||
@scheme[(make-option (listof attribute) (listof pcdata))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(textarea html-full) ()]{
|
||||
A @scheme[textarea] is
|
||||
@scheme[(make-textarea (listof attribute) (listof pcdata))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(title html-full) ()]{
|
||||
A @scheme[title] is
|
||||
@scheme[(make-title (listof attribute) (listof pcdata))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(head html-full) ()]{
|
||||
A @scheme[head] is
|
||||
@scheme[(make-head (listof attribute) (listof Contents-of-head))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-head] is either
|
||||
@itemize[
|
||||
@item[@scheme[base]]
|
||||
@item[@scheme[isindex]]
|
||||
@item[@scheme[link]]
|
||||
@item[@scheme[meta]]
|
||||
@item[@scheme[object]]
|
||||
@item[@scheme[script]]
|
||||
@item[@scheme[style]]
|
||||
@item[@scheme[title]]
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(tr html-full) ()]{
|
||||
A @scheme[tr] is
|
||||
@scheme[(make-tr (listof attribute) (listof Contents-of-tr))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-tr] is either
|
||||
@itemize[
|
||||
@item[@scheme[td]]
|
||||
@item[@scheme[th]]
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(colgroup html-full) ()]{
|
||||
A @scheme[colgroup] is
|
||||
@scheme[(make-colgroup (listof attribute) (listof col))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(thead html-full) ()]{
|
||||
A @scheme[thead] is
|
||||
@scheme[(make-thead (listof attribute) (listof tr))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(tfoot html-full) ()]{
|
||||
A @scheme[tfoot] is
|
||||
@scheme[(make-tfoot (listof attribute) (listof tr))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(tbody html-full) ()]{
|
||||
A @scheme[tbody] is
|
||||
@scheme[(make-tbody (listof attribute) (listof tr))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(tt html-full) ()]{
|
||||
A @scheme[tt] is
|
||||
@scheme[(make-tt (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(i html-full) ()]{
|
||||
An @scheme[i] is
|
||||
@scheme[(make-i (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(b html-full) ()]{
|
||||
A @scheme[b] is
|
||||
@scheme[(make-b (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(u html-full) ()]{
|
||||
An @scheme[u] is
|
||||
@scheme[(make-u (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(s html-full) ()]{
|
||||
A @scheme[s] is
|
||||
@scheme[(make-s (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(strike html-full) ()]{
|
||||
A @scheme[strike] is
|
||||
@scheme[(make-strike (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(big html-full) ()]{
|
||||
A @scheme[big] is
|
||||
@scheme[(make-big (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(small html-full) ()]{
|
||||
A @scheme[small] is
|
||||
@scheme[(make-small (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(em html-full) ()]{
|
||||
An @scheme[em] is
|
||||
@scheme[(make-em (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(strong html-full) ()]{
|
||||
A @scheme[strong] is
|
||||
@scheme[(make-strong (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(dfn html-full) ()]{
|
||||
A @scheme[dfn] is
|
||||
@scheme[(make-dfn (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(code html-full) ()]{
|
||||
A @scheme[code] is
|
||||
@scheme[(make-code (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(samp html-full) ()]{
|
||||
A @scheme[samp] is
|
||||
@scheme[(make-samp (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(kbd html-full) ()]{
|
||||
A @scheme[kbd] is
|
||||
@scheme[(make-kbd (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(var html-full) ()]{
|
||||
A @scheme[var] is
|
||||
@scheme[(make-var (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(cite html-full) ()]{
|
||||
A @scheme[cite] is
|
||||
@scheme[(make-cite (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(abbr html-full) ()]{
|
||||
An @scheme[abbr] is
|
||||
@scheme[(make-abbr (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(acronym html-full) ()]{
|
||||
An @scheme[acronym] is
|
||||
@scheme[(make-acronym (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(sub html-full) ()]{
|
||||
A @scheme[sub] is
|
||||
@scheme[(make-sub (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(sup html-full) ()]{
|
||||
A @scheme[sup] is
|
||||
@scheme[(make-sup (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(span html-full) ()]{
|
||||
A @scheme[span] is
|
||||
@scheme[(make-span (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(bdo html-full) ()]{
|
||||
A @scheme[bdo] is
|
||||
@scheme[(make-bdo (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(font html-full) ()]{
|
||||
A @scheme[font] is
|
||||
@scheme[(make-font (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(p html-full) ()]{
|
||||
A @scheme[p] is
|
||||
@scheme[(make-p (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(h1 html-full) ()]{
|
||||
A @scheme[h1] is
|
||||
@scheme[(make-h1 (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(h2 html-full) ()]{
|
||||
A @scheme[h2] is
|
||||
@scheme[(make-h2 (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(h3 html-full) ()]{
|
||||
A @scheme[h3] is
|
||||
@scheme[(make-h3 (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(h4 html-full) ()]{
|
||||
A @scheme[h4] is
|
||||
@scheme[(make-h4 (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(h5 html-full) ()]{
|
||||
A @scheme[h5] is
|
||||
@scheme[(make-h5 (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(h6 html-full) ()]{
|
||||
A @scheme[h6] is
|
||||
@scheme[(make-h6 (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(q html-full) ()]{
|
||||
A @scheme[q] is
|
||||
@scheme[(make-q (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(dt html-full) ()]{
|
||||
A @scheme[dt] is
|
||||
@scheme[(make-dt (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(legend html-full) ()]{
|
||||
A @scheme[legend] is
|
||||
@scheme[(make-legend (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(caption html-full) ()]{
|
||||
A @scheme[caption] is
|
||||
@scheme[(make-caption (listof attribute) (listof G5))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(table html-full) ()]{
|
||||
A @scheme[table] is
|
||||
@scheme[(make-table (listof attribute) (listof Contents-of-table))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-table] is either
|
||||
@itemize[
|
||||
@item[@scheme[caption]]
|
||||
@item[@scheme[col]]
|
||||
@item[@scheme[colgroup]]
|
||||
@item[@scheme[tbody]]
|
||||
@item[@scheme[tfoot]]
|
||||
@item[@scheme[thead]]
|
||||
]
|
||||
|
||||
@defstruct[(button html-full) ()]{
|
||||
A @scheme[button] is
|
||||
@scheme[(make-button (listof attribute) (listof G4))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(fieldset html-full) ()]{
|
||||
A @scheme[fieldset] is
|
||||
@scheme[(make-fieldset (listof attribute) (listof Contents-of-fieldset))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-fieldset] is either
|
||||
@itemize[
|
||||
@item[@scheme[legend]]
|
||||
@item{G2}
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(optgroup html-full) ()]{
|
||||
An @scheme[optgroup] is
|
||||
@scheme[(make-optgroup (listof attribute) (listof option))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(select html-full) ()]{
|
||||
A @scheme[select] is
|
||||
@scheme[(make-select (listof attribute) (listof Contents-of-select))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-select] is either
|
||||
@itemize[
|
||||
@item[@scheme[optgroup]]
|
||||
@item[@scheme[option]]
|
||||
]
|
||||
|
||||
@defstruct[(label html-full) ()]{
|
||||
A @scheme[label] is
|
||||
@scheme[(make-label (listof attribute) (listof G6))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(form html-full) ()]{
|
||||
A @scheme[form] is
|
||||
@scheme[(make-form (listof attribute) (listof G3))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(ol html-full) ()]{
|
||||
An @scheme[ol] is
|
||||
@scheme[(make-ol (listof attribute) (listof li))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(ul html-full) ()]{
|
||||
An @scheme[ul] is
|
||||
@scheme[(make-ul (listof attribute) (listof li))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(dir html-full) ()]{
|
||||
A @scheme[dir] is
|
||||
@scheme[(make-dir (listof attribute) (listof li))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(menu html-full) ()]{
|
||||
A @scheme[menu] is
|
||||
@scheme[(make-menu (listof attribute) (listof li))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(dl html-full) ()]{
|
||||
A @scheme[dl] is
|
||||
@scheme[(make-dl (listof attribute) (listof Contents-of-dl))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-dl] is either
|
||||
@itemize[
|
||||
@item[@scheme[dd]]
|
||||
@item[@scheme[dt]]
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(pre html-full) ()]{
|
||||
A @scheme[pre] is
|
||||
@scheme[(make-pre (listof attribute) (listof Contents-of-pre))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-pre] is either
|
||||
@itemize[
|
||||
@item{G9}
|
||||
@item{G11}
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(object html-full) ()]{
|
||||
An @scheme[object] is
|
||||
@scheme[(make-object (listof attribute) (listof Contents-of-object-applet))]
|
||||
}
|
||||
|
||||
|
||||
@defstruct[(applet html-full) ()]{
|
||||
An @scheme[applet] is
|
||||
@scheme[(make-applet (listof attribute) (listof Contents-of-object-applet))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-object-applet] is either
|
||||
@itemize[
|
||||
@item[@scheme[param]]
|
||||
@item{G2}
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(map html-full) ()]{
|
||||
A Map is
|
||||
@scheme[(make-map (listof attribute) (listof Contents-of-map))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-map] is either
|
||||
@itemize[
|
||||
@item[@scheme[area]]
|
||||
@item[@scheme[fieldset]]
|
||||
@item[@scheme[form]]
|
||||
@item[@scheme[isindex]]
|
||||
@item{G10}
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(a html-full) ()]{
|
||||
An @scheme[a] is
|
||||
@scheme[(make-a (listof attribute) (listof Contents-of-a))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-a] is either
|
||||
@itemize[
|
||||
@item[@scheme[label]]
|
||||
@item{G7}
|
||||
]
|
||||
|
||||
@defstruct[(address html-full) ()]{
|
||||
An @scheme[address] is
|
||||
@scheme[(make-address (listof attribute) (listof Contents-of-address))]
|
||||
}
|
||||
|
||||
|
||||
A @scheme[Contents-of-address] is either
|
||||
@itemize[
|
||||
@item[@scheme[p]]
|
||||
@item{G5}
|
||||
]
|
||||
|
||||
|
||||
@defstruct[(body html-full) ()]{
|
||||
A @scheme[body] is
|
||||
@scheme[(make-body (listof attribute) (listof Contents-of-body))]
|
||||
}
|
||||
|
||||
A @scheme[Contents-of-body] is either
|
||||
@itemize[
|
||||
@item[@scheme[del]]
|
||||
@item[@scheme[ins]]
|
||||
@item{G2}
|
||||
]
|
||||
|
||||
|
||||
A @scheme[G12] is either
|
||||
@itemize[
|
||||
@item[@scheme[button]]
|
||||
@item[@scheme[iframe]]
|
||||
@item[@scheme[input]]
|
||||
@item[@scheme[select]]
|
||||
@item[@scheme[textarea]]
|
||||
]
|
||||
|
||||
|
||||
A @scheme[G11] is either
|
||||
@itemize[
|
||||
@item[@scheme[a]]
|
||||
@item[@scheme[label]]
|
||||
@item[@scheme[G12]]
|
||||
]
|
||||
|
||||
A @scheme[G10] is either
|
||||
@itemize[
|
||||
@item[@scheme[address]]
|
||||
@item[@scheme[blockquote]]
|
||||
@item[@scheme[center]]
|
||||
@item[@scheme[dir]]
|
||||
@item[@scheme[div]]
|
||||
@item[@scheme[dl]]
|
||||
@item[@scheme[h1]]
|
||||
@item[@scheme[h2]]
|
||||
@item[@scheme[h3]]
|
||||
@item[@scheme[h4]]
|
||||
@item[@scheme[h5]]
|
||||
@item[@scheme[h6]]
|
||||
@item[@scheme[hr]]
|
||||
@item[@scheme[menu]]
|
||||
@item[@scheme[noframes]]
|
||||
@item[@scheme[noscript]]
|
||||
@item[@scheme[ol]]
|
||||
@item[@scheme[p]]
|
||||
@item[@scheme[pre]]
|
||||
@item[@scheme[table]]
|
||||
@item[@scheme[ul]]
|
||||
]
|
||||
|
||||
|
||||
A @scheme[G9] is either
|
||||
@itemize[
|
||||
@item[@scheme[abbr]]
|
||||
@item[@scheme[acronym]]
|
||||
@item[@scheme[b]]
|
||||
@item[@scheme[bdo]]
|
||||
@item[@scheme[br]]
|
||||
@item[@scheme[cite]]
|
||||
@item[@scheme[code]]
|
||||
@item[@scheme[dfn]]
|
||||
@item[@scheme[em]]
|
||||
@item[@scheme[i]]
|
||||
@item[@scheme[kbd]]
|
||||
@item[@scheme[map]]
|
||||
@item[@scheme[pcdata]]
|
||||
@item[@scheme[q]]
|
||||
@item[@scheme[s]]
|
||||
@item[@scheme[samp]]
|
||||
@item[@scheme[script]]
|
||||
@item[@scheme[span]]
|
||||
@item[@scheme[strike]]
|
||||
@item[@scheme[strong]]
|
||||
@item[@scheme[tt]]
|
||||
@item[@scheme[u]]
|
||||
@item[@scheme[var]]
|
||||
]
|
||||
|
||||
|
||||
A @scheme[G8] is either
|
||||
@itemize[
|
||||
@item[@scheme[applet]]
|
||||
@item[@scheme[basefont]]
|
||||
@item[@scheme[big]]
|
||||
@item[@scheme[font]]
|
||||
@item[@scheme[img]]
|
||||
@item[@scheme[object]]
|
||||
@item[@scheme[small]]
|
||||
@item[@scheme[sub]]
|
||||
@item[@scheme[sup]]
|
||||
@item{G9}
|
||||
]
|
||||
|
||||
|
||||
A @scheme[G7] is either
|
||||
@itemize[
|
||||
@item{G8}
|
||||
@item{G12}
|
||||
]
|
||||
|
||||
A @scheme[G6] is either
|
||||
@itemize[
|
||||
@item[@scheme[a]]
|
||||
@item{G7}
|
||||
]
|
||||
|
||||
A @scheme[G5] is either
|
||||
@itemize[
|
||||
@item[@scheme[label]]
|
||||
@item{G6}
|
||||
]
|
||||
|
||||
A @scheme[G4] is either
|
||||
@itemize[
|
||||
@item{G8}
|
||||
@item{G10}
|
||||
]
|
||||
|
||||
A @scheme[G3] is either
|
||||
@itemize[
|
||||
@item[@scheme[fieldset]]
|
||||
@item[@scheme[isindex]]
|
||||
@item{G4}
|
||||
@item{G11}
|
||||
]
|
||||
|
||||
A @scheme[G2] is either
|
||||
@itemize[
|
||||
@item[@scheme[form]]
|
||||
@item{G3}
|
||||
]
|
||||
|
||||
|
|
@ -1,6 +1,7 @@
|
|||
(module info setup/infotab
|
||||
(define name "HTML")
|
||||
(define doc.txt "doc.txt")
|
||||
(define scribblings '(("html.scrbl")))
|
||||
(define compile-omit-files
|
||||
'("dtd.ss" "dtdr.ss" "dtds.ss" "dtd-ast.ss"
|
||||
"case.ss" "html-structs.ss"
|
||||
|
|
|
|||
|
|
@ -213,7 +213,7 @@ font-weight: bold;
|
|||
/* Scheme text styles */
|
||||
|
||||
.schemeinput {
|
||||
color: #996633; /* brown */
|
||||
color: #cc6633;
|
||||
background-color: #eeeeee;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ printed output.
|
|||
@include-section["performance.scrbl"]
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section[#:tag "scripts"]{Scripts}
|
||||
@include-section["running.scrbl"]
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Configuration and Compilation}
|
||||
|
|
|
|||
152
collects/scribblings/guide/running.scrbl
Normal file
152
collects/scribblings/guide/running.scrbl
Normal file
|
|
@ -0,0 +1,152 @@
|
|||
#lang scribble/doc
|
||||
@(require scribble/manual
|
||||
"guide-utils.ss"
|
||||
(for-syntax scheme/pretty))
|
||||
|
||||
@title[#:tag "running" #:style 'toc]{Running and Creating Executables}
|
||||
|
||||
@local-table-of-contents[]
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section[#:tag "mzscheme"]{Running MzScheme and MrEd}
|
||||
|
||||
Depending on command-line arguments, MzScheme runs in
|
||||
@seclink["start-interactive-mode"]{interactive mode},
|
||||
@seclink["start-module-mode"]{module mode}, or @seclink["start-load-mode"]{load mode}.
|
||||
|
||||
@subsection[#:tag "start-interactive-mode"]{Interactive Mode}
|
||||
|
||||
When @exec{mzscheme} is run with no command-line arguments, then it
|
||||
starts a @tech{REPL} with a @litchar{> } prompt:
|
||||
|
||||
@verbatim[" Welcome to MzScheme\n > "]
|
||||
|
||||
@margin-note{For information on GNU Readline support, see
|
||||
@schememodname[readline/rep].}
|
||||
|
||||
To initialize the @tech{REPL}'s environment, @exec{mzscheme} first
|
||||
requires the @schememodname[scheme/init] module, which provides all of
|
||||
@scheme[scheme], and also installs @scheme[pretty-print] for display
|
||||
results. Finally, @exec{mzscheme} loads the file reported by
|
||||
@scheme[(find-system-path 'init-file)], if it exists, before starting
|
||||
the @tech{REPL}.
|
||||
|
||||
If any command-line arguments are provided, add @Flag{i} or
|
||||
@DFlag{repl} to re-enable the @tech{REPL}. For example,
|
||||
|
||||
@commandline{mzscheme -q -i}
|
||||
|
||||
disables loading of @scheme[(find-system-path 'init-file)], but still
|
||||
presents a @tech{REPL}.
|
||||
|
||||
Furthermore, if module-requiring flags appear before
|
||||
@Flag{i}/@DFlag{repl}, they cancel the automatic requiring of
|
||||
@schememodname[scheme/init]. This behavior can be used to initialize
|
||||
the @tech{REPL}'s environment with a different language. For example,
|
||||
|
||||
@commandline{mzscheme -l scheme/base -i}
|
||||
|
||||
starts a @tech{REPL} using a much smaller initial language (that loads
|
||||
much faster). Beware that most modules do not provide the basic syntax
|
||||
of Scheme, including function-call syntax and @scheme[require]. For
|
||||
example,
|
||||
|
||||
@commandline{mzscheme -l scheme/date -i}
|
||||
|
||||
produces a @tech{REPL} that fails for every expression, because
|
||||
@schememodname[scheme/date] provides only a few functions, and not the
|
||||
@scheme[#%top-interaction] and @scheme[#%app] bindings that are needed
|
||||
to evaluate top-level function calls in the @tech{REPL}.
|
||||
|
||||
If a module-requiring flag appears after @Flag{i}/@DFlag{repl} instead
|
||||
of before it, then the module is required after
|
||||
@schememodname[scheme/init] to augment the initial environment. For
|
||||
example,
|
||||
|
||||
@commandline{mzscheme -i -l scheme/date}
|
||||
|
||||
starts a useful @tech{REPL} with @schememodname[scheme/date] available
|
||||
in addition to the exports of @schememodname[scheme].
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@subsection[#:tag "start-module-mode"]{Module Mode}
|
||||
|
||||
If a file argument is supplied to @exec{mzscheme} before any
|
||||
command-line switch, then the file is required as a module, and
|
||||
(unless @Flag{i}/@DFlag{repl} is specified), no @tech{REPL} is
|
||||
started. For example,
|
||||
|
||||
@commandline{mzscheme hello.ss}
|
||||
|
||||
requires the @filepath{hello.ss} module and then exits. Any argument
|
||||
after the file name, flag or otherwise, is preserved as a command-line
|
||||
argument for use by the required module via
|
||||
@scheme[current-command-line-arguments].
|
||||
|
||||
If command-line flags are used, then the @Flag{u} or
|
||||
@DFlag{require-script} flag can be used to explicitly require a file
|
||||
as a module. The @Flag{t} or @DFlag{require} flag is similar, except
|
||||
that additional command-line flags are processed by @exec{mzscheme},
|
||||
instead of preserved for the required module. For example,
|
||||
|
||||
@commandline{mzscheme -t hello.ss -t goodbye.ss}
|
||||
|
||||
requires the @filepath{hello.ss} module, then requires the
|
||||
@filepath{goodbye.ss} module, and then exits.
|
||||
|
||||
The @Flag{l} or @DFlag{lib} flag is similar to
|
||||
@Flag{t}/@DFlag{require}, but it requires a module using a
|
||||
@scheme[lib] module path instead of a file path. For example,
|
||||
|
||||
@commandline{mzscheme -l help}
|
||||
|
||||
is the same as running the @exec{plt-help} executable with no
|
||||
arguments, since the @scheme[help] module is the main @exec{plt-help}
|
||||
module.
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@subsection[#:tag "start-load-mode"]{Load Mode}
|
||||
|
||||
The @Flag{f} or @DFlag{load} flag supports @scheme[load]ing top-level
|
||||
expressions in a file directly, as opposed to expressions within a
|
||||
module file. This evaluation is like starting a @tech{REPL} and typing
|
||||
the expressions directly, except that the results are not printed.
|
||||
For example,
|
||||
|
||||
@commandline{mzscheme -f hi.ss}
|
||||
|
||||
@scheme[load]s @filepath{hi.ss} and exits. Note that load mode is
|
||||
generally a bad idea, for the reasons explained in
|
||||
@secref["use-module"]; using module mode is typically better.
|
||||
|
||||
The @Flag{e} or @DFlag{eval} flag accepts an expression to evaluate
|
||||
directly. Unlike file loading, the result of the expression is
|
||||
printed, as in a @tech{REPL}. For example,
|
||||
|
||||
@commandline{mzscheme -e '(current-seconds)'}
|
||||
|
||||
prints the number of seconds since January 1, 1970.
|
||||
|
||||
For file loading and expression evaluation, the top-level environment
|
||||
is created in the same way for
|
||||
@seclink["start-interactive-mode"]{interactive mode}:
|
||||
@schememodname[scheme/init] is required unless another module is
|
||||
specified first. For example,
|
||||
|
||||
@commandline{mzscheme -l scheme/base -e '(current-seconds)'}
|
||||
|
||||
likely runs faster, because it initializes the environment for
|
||||
evaluation using the smaller @schememodname[scheme/base] language,
|
||||
instead of @schememodname[scheme/init].
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section[#:tag "exe"]{Creating Stand-Alone Executables}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@include-section["scripts.scrbl"]
|
||||
|
||||
116
collects/scribblings/guide/scripts.scrbl
Normal file
116
collects/scribblings/guide/scripts.scrbl
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
#lang scribble/doc
|
||||
@(require scribble/manual
|
||||
scheme/cmdline
|
||||
"guide-utils.ss")
|
||||
|
||||
@title[#:tag "scripts"]{Unix Scripts}
|
||||
|
||||
Under Unix and Mac OS X, a Scheme file can be turned into an
|
||||
executable script using the shell's @as-index{@tt{#!}} convention. The
|
||||
first two characters of the file must be @litchar{#!}; the next
|
||||
character must be either a space or @litchar{/}, and the remainder of
|
||||
the first line must be a command to execute the script. For some
|
||||
platforms, the total length of the first line is restricted to 32
|
||||
characters, and sometimes the space is required.
|
||||
|
||||
The simplest script format uses an absolute path to a MzScheme
|
||||
executable followed by a module declaration. For example, if
|
||||
@exec{mzscheme} is installed in @filepath{/usr/local/bin}, then a file
|
||||
containing the following text acts as a ``hello world'' script:
|
||||
|
||||
@verbatim[#<<EOS
|
||||
#! /usr/local/bin/mzscheme
|
||||
#lang scheme/base
|
||||
"Hello, world!"
|
||||
EOS
|
||||
]
|
||||
|
||||
In particular, if the above is put into a file @filepath{hello} and
|
||||
the file is made executable (e.g., with @exec{chmod a+x hello}), then
|
||||
typing @exec{./hello} at the shell prompt produces the output
|
||||
@tt{"Hello, world!"}.
|
||||
|
||||
The above script works because the operating system automatically puts
|
||||
the path to the script as the argument to the program started by the
|
||||
@tt{#!} line, and because @exec{mzscheme} treats a single non-flag
|
||||
argument as a file containing a module to run.
|
||||
|
||||
Instead of specifying a complete path to the @exec{mzscheme}
|
||||
executable, a popular alternative is to require that @exec{mzscheme}
|
||||
is in the user's command path, and then ``trampoline'' using
|
||||
@exec{/usr/bin/env}:
|
||||
|
||||
@verbatim[#<<EOS
|
||||
#! /usr/bin/env mzscheme
|
||||
#lang scheme/base
|
||||
"Hello, world!"
|
||||
EOS
|
||||
]
|
||||
|
||||
In either case, command-line arguments to a script are available via
|
||||
@scheme[current-command-line-arguments]:
|
||||
|
||||
@verbatim[#<<EOS
|
||||
#! /usr/bin/env mzscheme
|
||||
#lang scheme/base
|
||||
(printf "Given arguments: ~s\n"
|
||||
(current-command-line-arguments))
|
||||
EOS
|
||||
]
|
||||
|
||||
If the name of the script is needed, it is available via
|
||||
@scheme[(find-system-path 'run-file)], instead of via
|
||||
@scheme[(current-command-line-arguments)].
|
||||
|
||||
Usually, then best way to handle command-line arguments is to parse
|
||||
them using the @scheme[command-line] form provided by
|
||||
@schememodname[scheme]. The @scheme[command-line] form extracts
|
||||
command-line arguments from @scheme[(current-command-line-arguments)]
|
||||
by default:
|
||||
|
||||
@verbatim[#<<EOS
|
||||
#! /usr/bin/env mzscheme
|
||||
#lang scheme
|
||||
|
||||
(define verbose? (make-parameter #f))
|
||||
|
||||
(define greeting
|
||||
(command-line
|
||||
#:once-each
|
||||
[("-v") "Verbose mode" (verbose? #t)]
|
||||
#:args
|
||||
(str) str))
|
||||
|
||||
(printf "~a~a\n"
|
||||
greeting
|
||||
(if (verbose?) " to you, too!" ""))
|
||||
EOS
|
||||
]
|
||||
|
||||
Try running the above script with the @DFlag{help} flag to see what
|
||||
command-line arguments are allowed by the script.
|
||||
|
||||
An even more general trampoline uses @exec{/bin/sh} plus some lines
|
||||
that are comments in one language and expressions in the other. This
|
||||
trampoline is more complicated, but it provides more control over
|
||||
command-line arguments to @scheme{mzscheme}:
|
||||
|
||||
@verbatim[#<<EOS
|
||||
#! /bin/sh
|
||||
#|
|
||||
exec mzscheme -cu "$0" ${1+"$@"}
|
||||
|#
|
||||
#lang scheme/base
|
||||
(printf "This script started slowly, because the use of\n")
|
||||
(printf "bytecode files has been disabled via -c.\n")
|
||||
(printf "Given arguments: ~s\n"
|
||||
(current-command-line-arguments))
|
||||
EOS
|
||||
]
|
||||
|
||||
Note that @litchar{#!} starts a line comment in Scheme, and
|
||||
@litchar{#|}...@litchar{|#} forms a block comment. Meanwhile,
|
||||
@litchar{#} also starts a shell-script comment, while @exec{exec
|
||||
mzscheme} aborts the shell script to start @exec{mzscheme}. That way,
|
||||
the script file turns out to be valid input to both @exec{/bin/sh} and
|
||||
@exec{mzscheme}.
|
||||
Loading…
Reference in New Issue
Block a user