Bystro  Te  X
1 Introduction
2 Functions used in headers
bystroserver
bystro-connect-to-server
bystro
3 Some general tricks
4 Functions for manipulating slides
bystro
bystro-titlepage-init
slide
after-pause
remove-slide
use-La  Te  X-preamble
number-for-formula
ref-formula
bystro-bg
bystro-fg
bystro-formula
bystro-equation
bystro-toc
get-bib-from-server
bystro-dump-La  Te  X
5 Miscellaneous functions
get-bystro-scrbl-filename
bystro-set-css-dir
bystro-inject-style
spn
div
tg
init-counter
tbl
align
v+
v-
h+
h-
verb
clr
longtbl
boldred
bystro-js
bystro-js-url
bystro-elemstyle
bystro-rectangular-table?
bystro-path-to-link
bystro-dir-contains-scrbl?
bystro-list-scrbls
bystro-list-scrbls-in-dir
bystro-ribbon
bystro-ribbon-for-location
bystro-shell-dump
bystro-get-cl-argument
6 Functions for reading the configuration file
xml-file->bystroconf-xexpr
bystroconf-xexpr
all-names
get-bystroconf
with-bystroconf
7 Auxiliary functions
with-external-command-as
with-subprocess-as
run-pipeline
8 Legal
7.0

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

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

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)

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

(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.

Set the background color for formulas

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

(bystro-toc)  delayed-block?

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

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 Miscellaneous functions

 (require bystroTeX/common) package: bystroTeX

This .scrbl filename

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

(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

(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\"".

6 Functions for reading the configuration file

 (require bystroTeX/xmlconf) package: bystroTeX

The configuration file is usually called bystrotex.xml

procedure

(xml-file->bystroconf-xexpr xf)  xexpr?

  xf : path-string?
Reads configuration an XML file

value

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

value

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.)

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

(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 !)

8 Legal

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