Scripta User Guide

Welcome to Scripta, the tool designed to make it easy to put your content on the web: lecture notes and class handouts, the book you are writing, whatever.

Notice the toolbar, which you will find on the upper left. It looks like this:

image%3A%3A987bc26c22bd34aee0ff Screen%20Shot%202016 04 09%20at%204.14.17%20PM

Click to select the kind of document view you want:

1

1-column view

2

2-column view.

S

View Source

C

View Compiled document

T

View Titlepage


For this document, S is the best option because you want to compare the source text (on the left) with the rendered text (on the right).

For help getting started, see also the Scripta Cookbook. Remember to use the S option to "view source" in reading this document.

Getting started

Content in Scripta is written in Asciidoc, a markup language. Notice how Asciidoc is formatted — with little marks before and after the words that are to be made italic or bold. The marks help to give your text structure and visual form. We will give just a few examples in this section to get you started. You can write a great deal of text with just a few bits of markup. You can learn more as you need it.

You wrote italic and bold text using inline formatting. Here is one more example — what you might need to explain computer code: json = { 'fred' ⇒ 'abc5176' }.

Lists

Let’s make a list:

Groceries
  1. Bacon

  2. Butter

  3. Eggs

  4. Cholesterol medicine

Numbered items begin with a period at the left margin, followed by a space, followed by the item. The heading, which is optional, has the form period followed immediately by the text of the heading. For an itemized list, use asterisks instead of periods. For lists that have sublists, use double periods or double asterisks Etc. It is all very logical.

Let’s link to this article: The Spoon and the Wine Bottle. Just paste in the URL and follow it by the link text you want enclosed in brackets.

Images

image%3A%3A7f2f0b890096490858b6 Viceroy Butterfly compressed

To upload an image, you need to be in the editor. Click on the image%3A%3A3b37d6af577a7fe2a272 image black icon, fill out the form, choose the image, and press Upload. When you are brought back to your document, you will notice a blue button to the right of the image%3A%3A3b37d6af577a7fe2a272 image black icon with text something like insert 1272. The number 1272 is the ID number assigned to your image. Put your cursor where you want the image to be and click on the blue button. It will insert the link for the image.

image%3A%3A7f2f0b890096490858b6 Viceroy Butterfly compressed

As the image on the right shows, there are many ways of formatting an image. Try float=left, align=center, For more options, see XX. The same style of link can be used for videos and audios — whether uploaded into scripta, linked to youtube or vimeo, etc. See XXX.

Mathematics

You can do ninety percent of your writing with just a few markup codes. But when you need something more sophisticated, the tools are there for you. One of these is LaTeX, which you can use for in-line formulas like \(a^2 + b^2 = c^2\) or for displayed formulas like \[ \int_{-\infty}^\infty e^{-x^2/2} = \sqrt{2\pi} \]

Theorem 1.
There are infinitely many primes.
Theorem 2.
The series \[ \sum_{n=1}^\infty \frac{1}{n} \] diverges

Notice the LaTeX-like environments. Documents written in Scripta can in fact be exported to LaTeX. Just use the image%3A%3Ae6ba95d6b99336a4f1a6 Screen%20Shot%202016 04 09%20at%209.12.45%20PM tool in the pop-up toolbar in the editor:

image%3A%3Afbd4f2e8ea2a9e9b49ea Screen%20Shot%202016 04 09%20at%209.12.13%20PM

Chemistry

Chemistry, like mathematics, has its own symbology. There are in-line markup tools for chemical formulas and reactions, e.g., \(\ce{ C12H22O11 }\). More elaborate structural formulae can be handled as images, just as we did with the butterfly.

200px Saccharose2 original

Code

// Simple web server
var http = require('http');

var server = http.createServer(function (request, response) {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.end("Hello World\n");
});

server.listen(8000);
console.log("Server running at http://127.0.0.1:8000/")

You may want to look at the code example in single column mode — the lines are a bit long for the two-column modes.

Wrapping up

Notice that how we did section and subsection headings — two equal signs, a space, and then the text for section headings. Three equal signs for subsubsections, etc.

Warning
Some times your text comes out looking funny, as in the next paragraph. That is because you did not start our paragraph at the left margin. This is a feature, not a bug. It is used when you need to preserve formatting exactly.
 This is a test.
I repeat. It
  is
    a test
       of what I said
above!

Asciidoc 101

In this section we discuss the bare minimum that you need for common writing tasks — in-line formatting such as bold-face and italic, dividing your document into sections, making lists, cross-references, etc. To begin writing, just go for it; write like you would write an email. To make a paragraph, add one or more blank lines before it.

Note
Be sure to start your paragraph at the left margin, with no leading space.

In-line formatting

bold-face

Write bold-face text like this: *bold-face text*.

italic

Write italic text like this: _italic text_.

bold-italic

To get this, write *_get this_*.

highlighted text

To make your text look like this, write it like this:

#make your text look like this#

monospace

To obtain mono-spaced text, write

`mono-spaced text`

hyperlinks

References to a web site can be inserted verbatim, as in

or they can be "dressed up", as in this example:

For a dressed-up link, add a title in brackets right after the URL:

https://en.wikipedia.org/wiki/Prime_number_theorem[Prime Number Theorem]

Structure

sections

Precede a section heading by ==, a subsection heading by ===, and so on, like this:

== Introduction

== Conservation Laws

=== Energy

=== Momentum

Be sure to start the –0— right at the left margin. To automatically number sections, put the code

   :sectnums:

before the first section to be automatically numbered. To turn automatic numbering off, insert the code

   :!sectnums:

numbered lists

Here is a numbered list

  1. Eggs

  2. Bacon

  3. Strawberry Jam

    You write it like this

    . Eggs
    . Bacon
    . Strawberry Jam

    Each item begins with a dot at the left margin.

itemized lists

Here is an itemized list

  • Eggs

  • Bacon

  • Strawberry Jam

You write it like this

* Eggs
* Bacon
* Strawberry Jam

Note. There is a formatting bug the prevents the bullets from being shown. — I will correct this as soon as possible.  — Jim

Verbatim text

Verbatim text is "as-is" text with no formatting. Here is an example:

This
  is verbatim
        text!

It appears exactly as written and is rendered in a font different rom that in the main text. One way of writing a paragraph of verbatim text is to begin the first line with a space. Sometimes this is want you want to do, but often it happens by accident. If your rendered doesn’t looks odd, you probably started it with a space.

Another way of writing verbatim tex is to write a block of text "fenced-in" by the code ----:

  ----
  This is
         verbatim       text
  Cool!
        Yeah!!
  ----

Definitely useful for writing computer code and avant-garde poetry.

Warning
Be sure to "balance" codes like ----. If you write the "opening code", you must balance it with a second, "closing code". Just like with parentheses. If you don’t do this, you will have to debug your text.

Media

images

Images can be uploaded to Scripta by clicking on the image%3A%3A3b37d6af577a7fe2a272 image black icon. When you upload an image, its ID number will appear next to the image%3A%3A3b37d6af577a7fe2a272 image black icon. Place your cursor where you want to place the image, then click on the ID number. You can also search the image database for images to use. The image below was inserting by writing image ::458[]

894252393 original

There are many ways to control formatting, e.g.,

image ::458[width=200],   image ::458[float=left],   etc.

audio

Audio is treated in the same way. Thus the code

audio ::56[]

renders as

This is an excerpt from Chopin’s posthumous Nocturne n C# minor.

video

Video is uploaded in the same way as images using the image%3A%3A3b37d6af577a7fe2a272 image black tool. Thus the code

video ::22[]

renders as

This video, which represents a random process in two space dimensions and two dimensions of color, was created using Processing, a computer language for producing still and moving images.

YouTube

To insert a Youtube video, get its embed code, e.g. EsTgr-n53Ow?, then insert like this

video ::EsTgr-n53Ow?[youtube, width=575,height=350]

Here is the result:

Merkin Concert Hall, February 9, 2014

Sonata for Cello and Piano, by George Oakley
Jay Campbell, Cello, Inga Kashakashvili, Piano

Vimeo

The same principles apply to videos on Vimeo. To place the video below,

use

video ::111593305[vimeo]

Teaching Tools

The "click block" feature of Scripta can be used to construct interactive quiz/review material for students. The format is (1) question (2) answer, where the answer is hidden until the student clicks on it. Click on it again to re-hide the answer.

History Questions

Question 1.
What was the name of the Roman general who wrote a book about his conquest of Gaul?
Answer
Julius Caesar
Source
[env.question]
--
What was the name of the Roman general
who wrote a book about his conquest of Gaul?
--

[click.answer]
--
Julius Caesar
--

You can say [env.question], [env.problem], etc., depending on the context. What goes for env blocks also goes for click blocks. You can say [click.answer], [click.hint], etc. Below we use both answers and hints:

Question 2.
Who is buried in Grant’s tomb?
Hint
Think about it!
Answer
President Ulysses S. Grant

Math Questions

Using the same format as above, you can also write mathematics problems.

Problem 1.
Expand \((a+b)^2\)
Solution
\(a^2 + 2ab + b^2\)
Problem 2.
Factor the number 510510.
Hint
Use trial division
Solution
\(2\cdot 3\cdot 5\cdot 7\cdot 11\cdot 13\)

Writing tools

Scripta has a variety of writing tools, from word counts to indexes.

Word count

The word count of the current chunk of your document is displayed in the footer of the document as you edit.

Footnotes

To make a footnote,[1]. like the one in this sentence, insert the text

footnote:[This is just
a test of the amazing capabilities of
http://asciidoctor.org[Asciidoctor]

Commenting out

Sometimes you may wish to leave text in the source that is not visible in the rendered version. For a single line, do this:

// This section needs to be revised.

For more than one line, you may do this;

////
This article needs a much clearer outline.

Please call Ms. Grundy, the staff editor,
as soon as possible.
////

Cross-references

Basic

To make a cross-reference to another part of the text, enclose the ID for that part of the text in double angle brackets:

   <<ID>>

You can make your on ID’s, or you can use Scripta’s auto-generated ID’s. For example, consider this section, Writing tools. The ID _writing_tools_ is automatically generated, so we can insert the text

  <<_writing_tools>>

to make a cross-reference. It will appear as an active link to the Writing tools section,

Across blocks

In Scripta, a "master" document consists of one or more blocks. Imagine blocks of text that when laid end-to-end make up your document. In this document, Asciidoc 101, Teaching Tools, and Writing Tools are blocks. Note the little square before the block name.

To reference another block, use the code

xlink ::787[Introduction]

as a model. Here 787 is the ID of the block in question. The ID of the document being edited is displayed in the right part of the editor tool bar.

As an example, we make the link Teaching Tools to the previous section using this code:

xlink ::1492[Teaching Tools]

Across blocks to a specific item

You can also link to a specific item inside a block. Consider, for example, the subsection History Questions in the section Teaching Tools. The link

refers to the History Questions item. Here is the code:

xlink ::1492#_history_questions[Making History Questions]

Glossary

You can mark terms for a per-section glossary like this:

Screenshot 2015 09 28 00 original

In this case, the word potrezebie would be inserted in the glossary that you will find at the end of this section. In the main text, you would find potrezebie set in a dark red color. Look to see if you find any glossary terms on this page. Glossary terms link to their entry in the glossary list and vice versa.

You may also mark a glossary term like this:

Screenshot 2015 09 27 18 original

In this case, the phrase "imaginary contraption" appears in the glossary as explanatory text for the term "potrezebie." (We do note, by the way, that there was a time in the previous millennium in which the term potrezebie appeared in certain forms of humorous litereature).

To instruct Noteshare to display the glossary, put the code :glosssary: somewhere in the section — the beginning and the end are good choices. The glossary will appear at the end of the section. Thus, in the present section, the glossary appears at the end of the last subsection — subsection "[last_section]" — take a look at it now.

Note
See Writing Tools for a long example of a glossary.

Building an Index

Index

Suppose you are writing a text about animals:

The Aardvark is a strange animal with an
equally strange name ...

To add "Aardvark" to the index, change your text to this:

( ( (Aardvark) ) ) The Aardvark is a strange animal with an equally strange name …​

The index works only in the compiled view. Also, in order to instruct Scripta to make the index, you must add the code

make_index: yes

to your document preferences. To edit your document preferences, click on the triple-gear icon image%3A%3Aa8aba2877d7515698804 gears black.

Bibliography

To cite an entry in the bibliography, follow this model:

_The Cyberiad_ <<cyb>>, reviewed in
<<cyb2>>, recounts the adventures of

Note that the citations, following the usual syntax for cross-references, consist of a label enclosed in double angle brackets. The bibliography itself begins as in the following excerpt. Note that the bibliographical labels are enclosed in triple brackets/

[bibliography]
- [[[cyb]]] Lem, Stanisław (1975).
The Cyberiad –
fables for the cybernetic age.
translated by Michael Kandel.
United Kingdom: Secker and Warburg.
ISBN 0436244209

Below are the rendered bibliographical citation and bibliography.

The Cyberiad [cyb], reviewed in [cyb2], recounts the adventures of the robots Trurl and Klaupicius as they explore the universe, encountering all manner of life-forms.

Bibliography

Below is the glossary automatically constructed from the marked-up text.

Tables

Simple table

Eggs

one dozen

Potatoes

twelve pounds

Milk

three quarts


Source code
|===
| Eggs | one dozen
| Potatoes | nine pounds
| Milks | three quarts
|===

Formatted table

Eggs

12

0.56

$6.72

Potatoes

9 lb

0.45

$4.05

Milks

3 quarts

1.89

$5.67


Source code
[cols="<,^,>,>"]
|===
| Eggs | 12 | 0.56 | $6.72
| Potatoes | 9 lb | 0.45 | $4.05
| Milks | 3 quarts | 1.89 | $5.67
|===

Table with a header

Description Quantity Unit Price Price

Eggs

12

0.56

$6.72

Potatoes

9 lb

0.45

$4.05

Milk

3 quarts

1.89

$5.67


Source code
[cols="<,^,>,>", options=header]
|===
| Description | Quantity | Unit Price | Price
| Eggs | 12 | 0.56 | $6.72
| Potatoes | 9 lb | 0.45 | $4.05
| Milk | 3 quarts | 1.89 | $5.67
|===

Description Quantity Unit Price Price

$16.44

Eggs

12

0.56

$6.72

Potatoes

9 lb

0.45

$4.05

Milk

3 quarts

1.89

$5.67


The source code
[cols="<,^,>,>", options="header,footer"]
|===
| Description | Quantity | Unit Price | Price
| Eggs | 12 | 0.56 | $6.72
| Potatoes | 9 lb |  0.45 | $4.05
| Milk | 3 quarts | 1.89 | $5.67
|   |  |   |$16.44
|===

Mathematical text

Inline LaTeX

Inline mathematical text is written in the normal way, enclosed by dollar signs: $ …​ $. For currency in regular text, use \$.

Examples
subscripts

$a_1, \ldots, a_n$ ⇒ \(a_1, \ldots, a_n\).

superscripts

$x^2 + y^2 = z^2 $ = \(x^2 + y^2 = z^2\)

Greek symbols

$\alpha, \beta, ... \Omega$ ⇒ \(\alpha, \beta, ... \Omega \)

Special symbols

$\int_0^1 x^n dx$ ⇒ \(\int_0^1 x^n dx\),
$\lim_{x \to 0} \frac{ \sin(x)}{x}$ ⇒ \(\lim_{x \to 0} \frac{ \sin(x)}{x}\)
$A \cap ( B \cup C)$ ⇒ \(A \cap ( B \cup C)\)
Etc. See this list.

Grouping

$10^{-23} $ ⇒ \(10^{-23}\)

Displayed LaTeX

For displayed formulas you may use double dollar signs, but it is better to use a pair of braces:

                    \[ ... \]
Examples
Matrices

\[ A = \left[ \begin{array} 11 & 2 \\ 3 & 4 \\ \end{array} \right] \] The matrix is rendered from the text

 \[
  A =
    \left[
    \begin{array}
    11 & 2 \\
    3 & 4 \\
    \end{array}
    \right]
 \]
Partial differential equations

\[ - \frac{\hbar^2}{2m} \frac{\partial^2 \psi}{\partial x^2} + V\psi = i\hbar \frac{\partial \psi}{\partial t} \]

The source text is

 \[
    -\frac{\hbar^2}{2m}
    \frac{\partial^2 \psi}{\partial x^2}
    + V\psi
    =
    i\hbar \frac{\partial \psi}{\partial t}
 \]

Environments

Environments in Asciidoc-LaTeX work much like LaTeX environments, but have a different syntax and are more general. There are the typical mathematical environments (theorem, definition, equation, etc.), but also environments for chemical formulas and reactions as well as code listings. Here is a typical use for mathematics:

[env.theorem]
--
A line is the shortest path between two points.
--

It renders as

Theorem 3.
A line is the shortest path between two points.

You may label an environment for cross referencing, as in this example:

[env.definition#def-point]
--
A point is that which has no breadth
--

It renders as

Definition 1.
A point is that which has no breadth

The text after the hash mark is the label, or identifier.

To make the cross reference, enclose the label in double pointy brackets with no space:

"The professor harrumphed haughtily:
I refer you to <<def-point>>."

renders as

"The professor, harrumphed haughtily: I refer you to Definition 1."

Note that the the text "Definition 1" is a link.

Environments can contain LaTeX, as in the next example:

Theorem 4.
Let \(f(x)\) be a continuous function. Then \[ \frac{d}{dx} \int_0^x f(u) du = f(x). \]

Special environments

There are a number of special environments whose content is processed differently from env.theorem, env.definition, etc.

Equation environment

It is generally better to use env.equation for displayed equations: if you want them to be numbered for later reference, just add an identifier. Here is an example without an identifier:

\[ x^2 + y^2 = z^2 \]
[env.equation]
--
x^2 + y^2 = z^2
--

And here is an equation with an identifier:

\[ x^d + y^d = z^d \] (1)
[env.equation#fermat]
--
x^d + y^d = z^d
--

Note that putting an identifier (#fermat) "turns on" the automatic numbering.

Equation align environment

One often needs to write aligned sets of equations, like these:

\[\begin{split} (a + b)^2 &= a^2 + 2ab + b^2 \\ (a + b)^3 &= a^3 + 3a^2b + 3ab^2 + b^3 \end{split}\] (2)

Here is the source code:

[env.equationalign#binomials]
--
  (a + b)^2  &= a^2 + 2ab + b^2 \\
 (a + b)^3  &= a^3 + 3a^2b + 3ab^2 + b^3
--

Macros

You can use your own macros in a Scripta document. There are two ways to do this. The first is to add macros to the section you are working on like this:

[env.texmacro]
--
   \def\QQ{\mathbb{Q}}
   \def\ZZ{\mathbb{Z}}
   \newcommand{\set}[1]{ \{\,#1\,  \} }
   \newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} }
--
\( \def\QQ{\mathbb{Q}} \def\ZZ{\mathbb{Z}} \newcommand{\set}[1]{ \{\,#1\, \} } \newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} } \)

Then, if you write using the source code

 \[
    \QQ = \sett{ a/b }{ a, b \in \ZZ, b \ne 0}
 \]

the rendered text will be \[ \QQ = \sett{ a/b }{ a, b \in \ZZ, b \ne 0} \]

Document-wide tex macros

The env.texmacros hack is quick and dirty, but has the disadvantage that the macros only work in the section in which they live. A better solution is to put all of your macro definitions in a special document, the texmacros document. To set up the texmacros document, proceed as follows:

  1. Select the document title at the top of the table of contents

  2. Click on the "add associated document" tool image%3A%3Ad6aa28ecbffcf97b7de8 site black .

  3. In the form that comes up, enter "Tex Macros" for the type and "texmacros" for the type. Paste your tex macros in the window that appears below these two items.

  4. Click update.

You can edit texmacros any time. The macros you put in it are available to all sections of the document.

The search bar offers advanced search capablities.

ti foo

Search for documents with title matching foo.

ta foo

Search for documents with a tag matching foo

au foo

Search for documents by author with screen name foo

We are working to expand these capabilities. Eventually they will be available only to paid users.

Collaboration

This section is under construction.

Users have levels of privilege and annual fee.

NOTE

During the development phase, there are no annual charges. Our aim in any case is to keep them low and affordable for individuals once the site is a going concern. The price schedule is a subject of ongoing conversation among the members of the development team:-)

Commands not implemented yet are marked with an asterisk.

Table 1. Individual rate schedule

Level

Annual fee

Privileges

0

free

Same as non-signed in user

1

$15

Can manage their own node, participate in groups

2

$30

Can form and manage groups

3

$60

Can form and manage up to N nodes; additional nodes at a cost to be determined.

Level one commands

add document:1242

add the document with ID 1242 to the current node.

remove document:1242

remove the document with ID 1242 from the current node.

Any user can execute these commands for his own node. Node owners and administrators can also execute this command.

join group:reading of user:alpha*

Join alpha’s open access group reading

join group:secret of user:alpha using code:456qq*

Join alpha’s restricted group secret using the access code 456qq.

Level two commands

In this section, we assume the user is logged in with screen name alpha.

create group:foo

create a group named alpha_foo.

remove group:foo

remove the group alpha_foo.

add document:123 to group:foo

add the document with ID 123 to the group alpha_foo with read-write permissions.

add document:123:read_only to group:foo

as above, but with read only permissions

remove document:123 from group:foo*

remove the document with ID 123 to the group alpha_foo.

list groups

Display a list of the user’s groups.

Under construction


1. This is just a test of the amazing capabilities of Asciidoctor

Documents not found.