#lang scribble/doc
@;{
Copyright 2012,2013 Andrei Mikhailov
This file is part of bystroTeX.
bystroTeX is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
bystroTeX is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with bystroTeX. If not, see .
}
@(require scribble/manual
(for-label racket
scribble/core
scribble/base
scribble/html-properties
scribble/decode
scriblib/render-cond
"common.rkt"
"slides.rkt"))
@title{BystroTeX}
@section{Introduction}
This manual is only partially useful, because many functions
are auto-generated by macros. The beginner user should find the instructions
in the form of a slide presentation
@hyperlink["http://andreimikhailov.com/slides/bystroTeX/slides-manual/index.html"]{here},
and also study the sample file @tt{slides-manual.scrbl}, which is in the
samples directory. That sample file can be used as a template for creating new
presentations.
As a general rule, those functions whose name starts with @tt{bystro-}, are either
for internal use or for use in the header. They are not meant to be used in slides by themselves,
or at least not to be used frequently. (But this rule is not very strict.)
@section{Functions for manipulating slides}
@defmodule[(planet amkhlv/bystroTeX/slides)]
@defstruct[bystro ([formula-processor path?]
[formula-database-name string?]
[formula-dir-name string?]
[formula-size integer?]
[formula-bg-color (listof integer?)]
[formula-fg-color (listof integer?)]
[autoalign-adjust integer?]
[manual-base-alignment integer?])]{
Configuration structure (mutable)}
@defproc[
(bystro-titlepage-init)
element?
]{
Installs the titlepage style
}
@defproc[
(slide
[x content?]
[#:tag tg (or/c symbol? string? #f) #f]
[#:showtitle sttl boolean? #f]
[#:rest xs (listof pre-flow?)]
)
part?
]{
A basic slide. The title of the slide is @racket[x], and the contents are @racket[xs].
I recommend providing a nice tag @racket[tg], which will serve as a filename for the html.
Otherwize, @racket[x] will be used as a filename, which may lead to awkward effects.
}
@defproc[
(after-pause
[#:tag tg (or/c symbol? string? #f) #f]
[#:rest xs (listof pre-flow?)]
)
part?]{
The continuation of the slide to be shown after pause.
}
@defproc[(remove-slide)
void?]{
Removes the most recently shown part of the slide
}
@defproc[
(bystro-initialize-formula-collection)
db?]{
This is to initialize the formula collection.
}
@defproc[
(number-for-formula
[x string?]
)
string?]{
Like @literal|{\label{x}}| in @tt{LaTeX}.
}
@defproc[
(ref-formula
[x string?]
)
string?]{
Like @literal|{\ref{...}}| in @tt{LaTeX}, reference to the label @racket[x].
}
@; @defproc[
@; (bystro-command-to-typeset-formula
@; [comm path-string?]
@; [tex string?]
@; [n number?]
@; [fn string?]
@; )
@; string?]{
@; This should not be directly called by the user. Just for reference, @racket[comm] is
@; the path to an executable, which has the following properties. That executable should
@; take 3 arguments: a @tt{LaTeX} string @racket[tex] representing a formula,
@; a number @racket[n] which is the intended fontsize of the formula, and
@; a string @racket[fn] which is the filename, which should have extension @tt{.png}.
@; The executable, upon success, should return a number representing the vertical offset.
@; (Because e.g. letters x and y have different vertical offset.)
@; }
@defproc[
(bystro-formula
[#:database x db? ]
[#:formulas-in-dir y string? ]
[#:shell-command z path? #f ]
[#:size n natural-number/c ]
[#:bg-color bg-color (listof natural-number/c)]
[#:fg-color fg-color (listof natural-number/c)]
[#:align m (or/c (integer-in (- 99) 99) #f) ]
[#:use-depth ud boolean? ]
[#:aa-adjust aa-adj (integer-in (- 99) 99) ]
[#:rest tex (listof string?)])
element?]{
The user probably will not want to call this procedure directly, because there are
various auto-generated shortcuts.
}
@defproc[
(bystro-equation
[tex (listof string?)]
[#:size n natural-number/c]
[#:label l (or/c string? #f) #f]
[#:bg-color bg-color (listof natural-number/c) (bystro-formula-bg-color configuration)]
[#:fg-color fg-color (listof natural-number/c) (bystro-formula-fg-color configuration)]
)
nested-flow?]{
Display-style formula. But it should not be called directly, because there is
a shortcut defined in the headers of the slide file.
}
@defproc[
(bystro-toc)
delayed-block?]{
Insert the list of slides. This is for use on the title-slide.
}
@section{Miscellaneous functions}
@defmodule[(planet amkhlv/bystroTeX/common)]
@defproc[
(bystro-set-css-dir [x path?])
void?]{
Where to find @tt{.css} files. Note that the default @tt{.css} path is the current directory.
}
@defform[(spn someword content)]{
Returns @tt{content}. For example:
@tt|-{@span[attn]{remember to pay the phone bill!}}-|.
Notice the absence of
quotation marks around @tt{attn} in the first argument of @tt|-{@span}-|. The corresponding
CSS could be, for example:
@verbatim|{
.attn {
color: red;
font-weight: bold;
}
}|
(that's how it is currently defined in @tt{misc.css})
}
@defform[(div someword content)]{
Similar to @racket[spn] but creates @tt{div} instead of @tt{span}:
@tt{content
}
The difference is that @tt{div} can extend over several paragraphs.
}
@defform[(tg someword content)]{
Creates @tt{content}, for example:
@verbatim|--{
@tg[ol]{
@tg[li]{The union of open sets is an open set.}
@tg[li]{The finite intersection of open sets is an open set.}
@tg[li]{@f{X} and the empty set @f{\emptyset} are open sets.}
}
}--|
}
@defform[(init-counter name)]{
This is to set up a counter. For example, suppose that I want to include exercises
in my slides. The exercises should be numbered, Exercise 1, Exercise 2, @italic{etc.}
In the header, I add:
@verbatim|--{
@(require racket/dict)
@(init-counter exercise)
@(define (ex-num label)
(elemtag label (number->string (exercise-next label))))
@(define (ex-ref label)
(elemref label (string-append "Exercise " (number->string (exercise-number label)))))
}--|
Then, when I want to give the next Exercise, I say:
@verbatim|--{
@bold{Exercise @ex-num{ProvePositivityOfE}:} Show that the energy is always greater thatn zero
}--|
When I need to refer to this exercise later, I say:
@verbatim|--{
As you should have proven in @ex-ref{ProvePositivityOfE}, ...
}--|
}
@defproc[
(tbl [rows bystro-rectangular-table?] [#:orient dirn (or/c 'hor 'vert #f)])
table?
]{
To insert a table
}
@defform[(align alignment-scheme content ...)]{
This is a table-like structure, useful for multiline formulas. Examples:
@verbatim|--{
@align[r.l
@list[
@f{{2\over 1 - x^2} = } @f{1+x+x^2 + \ldots +}
]@list[
"" @f{1-x+x^2- \ldots}
]
]
}--|
but this comes out with an alignment defect. A better version:
@verbatim|--{
@align[r.l
@list[
@f{{2\over 1 - x^2} = } @v+[2 @f{1+x+x^2 + \ldots +}]
]@list[
"" @f{1-x+x^2- \ldots}
]
]
}--|
Notice that in the first line stands the symbol @racket{r.l} which defines the alignment (right, then left).
The @racket{v+} is a padding, it serves for vertical adjustment, see below.
The @bold{numbered} version of the same formula will be
@verbatim|--{
@align[r.l.n
@list[
@f{{2\over 1 - x^2} = } @v+[2 @f{1+x+x^2 + \ldots +}] ""
]@list[
"" @f{1-x+x^2- \ldots} @label{SumOfGeometricProgressions}
]
]
}--|
Notice that the alignment symbol is now @racket[r.l.n], we added letter @racket[n] for the number.
The function @tt|{@label[]}| is defined in the slides' header.
}
@defproc[
(v+ [n exact-nonnegative-integer?] [#:rest xs (listof pre-content?)])
table?
]{
The content is padded from below, therefore it gets shifted up.
}
@defproc[
(v- [n exact-nonnegative-integer?] [#:rest xs (listof pre-content?)])
table?
]{
The content is padded from above, therefore it gets shifted down.
}
@defproc[
(h+ [n exact-nonnegative-integer?] [#:rest xs (listof pre-content?)])
table?
]{
The content is padded from the left, therefore gets shifted to the right.
}
@defproc[
(h- [n exact-nonnegative-integer?] [#:rest xs (listof pre-content?)])
table?
]{
The content is padded from the right, therefore gets shifted to the left.
}
@defproc[
(bystro-bg [r exact-nonnegative-integer?] [g exact-nonnegative-integer?] [b exact-nonnegative-integer?])
void?]{
Set the background color for formulas
}
@defproc[
(bystro-fg [r exact-nonnegative-integer?] [g exact-nonnegative-integer?] [b exact-nonnegative-integer?])
void?]{
Set the foreground color for formulas
}
@defproc[
(verb [x string?] [#:indent i exact-nonnegative-integer?] [#:rest xs (listof string?)])
block?
]{
Like @racket[(verbatim x #:indent i xs)] but modified so that copy-past does not introduce extra linebreaks
}
@defproc[
(clr [colorname string?] [#:rest xs (listof pre-content?)])
element?
]{
Colored text.}
@defproc[
(longtbl
[ bss (listof (listof block?))]
[#:styless stylepropsss (listof (listof (listof (or/c 'left 'right 'center 'top 'baseline 'bottom 'vcenter))))]
[#:width w (integer-in 1 100)])
nested-flow?]{
Produces a tabular structure of width @racket[w] with cell content @racket[bss] and
cell styles @racket[stylepropsss].
}
@defproc[
(boldred [#:rest x (listof pre-content?)])
element?]{
Text in bold red. @bold{Deprecated} in favor of @tt|-{@spn[attn]{x}}-|.
}
@defproc[(bystro-js [x string?])
traverse-element?
]{Javascript injection}
@defproc[(bystro-js-url [url string?])
traverse-element?
]{Insert Javascript from URL}
@defproc[
(bystro-elemstyle [x (or/c #f string?)] [#:rest otherprops (listof any/c)])
style?
]{Style selector for element. Example of use:
@racket[@element[@bystro-elemstyle{vertical-align:middle} @image{flowers-on-the-wall.png}]]
The @racket[otherprops] are as described in the manual of @racket[element]
}
@defproc[
(bystro-rectangular-table? [l any])
boolean?
]{Verifies if @racket[l] is a list of lists representing a rectangular table}
@defproc[
(bystro-path-to-link [x string?])
string?
]{Returns the string representing a file URL for the UNIX path represented by @racket[x]}
@defproc[
(bystro-dir-contains-scrbl?
[p path?])
boolean?]{
Returns @racket[#t] if the directory @racket[p] contains a scribble-file
}
@defproc[
(bystro-list-scrbls
[p path?]
[#:exclude-same-name x boolean? #t])
(listof path?)]{
Return the list of paths to scribble files in the dir @racket[p]; if @racket[x] is @racket[#t], then exclude the
file which has the same name as the source file
}
@defproc[
(bystro-list-scrbls-in-dir
[p path?]
[#:background-color clr (listof integer?) '(251 206 177)]
)
element?]{
A nicely formatted list of links to scribble files in the folder @racket[p]
}
@defproc[
(bystro-www-ribbon)
table?
]{
This is for putting pages on my website.
Formatted list of all the @tt{.scrbl} files in the current directory,
with the URL of my website prepended.
}
@section{Legal}
Copyright 2012,2013 Andrei Mikhailov
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .