Published by www.noteshare.io
What Is Noteshare?
Noteshare is a tool for creating and sharing documents online. We’ll call these documents notebooks. A notebook can be anything: notes for a project, a diary, a collection of poetry. It can be a set of lecture notes or homework problems for a class you are teaching, or an online textbook. It can be a cookbook, a machine shop manual … you name it!
Noteshare Quick Start will get you started writing interesting documents with just an hour’s practice. To get an idea of what is possible, take the tour. To see how a noteshare document is made, look at Sample documents A, B and C in the next three sections.
To learn how to create a new notebook, write, edit, and save text, go to creating a document. To learn how to structure a document with sections and subsections, re-order these, etc. see structuring and formatting text. You will need this as your notebooks grow larger. The rest of this guide addresses the needs of specialized authors and their audiences. Read those that pertain to you.
images
Images and other media
In addition to text, Noteshare documents can contain images, audio, and video, links to web sites, and links to other noteshare documents. You can write mathematical formulas, list computer code, and attach pdf files — scans of handwritten notes, diagrams, drawings, etc. Below, for example, is how you insert an image in a notebook once you upload it to Noteshare.
IMAGE::460[float=right, width=125]
The number 460 is the ID of the image. You will learn about ID’s later — they are a kind of Social Security number for media, documents, you name it. If you are curious about ID’s, take a look at the media database now. Anything you see there can be incorporated into what you write. And of course you can upload your own images. To find an image, use the search box at the top of the Media tab. Try a search on the word bird.
Question and answer format
Of value to anyone who teaches is the question-answer format of the example below — good for problem sets, course notes with exercise, etc. If you click on the text "Answer" the answer will be revealed. If you click a second time, it will be hidden. Questions are automatically numbered. (You may need to refresh your browser for this feature.)
Noteshare has a wealth of features, but this is enough for now.
Examples
One of the best ways of learning Noteshare is to look at examples. By comparing the source text — what you write — with the rendered text — what your readers see — you will quickly learn what you need to know. To this end, there is a set of samples documents at examples.noteshare.io, e.g.,
Below is one very short example, with the source displayed in the sidebar.
Norbert Yocum, Organized Man
Mr. Norbert Yocum is a punctilious maker of lists:
-
Get up
-
Shave & Shower
-
Make breakfat
-
Orange juice
-
Cereal
-
Coffee
-
-
Read the New York Times for exactly 11 minutes
He is fond of algebra and loves the formulas \(a^2 + b^2 = c^2\) and \[ \int_0^1 x^n dx = \frac{1}{n+1} \] In his spare time he likes to experiment with electronics. He keeps a journal which records each experiment:
Each night before going to bed, he reads a bit of poetry, usually of modest literary quality:
Twas brillig, and the slithey toves Did gyre and gimble in the wabe: All mimsy were the borogroves, And the mome raths outgrabe. "Beware the Jabberwock, my son! The jaws that bite, the claws that catch! Beware the Jubjub bird, and shun The frumious Bandersnatch!" Etc.
Creating a document
In this lesson, you will learn how to create and edit new Noteshare document. It will be much like writing an email — no special formatting. Just type away. In the next lesson, you will learn how to structuring and formatting text your text --- add sections, create numbered lists, write bold and italic text, etc.
Throughout you will use the tools in the editor tool panel pictured above. For now you will need just two of the tools in the panel. For a description of what the buttons do, see buttons of the Help Notebook.
Note that if you place the cursor over a tool and wait a second or two, a short description of the tool will appear.
=
Creating a document
-
Open Noteshare in a second window or browser tab so that you can follow these directions and experiment at the same time. When you have the new window up, press the home button . In the middle column where your notebooks are listed, select the new document tool .
-
A form to fill out will appear. You can put "Test" for Area and "First Notebook" for Title, or you can put something of your own choosing. The Tags field is optional.[1] Press Create.
-
You will see a page with a smallish First Notebook followed by a large TITLE.. To the left of First Notebook, you see the edit too . Press it.
-
You are now in the editor. You see two "window panes." On the left is your source text. On the right is the rendered text. For the moment there is not too much difference between source and rendered text. We will get to that later. You are going to change the source text. This is what you see:
== TITLE Your text here
Replace TITLE
by
your own title, add a blank line, and then your own text. Type as much
as you want, and don’t worry about formatting.
Press return whenever you need or want to.
To see the changes you have made and to save your work,
press the update button at the bottom of the page.
You can also press Ctrl-U. Look at the text in
the right part of the page — the rendered text.
It has changed. Continue writing. Press update
or Ctrl-U from time to time, To return to where
you began, press exit or
Ctrl-X. (This button is like "cancel".
It does not save your work.)
Caution
|
Don’t change the two equal signs
(== ). They tell Noteshare that TITLE (or whatever
you replace it by) is a section heading.
A section heading always has the form
two equal signs starting at the left margin
followed by a space followed by the title.
|
Comments
-
To make a new paragraph, insert a blank line, then continue writing.
-
You may notice sometimes that your text looks strange, like
here is some of my text why does it look so weird?
What happened?? Well, by design or by accident, you began your paragraph with a space. This is the signal that Asciidoc uses for verbatim text: that is, text with no formatting, and all spacing respected. This can be useful, but it is not usually what you want to do.
Standard procedure is to start writing at the left margin.
-
In the source text, don’t worry about line endings. Just type away, and press return on your keyboard whenever you want.
Creating a new section
Before you leave this lesson, let’s create a new section and add a little text to it.[2] When you pressed exit, you went to a page that displayed what you had typed. This was in the middle column. On the left is a table of contents with just one item. Above the table of contents you see some buttons. In the editor tool panel find the new section tool and click it to create a new section of your notebook. You can also press Ctrl-N. Then create some text using what you have learned in this lesson.
Now you can relax! Good job!! You have created a notebook and written some text in the first section of the notebook. Then you created a new section. It’s time for a break.
Back from your break? The last part of this lesson is easy — just explore the View menu.
View menu
Take a look at the View menu. It has these items:
Standard |
three-column view with table of contents |
Simple |
a view with out the editing tools |
Source |
source text on left, rendered text on right |
Sec/print |
a printable view of the current section |
Whole doc |
a printable view of the whole document |
LaTeX |
convert the current section to LaTeX (experimental) |
Experiment with these menu items to see what they do. The Source item is especially useful when you are learning Noteshare. It displays the source and rendered text side by side but doesn’t allow you to change anything. Take a look at this section now using Source — see if you can figure out how it was made!
Structuring and formatting text
In the first lesson, you wrote unformatted text whose only
structure was that of the paragraph. In this lesson,
you will learn to structure and format text by putting little markup codes
in it. For example, to
italicize text, you write _italicize text_
, Here the markup
code is the underscore symbol: _. For another example, consider
bold text, which you get by writing *bold text*
. Here the markup
code is the asterisk: *.
The codes _
and *
are part of the Asciidoc markup language.
The engine that powers Noteshare is Asciidoctor,
a very fast Asciidoc processor that has other important features. It can,
for example,
export documents to PDF files, EPUB3 (electronic book) files, as well as
LaTeX files. LaTeX file export is experimental, but is in reasonably
good working order.
Our goal in this lesson is to learn enough markup to write documents with section headings, numbered lists, images, and links to web sites.
Rendering text
When you presed the update button or type CTRL-U as in the previous lesson, you told Noteshare to process the marked-up source text to produce the rendered text: source text ⇒ rendered text. When the source text is marked up, the rendering process is more interesting:
Once you get used to marking up your text, you will find that you can write much faster and stay better focused on your writing than when you have to pause, select text, go the menu, etc.
A Realistic Example
Imagine for a moment that you are a teacher and that you use Noteshare every day to write your lesson plans. One of them, titled Tuesday’s Lesson Plan, is in the sidebar on the right. Take a look through Tuesday’s lesson plan now.
Let’s compare the source text for the Lesson Plan, listed below with the rendered text. The goal is to get a general idea of how the markup affects the rendered text, not to understand it in detail. After you have done the comparison, the section markup, will give a detailed explanation.
As you compare the two versions, pay attention to the following elements:
-
bold and italic text
-
section headings
-
numbered lists
-
images
-
links to web pages
==== Tuesday's Lesson Plan Today we will focus on _matter_. This is stuff of which planets, houses, people, butterflies, bacteria, and a cup of coffee are made. Matter itself is made up of tiny, tiny particles called _atoms_, and these in turn are made of . Protons . Neutrons . Electrons ==== Homework . Read the http://www.chem4kids.com/files/atom_intro.html[chem4kids article] about atoms, then answer the questions below. . How many protons does a hydrogen atom have? How many electrons? . How many protons, neutrons, and electrons does a carbon atom have? . What determines the chemical properties of an atom? . What are the most massive ("heaviest") parts of an atom? !!IMAGE::185[width=200, align=center] *Your assignment is due this Friday.* *Extra credit.* The image above is the first ever made of a single hydrogen atom. Read about it http://physicsworld.com/cws/article/news/2013/may/23/quantum-microscope-peers-into-the-hydrogen-atom[here] and write an essay on the theme "Seeing things that are very small." <<_atomic_theory, Further reading>>
Markup
Let’s review what you have discovered by comparing the marked-up source text for the lesson plan with the nicely formatted rendered text.
-
To write bold and italic text. For bold text, put an asterisk before and after:
*bold text*
. For italic text, put an underscore before and after:_italic text_
. -
To make a section title, write
== section title
or=== subsection title
, or==== subsubsection title
, etc. Be sure to start right at the left margin. -
For each item in an automatically numbered lists, write a period, a space, and then the item. (For bulleted lists, write an asterisk, a space, then the item).
-
To add images, you first upload them to the Noteshare media library. We will learn how to do this in the next lesson. Every image has a numerical ID. The ID number for the atom image is 185, so we wrote this:
!!IMAGE::185[width=200, align=center]
to include the image in our document.
-
To link to a web page like
http://nytimes.com
, just write the URL (web address) with the link text in brackets.http://nytimes.com[New York Times]
The text with the brackets is optional, but is a good way make the link shorter and fit your needs. Look to the right to compare the very long link in the source of the Extra Credit section with the rendered version, where all you see is an underlined "here".
-
You can also link to sections of other Noteshare documents. Like images, each section has a numerical ID. We linked to the section with ID 540 like this
!!XLINK::540[Further reading]
.
That’s it! You have learned about bold and italic text, section headings, lists, images, and links. With these six elements of the Asciidoc markup language, you can write 90% of what you will want to write on Noteshare.
Using what you have learned
You have looked over the lesson plan and learned some basics of the Asciidoc markup language. It is time to put these new tools into practice — go to the tab or window in your browser where you have Noteshare open. Near the top of the left-most column, you should see the Editor Tool Panel, as in the figure. Click on the tool to create a new section.. Create some text using what you have learned in this lesson.
-
If you have "lost" your notebook, press Home. It will be listed in the middle column under my notebooks. Or you can type the name of the notebook in the search box in the top left of the menu bar.
-
If you don’t see the three buttons, press the buttons Write, then Read.
Extras
-
You noticed that there was a link at the beginning of this lesson to the section titled Asciidoc used in the lesson plan. Here is how made that link:
-
You can make nested lists like this:
. Grocery store .. Eggs .. Bacon .. Orange Juice . Hardware store .. Nails .. Caulking compound
For an un-numbered list use asterisks instead of periods:
*Grocery store ** Eggs ** Bacon ** Orange Juice * Hardware store ** Nails ** Caulking compound
Keyboard short cuts
ctrl = Control Key
alt = Alt or Option Key
ctrl-B — Browse
ctrl-R — Read
ctrl-W — Write
ctrl-M — Media
ctrl-P — Print — show printable version of page
ctrl-N — New section
ctrl-E — Edit current section
ctrl-A — Edit aside for current section
ctrl-U — Update: save source text and refresh rendered text
ctrl-X — Exit editor without saving
Media
You can put many types of media — images, audio, and video — in a VS document. To do so, you will use the Noteshare media library, In it, every file is identified by a numerical ID. The image on the right, for example has ID 120: Below, we describe how to
-
Search the Media Library
-
Place files already in the Media Library into your document
-
Upload files to the Media Library
Searching the Library
The media library can be searched by
by keyword or ID. Press Media in the far right of the menu bar.
Once you the Media screen comes up, you will see two search boxes
in the left-hand part of the menu bar. Type the number 120
in the
left-hand box, then press RETURN. What image do you see?
Let’s use this search feature to find an image of a bird. In the second of these, put the word "Bird" and press RETURN. What images do you see? Scroll down until you see the image with ID 458. What kind of bird is it?
Notice the word Random
in the menu bar of the Media tab. Each time
it is pressed, a set of random images is displayed.
Placing Images
You saw then image below when you searched for "Bird" --- it was the image with ID 458. We inserted it in this document with the code
IMAGE:458[]
The space between the brackets in IMAGE:458[]
is for options that control
the size and placement of the image. Here are some examples:
-
IMAGE:458[width=200]
-
IMAGE:458[width=200, float=left]
-
IMAGE:458[width=200, align=center]
Here, for example, is the 200-pixel wide center-aligned image:
You can also put a caption on the photo, as in the example below.
In the case of the captioned image, we have "floated" the image on the left, meaning that the text written below it will wrap around the image. Notice, by the way, that the caption is automatically numbered. There is, of course, a way to turn automatic numbering off. For this and much more information about images, see the Asciidoctor User Manual.
Note
|
You can center an image with a centered caption. Look below the image for the code for this. |
[.text-center] .King parrot IMAGE::463[align=center,width=200]
Other Media
Reference video files using the VIDEO
tag. Thus, use
VIDEO::104[]
to place the video below.
The same technique applies to audio files:
.Chopin AUDIO::56[]
to place this:
External Media
Add a Youtube video using its embed code, e.g. EsTgr-n53Ow?. Then you can write video::EsTgr-n53Ow?[youtube,width=575,height=350] to display the video below.
Inserting ontent from vimeo is done in much the same way. Thus, write VIDEO::111593305[vimeo] to display the video below.
Uploading Media
To add a media file to the Noteshare library, proceed as follows:
-
Select the Media menu item (upper right).
-
Select Upload and follow directions to upload the file from your computer.
-
When the upload is complete, you will see the image in NoteShare. The image had an ID number, say, 198.
Once your file is uploaded and you have the ID number, you can insert in your document, following the directions of the previous section. I you were already writing something and switched over to Media, press "Write to switch back.
Note
|
When you uploaded your file, it was stored in NoteShare’s media library. Uploaded files can be marked as public or private. Public files, like the one with ID 198, can be seen and used by anyone. |
Tables
Suppose you want to construct a table, e.g..,
Eggs |
one dozen |
Potatoes |
twelve pounds |
Milk |
three quarts |
Use the source code below as a model. For more on tables — formatting, etc., — see the tables or the complete reference, Asciidoctor User Guide
|=== | Eggs | one dozen | Potatoes | nine pounds | Milks | three quarts |===
Click blocks
Look at the next paragraph. You see the words "Comment" in blue. Click on the word "Comment". What happened?
Click blocks a good way of making problem sets, training documents, etc. We used them in this way in the section, what is noteshare.
Imitate this example to make click block:
[click.comment] -- This is a click block. Click the header again to hide me. --
Environment blocks
An environment block is much like a click block, except that the header is red and the body is always visible. Environment blocks are automatically numbered, unless you tell them to behave otherwise. Here is a typical environment block
And here is how it is written:
[env.fact] -- Hot air rises.¨ --
The header of a basic environment block has
the form [env.TYPE]
, where TYPE
can be any string e.g., fact
, question
,
comment
, theorem
, equation
, joke
.
The numbering of environment blocks
depends on the TYPE. Thus jokes are
numbered separately from facts and theorems.
Example
Use environment blocks to automatically number elements, as in the examples below. Choose Source from the View menu to see how these were done.
Cross-references
Environment blocks can be labeled and cross-referenced. For example, consider Fact Fact 2. This is a cross -reference to the fact bout the US population mentioned above. It was written like this
[env.fact#population-us] -- The population of the US was 316.1 million in 2013 --
The string population-us
after the symbol #
is the label
for the env block. We used this label in constructing the
cross-reference:
The general form of a cross-reference is
Mathematics
You can freely use (and invent) blocks
like [env.theorem]
, [env.definition]
,
etc. These will be translated into the
corresponding LaTeX environments
if you convert a VS document
into LaTeX (see XX). You can
label and cross-references these
blocks as described in the previous
section.
Some blocks receive special treatment.
One of these is the equation
block:
[env.equation] -- a^2 + b^2 = c^2 --
It is rendered like this:
\[ a^2 + b^2 = c^2 \] | (1) |
The VS equation block is very much like the LaTeX equation
environment: equations are numbered by default and one can
be cross-referenced. Thus, we may refer to the famous formula
equation 1 using the method of the previous section — enclose the label eq-pythagoras
in double pointy brackets.
Notice that the display delimiters \[ … \]
are not needed in
the
equation environment.
Computer code
sum = 0 k = 0 while k < 100: k = k + 1 sum = sum + 1.0/k sum
Mathematics
Write formulas, equations, etc. using LaTeX:, e.g., $`a^2 + b^2 = c^2`$ for the Pythagorean formula, $a^2 + b^2 = c^2, and
+++ \[ \int_0^1 x^n dx = \frac{1}{n+1} \] +++
for the integral formula
\[
\int_0^1 x^n dx = \frac{1}{n+1}
\]
Noteshare usually recognizes the fact that you are writing
mathematical text, but if not, put the code :latex:
somewhere
in your text.
Environments
In place of LaTeX environments, use Asciidoctor environments. For theorems, e.g.,
use this template:
[env.theorem] -- The square on the hypotenuse is the sum of the squares on the other two sides. --
This construct is an example of a block. The body of the block is the text between the dashed lines. The body may contain both in-line and display mathematics:
We wrote it this way:
subs=verbatim]
[env.theorem#cyclotomic] -- The equation +++ \[ z^n = 1 \] +++ has $n$ distinct complex solutions. --
The string cyclotomic
after the mark \#
is a label used in cross-referencing.
Thus w may later say: "Ahem, and I refer you to Theorem Theorem 2.
The reference is written << cyclotomic >> , but with no wpace on either
side of the word "cyclotomic."
You may use [env.equation]
, [env.definition]
, [env.joke]
, etc. — whaterver you like. Each
kind of element is separately numbered,.
Some environment blocks receive special treatment. One of these
is [env.equation]
. For example, the source text
[env.equation] -- \sum_{n=1}^\infty \frac{1}{n} = \infty --
renders as
\[ \sum_{n=1}^\infty \frac{1}{n} = \infty \] |
Equations may be labeled and referred to as before.
Macro definitions
You can put macro definitions in you documents like this:
++++ \( \def\NN{\mathbb{N}} \newcommand{\Set}[1]{ \Big\{\,#1\, \Big\} } \) ++++
Then the source text
+++ \[ \NN = \Set{ \ldots, -2, -1, 0, 1, 2 \ldots } \] +++
is rendered as \[ \NN = \Set{ \ldots, -2, -1, 0, 1, 2 \ldots } \]
Macro definitions can also be put in the "Attributes" screen of a notebook, in which case they are available for use in all sections. Below is an image of the screen in question. You get to it by going into the document editor (select Edit or Write), then from the Edit menu, select Notebook ...
The macros that you put in "Attributes" should follow this form:
[begin:texmacros] \def\ZZ{\mathbb{Z}} \def\EEE{\mathcal{E}} \def\ffp{\mathfrak{p}} \def\bold#1{\bf #1} \newcommand{\set}[1]{ \{\,#1\, \} } \def\dim{\mathop{dim}} [end:texmacros]
Conversion: Noteshare to LaTeX
Use the downlod tool to download a complete set of files for your notebook - text files, image files, etc. This set will contain .html, adoc, and .tex files that represent your compiled noteobook. The conversion from asciidoc to LaTeX is experimental.
Chemistry
Write in-line chemical formulas using the chem::[…]
macro. Thus, to say
\(\ce{ CO2 }\) makes \(\ce{ H2O }\) fizzy!, we say
chem::[CO2] makes chem::[H2O] fizzy!
This macro and the next are wrappers for Martin Hensel’s mhchem ¨package. What about displayed reactions, like the following?
\[\ce{2Fe2O3 + 3C → 4Fe + 3CO2}\] | (1) |
For these we use the chem
environment, e.g.,
[env.chem] -- 2Fe2O3 + 3C -> 4Fe + 3CO2 --
More examples
\[\ce{NaHCO3 + CH3COOH → CO2 + H2O + Na+ + CH3COO-}\] | (2) |
[env.chem#fizz] -- NaHCO3 + CH3COOH -> CO2 + H2O + Na+ + CH3COO- --
The little piece of code fizz
after the symbol #
is a label. It is used
for cross references 2 — see bottom of this page.
\[\ce{Zn ←→ Zn^2+ + 2e-}\] | (3) |
.Electrochemcial reactions [env.chem] -- Zn <--> Zn^2+ + 2e- --
\[\ce{^{227}_{90}Th+}\] | (4) |
[env.chem] -- ^{227}_{90}Th+ --
\[\ce{A\bond{-}B\bond{=}C\bond{#}D}\] | (5) |
[env.chem] -- A\bond{-}B\bond{=}C\bond{#}D --
\[\ce{SO4^2- + Ba^2+ → BaSO4 v}\] | (6) |
[env.chem] -- SO4^2- + Ba^2+ -> BaSO4 v --
Cross references
Reaction (2) is one that you can demonstrate at home.
Reaction (<<fizz>>) is one that you can demonstrate at home.
Document organization
As your document grows, you will find that you want to re-order sections and subsections For this you will use the editor control panel (right). If you press the Table of Contents Tool, , you will get three-column screen with section numbers, e.g., 1, 2, 3.1, 3,2, etc. section titles, and blank boxes. The figure below titled Hodge theory, illustrates this.
Suppose you want section 2.2 to be where section 2.1 is. Just type 2.1 in the box on the right of "2.1 Topology". Press return, and the change is made.
The same principle works on the setion level: type 1 in the box to the right lf "2 Elliptic curves" to promote the latter to frist position.
You can also promote subsections to sections and demote sections to subsections. Type 3 in the box to the right of 3.2 Projecive Space. The projective space will become the new section 3, with Basic Algabraic Geeometry pushed down to become section 4.