BystroTeX

8.12

BystroTeX🔗ℹ

1 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 here, and also study the sample file 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 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.)

2 Functions used in headers🔗ℹ

(require bystroTeX/slides)

package: bystroTeX

struct
(struct bystroserver (connection token user host port path)
    #:extra-constructor-name make-bystroserver)
  connection : http-conn?
  token : string?
  user : (or/c #f string?)
  host : string?
  port : integer?
  path : string?

Configuration of the LaTeX server

procedure
(bystro-connect-to-server xmlconf-file)
→ (or/c 'running-without-LaTeX-server bystroserver?)
xmlconf-file : (or/c #f path?)

Configures the location of the file containing the parameters of the LaTeX server (port number etc.)

struct
(struct bystro ( formula-processor
formula-database-name
formula-dir-name
formula-size
formula-bg-color
formula-fg-color
autoalign-adjust
manual-base-alignment)
    #:extra-constructor-name make-bystro)
  formula-processor : (or/c 'running-without-LaTeX-server bystroserver?)
  formula-database-name : path-string?
  formula-dir-name : path-string?
  formula-size : integer?
  formula-bg-color : (list/c (integer-in 0 255) (integer-in 0 255) (integer-in 0 255))
  formula-fg-color : (list/c (integer-in 0 255) (integer-in 0 255) (integer-in 0 255))
  autoalign-adjust : integer?
  manual-base-alignment : integer?

Basic configuration

3 Some general tricks🔗ℹ

To load a stylesheet from a file filename.css:

@(element (make-style #f (list (make-css-addition (string->path "filename.css")))) '())

Example of nesting things:

@nested[ #:style @(make-style "comment" '()) @verb|{

This is some text which I want to be show verbatim

]

4 Functions for manipulating slides🔗ℹ

(require bystroTeX/slides)

package: bystroTeX

struct
(struct bystro ( formula-processor
formula-database-name
formula-dir-name
formula-size
formula-bg-color
formula-fg-color
autoalign-adjust
manual-base-alignment)
    #:extra-constructor-name make-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)

procedure
(bystro-titlepage-init) → element?

Installs the titlepage style

procedure
(slide x [#:tag tg #:showtitle sttl] #:rest xs) → part?
  x : content?
  tg : (or/c symbol? string? #f) = #f
  sttl : boolean? = #f
  xs : (listof pre-flow?)

A basic slide. The title of the slide is x, and the contents are xs. I recommend providing a nice tag tg, which will serve as a filename for the html. Otherwize, x will be used as a filename, which may lead to awkward effects.

procedure
(after-pause [#:tag tg] #:rest xs) → part?
tg : (or/c symbol? string? #f) = #f
xs : (listof pre-flow?)

The continuation of the slide to be shown after pause.

procedure
(remove-slide) → void?

Removes the most recently shown part of the slide

procedure
(page x [#:tag tg #:showtitle sttl]) → pre-part?
  x : content?
  tg : (or/c symbol? string? #f) = #f
  sttl : boolean? = #f

This works similar to slide. The differences are:

Do not put curved brackets {} around the content. The content just goes after @page[...], until the next @page[...]
No way to do after-pause
Inside the content, use subpage instead of section / subsection / subsubsection

The intent is that page should be more general-webpage-oriented, while slide more slideshow-oriented.

The CSS style is called pagetitle

procedure
(subpage level x [#:tag tg]) → pre-part?
  level : integer?
  x : content?
  tg : (or/c symbol? string? #f) = #f

Like section / subsection / subsubsection , but inside page (and not slide)

The CSS styles are pagetitle-N where N is level

procedure
(use-LaTeX-preamble #:rest xs) → void?
xs : string?

Defines the LaTeX preamble; this is where we put all our \newcommand{...}{...}s

procedure
(number-for-formula x) → collect-element?
x : string?

Like \label{x} in LaTeX.

procedure
(ref-formula x) → delayed-element?
x : string?

Like \ref{...} in LaTeX, reference to the label x.

procedure
(bystro-bg r g b) → void?
  r : exact-nonnegative-integer?
  g : exact-nonnegative-integer?
  b : exact-nonnegative-integer?

Set the background color for formulas

procedure
(bystro-fg r g b) → void?
  r : exact-nonnegative-integer?
  g : exact-nonnegative-integer?
  b : exact-nonnegative-integer?

Set the foreground color for formulas

procedure
(bystro-formula #:database x
#:formulas-in-dir y
[ #:shell-command z]
#:size n
#:bg-color bg-color
#:fg-color fg-color
#:align m
#:use-depth ud
#:aa-adjust aa-adj
#:rest tex) → element?
  x : db?
  y : string?
  z : path? = #f
  n : natural-number/c
  bg-color : (listof natural-number/c)
  fg-color : (listof natural-number/c)
  m : (or/c (integer-in (- 99) 99) #f)
  ud : boolean?
  aa-adj : (integer-in (- 99) 99)
  tex : (listof string?)

The user probably will not want to call this procedure directly, because there are various auto-generated shortcuts.

procedure
(bystro-equation tex
#:size n
[ #:label l
#:bg-color bg-color
#:fg-color fg-color]) → nested-flow?
  tex : (listof string?)
  n : natural-number/c
  l : (or/c string? #f) = #f
   bg-color : (listof natural-number/c)
= (bystro-formula-bg-color configuration)
   fg-color : (listof natural-number/c)
= (bystro-formula-fg-color configuration)

Display-style formula. But it should not be called directly, because there is a shortcut defined in the headers of the slide file.

procedure
(v+ n #:rest xs) → table?
n : exact-nonnegative-integer?
xs : (listof pre-content?)

The content is padded from below, therefore it gets shifted up.

procedure
(v- n #:rest xs) → table?
n : exact-nonnegative-integer?
xs : (listof pre-content?)

The content is padded from above, therefore it gets shifted down.

procedure
(h+ n #:rest xs) → table?
n : exact-nonnegative-integer?
xs : (listof pre-content?)

The content is padded from the left, therefore gets shifted to the right.

procedure
(h- n #:rest xs) → table?
n : exact-nonnegative-integer?
xs : (listof pre-content?)

The content is padded from the right, therefore gets shifted to the left.

procedure
(bystro-toc) → delayed-block?

Insert the list of slides. This is for use on the title-slide.

procedure
(bystro-local-toc) → delayed-block?

Insert the local table of contents on the page.

procedure
(get-bib-from-server key) → hash?
key : string?

Get the BibTeX entry from the server.

procedure
(bystro-dump-LaTeX b) → void?
b : boolean?

This triggers dumping LaTeX formulas instead of insertion of their pictures. Useful for translating BystroTeX documents into LaTeX.

5 BibTeX🔗ℹ

procedure
(cite x) → element?
x : string?

Cite a BibTeX entry

procedure
(bibliography) → table?

List of references

6 Miscellaneous functions🔗ℹ

(require bystroTeX/common)

package: bystroTeX

procedure
(get-bystro-scrbl-filename) → string?

This .scrbl filename

procedure
(get-bystro-scrbl-name) → string?

This .scrbl filename without .scrbl extension

procedure
(bystro-set-css-dir x) → void?
x : path?

Where to find .css files. Note that the default .css path is the current directory.

procedure
(bystro-inject-style #:rest xs) → element?
xs : (listof string?)

Specify the .css files to use. Enter file names. The path is setup by "bystro-set-css-dir", the default is the current directory.

syntax
(spn someword content)

Returns <span class="someword">content</span>. For example:

@span[attn]{remember to pay the phone bill!}.

Notice the absence of quotation marks around attn in the first argument of @span. The corresponding CSS could be, for example:

.attn {

color: red;

font-weight: bold;

}

(that’s how it is currently defined in misc.css)

syntax
(div someword content)

Similar to spn but creates div instead of span:

<div class="someword">content</div>

The difference is that div can extend over several paragraphs.

syntax
(tg someword content)

Creates <someword>content</someword>, for example:

@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.}

}

Attributes are also supported:

@tg[span #:attrs ([style "color:blue;text-decoration:underline;"] [title "not clickable! Example only!"])]{pseudo-link!!!}

syntax
(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, etc. In the header, I add:

@(require racket/dict)

@(init-counter exercise)

@(define (ex-num label)

(elemtag label (exercise-next label)))

@(define (ex-ref label)

(elemref label (list "Exercise " (exercise-number label))))

Then, when I want to give the next Exercise, I say:

@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:

As you should have proven in @ex-ref{ProvePositivityOfE}, ...

procedure
(tbl rows #:orient dirn) → table?
rows : bystro-rectangular-table?
dirn : (or/c 'hor 'vert #f)

To insert a table

syntax
(align alignment-scheme content ...)

This is a table-like structure, useful for multiline formulas. Examples:

@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:

@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 "r.l" which defines the alignment (right, then left). The "v+" is a padding, it serves for vertical adjustment, see below.

The numbered version of the same formula will be

@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 r.l.n, we added letter n for the number. The function @label[] is defined in the slides’ header.

procedure
(verb x #:indent i #:rest xs) → block?
  x : string?
  i : exact-nonnegative-integer?
  xs : (listof string?)

Like (verbatim x #:indent i xs) but modified so that copy-past does not introduce extra linebreaks

procedure
(clr colorname #:rest xs) → element?
colorname : string?
xs : (listof pre-content?)

Colored text.

procedure
(longtbl bss
#:styless stylepropsss
#:width w) → nested-flow?
  bss : (listof (listof block?))
  stylepropsss : (listof (listof (listof (or/c 'left 'right 'center 'top 'baseline 'bottom 'vcenter))))
  w : (integer-in 1 100)

Produces a tabular structure of width w with cell content bss and cell styles stylepropsss.

procedure
(boldred #:rest x) → element?
x : (listof pre-content?)

Text in bold red. Deprecated in favor of @spn[attn]{x}.

procedure
(bystro-js x) → traverse-element?
x : string?

Javascript injection

procedure
(bystro-js-url url) → traverse-element?
url : string?

Insert Javascript from URL

procedure
(bystro-elemstyle x #:rest otherprops) → style?
x : (or/c #f string?)
otherprops : (listof any/c)

Style selector for element. Example of use:

(element (bystro-elemstyle "vertical-align:middle") (image "flowers-on-the-wall.png"))

The otherprops are as described in the manual of element

procedure
(bystro-rectangular-table? l) → boolean?
l : any

Verifies if l is a list of lists representing a rectangular table

procedure
(bystro-path-to-link x) → string?
x : string?

Returns the string representing a file URL for the UNIX path represented by x

procedure
(bystro-dir-contains-scrbl? p) → boolean?
p : path?

Returns #t if the directory p contains a scribble-file

procedure
(bystro-list-scrbls p
[ #:exclude-same-name x]) → (listof path?)
p : path?
x : boolean? = #t

Return the list of paths to scribble files in the dir p; if x is #t, then exclude the file which has the same name as the source file

procedure
(bystro-list-scrbls-in-dir p
[ #:background-color clr]) → element?
p : path?
clr : (listof integer?) = '(251 206 177)

A nicely formatted list of links to scribble files in the folder p

procedure
(bystro-ribbon) → table?

Formatted list of all the .scrbl files (more precisely, the links to the corresponding .html files) in the current directory.

procedure
(bystro-ribbon-for-location p
[ #:exclude-same-name esn]) → block?
p : path?
esn : boolean? = #f

Same as bystro-ribbon but for some other directory (instead of the current directory).

procedure
(bystro-shell-dump command
[ #:stdin stdin
#:style style
#:indent indent]
#:rest arguments) → block?
  command : string?
  stdin : (or/c (and/c input-port? file-stream-port?) #f) = #f
  style : (or/c style? #f) = #f
  indent : exact-nonnegative-integer? = 0
  arguments : (listof string?)

Inserts the output of a shell command. For example:

@bystro-shell-dump|{sqlite3 -line base.sqlite

select capital,population from countries where continent like '%asia%'}|

Note how we use the at-syntax instead of quotation marks in the SQL query

procedure
(bystro-get-cl-argument key) → string?
key : string?

Extract the value of command line argument of the scribble command. For example, if we invoke as follows:

scribble ++arg --person ++arg Andrei filename.scrbl

then "(bystro-get-cl-argument \"person\")" will return "\"Andrei\"".

7 Functions for reading the configuration file🔗ℹ

(require bystroTeX/xmlconf)

package: bystroTeX

The configuration file is usually called bystrotex.xml

parameter
(working-directory) → (or/c path-string? #f)
(working-directory dir) → void?
dir : (or/c path-string? #f)

A parameter defining the BystroTeX directory. Defaults to current directory.

procedure
(xml-file->bystroconf-xexpr xf) → xexpr?
xf : path-string?

Reads configuration an XML file

procedure
(bystroconf-xexpr) → (or/c xexpr? #f)

Configuration read from the file bystrotex.xml in the current directory. (If there is no such file, returns #f

procedure
(all-names) → (listof string?)

List of all scribbling names in the current directory

procedure
(get-bystroconf name) → (or/c xexpr? #f)
name : string?

Returns the configuration for name

syntax
(with-bystroconf
  bc
  (name dest name.html name.scrbl formulas/ .sqlite arglist multipage?)
  body ...)

Here bc is a configuration for a scribbling (typically a result of get-bystroconf). In the body, name (string?) gets bound to name, dest (string?) to dest, name.html (path?) to just name.html, name.scrbl (path?) to just name.scrbl, formulas/ (string?) to the directory where SVG files of formulas will be stored, .sqlite (string?) to the path to SQLite file. (You can provide your own set of identifiers.)

8 Auxiliary functions🔗ℹ

(require bystroTeX/utils)

package: bystroTeX

syntax
(with-external-command-as nick (com arg ...) action ...)

A wrapper around the Racket’s process* procedure. It executes (find-executable-path com) to find the executable. The following identifiers are available:

nick-stdout is the input-port from the stdout of the process
nick-stdin is the output-port to the stdin of the process
nick-pid is the PID
nick-stderr is the input-port from the stderr of the process
nick-ctl is the control procedure, see the manual for process*

syntax
(with-external-command-as nick #:cmdline xs action ...)

An alternative form, where xs is (list cmd arg ...)

syntax
(with-subprocess-as nick outp inp errp (com arg ...) action ...)

A wrapper around the Racket’s subprocess procedure. It executes (find-executable-path com) to find the executable. The following identifiers are available:

nick-process is the resulting subprocess
nick-stdout is the input-port from the stdout of the process
nick-stdin is the output-port to the stdin of the process
nick-stderr is the input-port from the stderr of the process

See the manual for subprocess

syntax
(with-subprocess-as nick outp inp errp #:cmdline xs action ...)

An alternative form, where xs is (list cmd arg ...)

syntax
(run-pipeline pipe-stdout pipe-stdin (com arg ...) ...)

Runs the pipeline and returns the input-port from its stdout. (Which should eventually be closed by calling close-input-port !)

9 Legal🔗ℹ

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 <http://www.gnu.org/licenses/>.

1	Introduction
2	Functions used in headers
3	Some general tricks
4	Functions for manipulating slides
5	Bib Te X
6	Miscellaneous functions
7	Functions for reading the configuration file
8	Auxiliary functions
9	Legal