Source

tome / doc / intro.tome

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
%
% Copyright 2013 Brian Mearns
% 
% This file is part of Tome.
% 
% Tome is free software: you can redistribute it and/or modify
% it under the terms of the GNU Affero General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
% 
% Tome 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 Affero General Public License for more details.
% 
% You should have received a copy of the GNU Affero General Public License
% along with Tome.  If not, see <http://www.gnu.org/licenses/>.
%

:Title: Tome
:Title: A Markup Language and Tool Suite for Authors
:Title: And an exercise in unobstructed writing

:Author: Brian Mearns

:Meta: lang             en-US
:Meta: uid              https://www.barrenmains.com/epub/tome/intro
:Meta: license          Creative Commons BY-NC-ND 3.0
:Meta: license-url      https://creativecommons.org/licenses/by-nc-nd/3.0/deed.en_US


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%




:Part: Introduction

:Chapter: Introduction


Tome is a markup language that was designed for use by authors, primarily authors of novels or other works
with relatively simple requirements. The intention is to be quick, simple, and above all  unobtrusive
to the writing process.

Tome offers a relatively small set of markup elements which are entirely  related to content or structure---
not style. The philosophy behind  Tome is that writers should focus writing, first and foremore. Once
the story is written, you or your publisher can bo back and tweak the  margins or the font or whatever
for as long as you like, but doing so  during the writing process is really only a distraction.

Tome is deliberately not very flexible in terms of markup, because the  more flexible it is, the more
time you spend tweaking things, and the  less time you spend writing. There are no macros, no custom
definitions, no settings: just write and write and write, and when you're done, Tome  will generate
output documents for you, which you can then tweak to your  heart's content.

***

Before going any further, let it be clear that tome is a command line tool, there is no GUI interface for it.
Although it is very simple to use, if you're not at least slightly familiar with the command line (meaning,
you don't even know how to open a command prompt), then tome is not for you.

***

In this document, we will introduce the Tome markup language and tool suite, providing information that
should be sufficient for you to get started writing Tome. Because it is such a simple markup language, it
should not be very difficult for you to learn.

In this first part, we will provide an overview and description of tome including it's features, but will not
get into the details of its use. For that, skip ahead to part 2.


:Chapter: Overview
:Title: A General Description of how Tome Works

To use tome, you write your document using tome markup, and then use the  tome tool suite to generate an
output document. Tome can generate output  documents in several different formats include EPUB/HTML, Latex,
and  plain text. The tome tools are also open source and available under the  GNU Affero General Public License, so
if you know how to program in python, so  can pretty easily develop your own output writer for whatever
format you  desire.  

Technically, tome is more of a  !{grammar}!  than a language. Or,  another way of looking at it, tome is
a family of languages, all with  the same grammar, but with different syntaxes. What this means is that  
there are a number of different tome languages you can use to write your  document, but the content and
structure will be the same.  

For instance, the canonical representation of a tome document is in XML.  You could, if you wanted, write
your document in XML, but this would be  a lot of unecessary work and is not very conduscive to the writing  
process.  

So instead, if you're a user of the Vim text editor, you could use the  original tome language, now called  
"{Tome-OTL}", which is compatible  with the Vim Outliner syntax: this allows you to write your document as  
an outline and collapse sections when you don't need to see them.  

If you're more of a traditional writer, you can instead use the  "{Tome-Flow}"  language, which is a less
structured variant that is much  better suited to bare-bones plaintext editors.  

Whatever tome language you use, the internal representation of your  document within the tome tools
will be the same, which means your output document will be the same as well.  


:Chapter: Basic markup
:Title: Inline Markup for Text Segments


Tome includes markup for  /{italics}/, and  *{bold}*, and  _{underline}_,  and general  !{emphasis}!. These
are considered  !{structural}!, not  !{stylistic}!  markup elements, because they mark a certain segment of  
text as having a particular purpose: for instance standing out from the  surrounding text. The output writer
will still decide how exactly they  should be styled, your markup simply indicates to the writer what the  
purpose is.  

With this in mind, the emphasis markup will probably be the most useful  in general. This is an instruction
to the writer that you simply want the text  to standout from the surrounding text, and the writer will
decide the  best way to do that. For instance, a common to emphasize text is to make  it italics, but if the
surrounding text is already italics, the  emphasized text will need to be rendered in some other way in order
to  stand out.  

The italics and bold markup are more specific instructions: italicized  text is meant to be rendered slanted,
and bold text is meant to be  rendered with a heavier weight, or a  "{thicker brush}". Because they so  
closely toe the line between style and structure, it is recommended that  you use them sparingly. However,
there may be times when you want to be  this explicit. For instance, it is common for the latin names of a  
species to be rendered in italics, and it would be inappropriate for the  writer to style it in some other
way.  

Underline is similar, though there are traditionally some very specific  uses of underlined text, such as the
title of a book.  




:Chapter: Block Markup


Tome includes a few markup elements referred to as  "{block markup}"  or  "{block segments}". These are
markups that may apply to large blocks of  text and may contain paragraph breaks within them.  

Probably the most commonly used block markup is for !{quotation}!.  Quotation in tome documents should always be
done using the prescribed  markup, instead of manually by typing quotation mark characters.  This allows  "{
smart quoting}"  to be generated in the output: for  instance using the  "{curly quote}"  characters instead
of simply "straight  quotes" (where possible, depending on the output format).  

Additionally, quoted content in Tome can contain paragraph  breaks and using the markup allows Tome to
correctly generate the  repeated opening quotation mark for each paragraph. For instance, if I  were to say: 
"{There is a lot of confusion about whether or not to close  quotations when breaking paragraphs. The
standard practice is to leave  the quote open at the end of the pargraph, but to  !{re-open}!  it at the  
beginning of each quoted paragraph.  

A lot of people---especially contemporary writers with lots of computer  experience---don't like this, perhaps
because the quotes are then  !{unbalanced}!  and  !{unmatched}!.  

However, the reason for not closing the quote at the end of each  paragraph is because this normally signals
the end of a person speaking, so if the next paragraph is also quoted, it should indicate that another person
is speaking.

You could also just leave the quotation open for the entire duration,  but it's probably hard to keep track
of the fact that it is quoted text  if the quote includes many paragraph breaks. The opening quote at the  
beginning of each paragraph is a reminder.}"  You can see how this is  rendered by Tome.  

If you want to include a long quotation from an external source, you can  also use the !{block quote}! markup,
like this one from Hans Andersen's  _{The Little  Mermaid}_:  
|{
    Far out in the wide sea,---where the water is blue as the loveliest  cornflower, and clear as the purest
    crystal, where it is so  deep that very, very many church-towers must be heaped one upon  another in
    order to reach from the lowest depth to the surface  above,---dwell the Mer-people.  

    Now you must not imagine that there is nothing but sand below  the water: no, indeed, far from it! Trees
    and plants of wondrous  beauty grow there, whose stems and leaves are so light, that  they are waved to
    and fro by the slightest motion of the water,  almost as if they were living beings. Fishes, great and
    small,  glide in and out among the branches, just as birds fly about  among our trees.  

    Where the water is deepest stands the palace of the Mer-king. The  walls of this palace are of coral, and
    the high, pointed windows  are of amber; the roof, however, is composed of mussel-shells,  which, as the
    billows pass over them, are continually opening  and shutting. This looks exceedingly pretty, especially
    as each  of these mussel-shells contains a number of bright, glittering  pearls, one only of which would
    be the most costly ornament in  the diadem of a king in the upper world.  
}|

Block quotes are usually rendered indented on both sides compared to the  main text. Ordinary quotes are
usually used for short quotes or for  dialog (i.e., when a character of the story is speaking), but block  
quotes are typically used for long external quotes (i.e., not from an  internal character).  

Another block markup is for !{footnotes/endnotes}!^{
    A note is a bit of extra information that doesn't fit into the main text  but which the reader may find
    useful. It is normally referenced from the  main text with a little superscript number of sybmol.  

    Tome notes may contain multiple paragraphs and any other tome markup,  such as  "{quotes}",  /{italics}/,
    *{bold}*,  _{underline}_,  !{emphasis}!, etc.  They can even contain additional notes^{
        See? This is a note within a  note.
    }^
}^. Tome does not distinguish between footnotes and endnotes because  that depends on where the output writer
decides to put the notes. In many cases,  the output document will not have any specific page breaks (for  instance,
in an HTML document), so strict footnotes are not possible.  

The final type of block markup is !{preformatted text}!. Preformatted text  is not parsed for additional markup
and is rendered with whitespace  intact. For instance, you can use a preformatted text block for ASCII  art: 

=                 .-~~~~~~~~~-._       _.-~~~~~~~~~-.
=             __.'              ~.   .~              `.__
=           .'//                  \./                  \\`.
=         .'//                     |                     \\`.
=       .'// .-~"""""""~~~~-._     |     _,-~~~~"""""""~-. \\`.
=     .'//.-"                 `-.  |  .-'                 "-.\\`.
=   .'//______.============-..   \ | /   ..-============.______\\`.
= .'______________________________\|/______________________________`.


If this wasn't in a preformatted block, then all of that whitespace  (including linebreaks) would typically
be condensed and the image would  look like this:  
|{
                  .-~~~~~~~~~-._       _.-~~~~~~~~~-.
              __.'              ~.   .~              `.__
            .'//                  \./                  \\`.
          .'//                     |                     \\`.
        .'// .-~"""""""~~~~-._     |     _,-~~~~"""""""~-. \\`.
      .'//.-"                 `-.  |  .-'                 "-.\\`.
    .'//______.============-..   \ | /   ..-============.______\\`.
  .'______________________________\|/______________________________`.

}|


:Chapter: Tome Document Structure

The general structure of a Tome document is hierarchical: document, part, book,  chapter, scene, paragraph.
The document is the tome document itself,  there is always exactly one of these. Within this document, there
may be  multiple parts, which may in turn contain multiple book, in turn  multiple chapters, multiple scenes,
and multiple paragraphs. Parts, books,  and chapters can all be titled, scenes and paragraphs may not.  

Parts and books are not currently being handled by any of the output  writers: you can include them in your
document without any problems, but  there is no indication of them in the output, it will just look like a  
flat series of chapter. This will be an upcoming feature, hopefully very soon.

***

A !{scene change}! like the one preceeding this paragraph is typically used  to shift perspective or setting  
abruptly. In a more general sense, a scene can simply be regarded as a  subchapter, used to divide up the
content into blocks that are somewhat  unrelated, but not so much that they deserve their own chapter.  




:Chapter: Additional Tips, Tricks, and Notes

While tome is deliberately intended to be simple and not very flexible,  this is obviously also a
limitation. If you want to do a lot of  customization and have a lot of control over your document, tome may
not  be the correct choice for you. Something like Tex is a very  powerful tool which may be better suited to
you. The downside of these  types of powertools is that it is often harder to simply write when  using them. 


Another option, if you want to use Tome but want to do a lot of tweaking  of the output, is to use patches.
This is a slightly sophisticated  approach, but if you're comfortable with computers, you should be able  to
do it reasonably well. The idea is to write your simple tome document  as usual, generate the output, and
then manually edit the output to make  it exactly how you want it. Then, use a diff tool to compare your  
customized output to the original output and generate a set of patches  describing the changes.  

After doing some more editing of your tome document, you rerun the output  writer and your customizations are
overwritten: simply apply your  patches to the new output to add your customizations back in.  


:Part: Tutorial

:Chapter: Getting Started with Tome

In this part of the document, we will go through a brief tutorial so you can learn how to actually use tome.
To do so, we will write a simple tome document and "{public}" it to various output formats.

Tome documents are written as plain text files. You can use whatever plaintext editor you wish, this author
prefers using the very excellent !{Vim}! text editor. Other popular choices are GNU Emacs, Notepad++, or
simply Windows Notepad.

In this tutorial, we will be writing a Tome document using the !{tome-flow}! syntax, which we will 
refer to as "{tome syntax}", "{tome markup}", or simply "{tome}"^{
    There are other varities of tome markup that you can use, as described earlier in this document, but
    tome-flow is the easiest to use with generic editors.
}^. The conventional file extension for documents written in tome-flow is "{.tome}", but you can use whatever
extension you want.

A quick overview of tome-flow: most of what you write will just be ordinary text without any special
considerations. However, lines beginning with certain characters have special meaning in tome-flow^{
    Leading whitespace at the beginning of a line is ignored: it is the first non-whitespace character of the
    line that indicates the purpose of the line.
}^. The most important special character is the colon ('{:}'), any line beginning with a colon is treated as a
command. Commands are used for things like specifying the title or author of a document or part of a document.
There is a small set of commands currently defined, if you use any other commands, it will produce an error in
the tome processor.

So let's begin writing our Tome document. The first thing it needs is a title, so write this in your document:

=
=:Title: My First Tome Document
=

Pretty easy, right? The colon character ('{:}') at the beginning of the line indicates that it is a command,
and the command in this case is "{Title}". All commands in tome-flow are case-insensitive, meaning you can
capitalize the command however you like. Commands are terminated by any whitespace character and everything
after that is processed according to the command.

Notice that there is a second colon at the end of the "{Title}" command: this is not strictly requird, but you
may find it helpful for making command lines stand out more, and making it easier to isolate the command from
the rest of the line. In fact, all colon characters at the beginning and end of a command are stripped off and
ignored, so you can use as many colons before or after as you want, it doesn't change the meaning of the
command. The important things are that the line must begin with a colon to be designated a command line, and
the command is terminated by whitespace.

Now that we have a bit of a handle on commands, lets try another to add an author to our document:

=
=:Title: My First Tome Document
=:Author: Your Name
=

Couldn't be easier. You can add multiple authors and multiple titles to a document by reusing the commands.
For instance:

=
=:Title: My First Tome Document
=   :Title: In Which we Learn how to use Tome Markup and Tools
=
=:Author: Your Name
=:Author: My Name
=:Author: Someone E. Name
=

Any additional titles are generally treated as subtitles, but it really just depends on the output writer.
You'll notice I indented the second "{Title}" command a bit: this is entirely unecessary, I just did it to
emphasize (for myself, that is) that this is a subtitle. Leading whitespace at the beginning of a line is
always ignored, the line has the exact same effect on the document whether it is indented or not.

Similarly, the blank line between the titles and the authors is meaningless as well: completely blank lines
are only relevenat following ordinary text (meaning the content of your story) in which case they indicate and
paragraph break, as we will see shortly.


Now, lets begin writing some content. The heirarchical structure of a tome document is: part > book >
chapter. Parts and Books are a way of organizing or dividing your document into larger sections. This isn't
exactly uncommon, but it's also not typical: the majority of novels and other non-reference books simply use a
"{flat}" structure of sequential chapters with no larger subdivisions. And, since none of the output writers
currently do anything with parts or books anyway, we'll skip straight to chapters.

So add a "{chapter}" command to your document, so that it looks like this:

=
=:Title: My First Tome Document
=   :Title: In Which we Learn how to use Tome Markup and Tools
=
=:Author: Your Name
=:Author: My Name
=:Author: Someone E. Name
=
=
=:Chapter: Getting to know Tome
=

The rest of the line after a "{chapter}" command is simply the main title of the chapter. You can leave it
blank if you don't want a title (e.g., just numbered chapters), and you can add additional "{title}" commands
!{below}! the chapter to specify subtitles for the chapter. For instance:

=
=:Chapter: Getting to know Tome
=   :Title: Some Basic Markup
=

Once again, the indent on the command line doesn't matter, I just use that to make it more clear (to myself)
that it's a subtitle.

Ok; start writing. Seriously, just start writing. Try something like this:

=
=:Chapter: Getting to know Tome
=   :Title: Some Basic Markup
=
=This is my very first tome document. So far I've
=written a few commands to add titles and authors
=and subtitles and chapters (with subtitles),
=and now I'm finally writing some actual content.
=

That's what most of your time will be spent doing hopefully, just writing your text. There's nothing special
you have to do indicate ordinary text: if the line doesn't begin with one of the few special characters, then
it's just treated as ordinary text.

Ordinary text is handled as though it's (get this)...ordinary text. Which isn't to say that what you write is
what you get, but that what you get is (hopefully) what you intended when you wrote it. For instance, whitespace
is generally all treated the same, which means simgle spaces, multiple spaces, even linebreaks are all just
used to separate words and the output writer will generally reflow your words however is appropriate for the
output.

So now that we've started writing, let's continue writing. We'll start a new paragraph, which is done
simply by inserting a blank line after your previous paragraph:

=
=:Chapter: Getting to know Tome
=   :Title: Some Basic Markup
=
=This is my very first tome document. So far I've
=written a few commands to add titles and authors
=and subtitles and chapters (with subtitles),
=and now I'm finally writing some actual content.
=
=Starting a new paragraph is really easy in tome.
=I just whack the return key a few times and start
=typing again!
=

The exact number of blank lines between paragraphs is unimportant, as long as there is at least 1 blank
line. Feel free to use more if it helps you organize your text better.



:Chapter: Generating Output

Now, presumably, you'd like to know what this is all going to look like at the end. That's where the tome
tools come in.

The Tome package comes with a command line program, called simply "{tome}". In it's most basic use, it's
really easy: specify the path to the input file, and the path to the output file, and you're good to go.

So let's start by generating a text output for our document. The !{text format}! option in tome generates a
plaintext output of your document. I know what you're thinking: /{I wrote it in plaintext, why would I want to
output it in plaintext?}/ Because the plaintext output is nicely formatted, with reflowed and fully justified
text, centered and underlined titles, proper endnotes, and more. Granted, this is probably the least exciting output format
supported by tome, but it's also the most widely supported: anyone can open a plaintext file.

We'll get to more interesting formats in a minute, but let's just start with the simplest. Save your tome
document that we've been writing to something like "{first_document.tome}", and open a command prompt in the
same directory. Enter the following command:
=
=tome first_document.tome first_document.txt
=

That's it^{
    Of course, if you named your document something other than "{first_document.tome}", you'll need
    to adjust the first argument to the tome command accordingly.
}^. Look at the current directory and you should see your output file "{first_document.txt}". Open that up and
you should see your document, nicely formatted in plain text.

The command is pretty simple, but just to be clear: the first argument ("{first_document.tome}" in this case)
specifies the input file, which is the tome document you've written; the second argument is specifies where
you would like the output file to be written.

Actually, the second argument does a little more than just specify where: it also specifes what !{type}! of
output to generate. It does this implicitely from the file extension you specify for the output. We specified
"{.txt}" as the extension, which instructs the tool to generate plaintext output. You can also explicitely
specify the output format using the "{--format}" option. This is useful if you want to use an extension that
tome doesn't recognize for your desired format. For instance:
=
=tome --format txt first_document.tome first_document.plaintext
=

Similarly, the extension on the first argument (the input file) tells tome what syntax your document is in so
it know how to read it. The "{.tome}" extension corresponds to the tome-flow syntax we're using. Just like
with the output format, if your extension doesn't match the syntax of the input file, you can use the
"{--syntax}" option to specify it. For instance, if you saved your document as "{first_document.tme}" instead,
you could use this command:
=
=tome --syntax flow first_document.tme first_document.txt
=

The "{--syntax flow}" option explicitely states that your input document uses the tome-flow syntax. Of course,
you can combine both the "{--syntax}" and "{--format}" options.

As mentioned, plaintext is not a very interesting output format^{
    Unless you're really into the mechanics of laying out fixed-width text, then the plaintext output format
    is quite interesting.
}^, so lets generate an !{EPUB output}! document instead. But there's two small additions you need to make to
your document for EPUB: you need to specify the !{language}! and a !{unique identifier}! for your document.
These are part of the EPUB standard, which you can reference for more details, but essentially the unique
identifier (also called a "{uid}") is something that uniquely specifies this particular document. The exact
format of the uid is not specified by the standard, but it is common to just use a URL that you have control
over (for instance, a URL on your website).

To include this information in your document, use the "{meta}" tome command. This command can be used to store
arbitrary information with your document where each piece of information is associated with a specific key
that you name in the command. The EPUB output writer looks for meta values named "{lang}" and "{uid}".

To make your document ready for EPUB, add these lines to your document, somewhere before the first chapter:

=
=:Meta: lang en-US
=:Meta: uid http://www.example.com/myEpub
=

With these meta lines in your document, generating the EPUB is easy, just change the "{.txt}"
extension on your second command argument to "{.epub}" (alternatively, specify the "{--format epub}" option),
and let it rip:
=
=tome first_document.tome first_document.epub
=

Of course, you'll need something to read the EPUB with, which is why we didn't start with that. Some common
(and free) EPUB reading software includes Adobe Digital Editions, Nook for PC, and Calibre. Get one of those
or another EPUB reader, and use it to open your output file to take a gander at what it looks like.

A third output format is !{latex}!, which is specified either with the extension "{.tex}" or "{.latex}", or
with the "{--format latex}" option. If you're not familiar with latex, it's a very powerful programming and
markup language for writing documents, especially complex documents with specific layout requirements,
mathematical formulas, tables, figures, etc. The latex output format for tome generates a single latex source
file, which probably isn't what you actually want to use to read your document. Instead, use a standard latex
tool chain to produce a DVI, Postscript, or PDF document from the generated latex file.


:Chapter: Finally, some Markup!

Ok, you know the basics, you've produced an output document from your tome input document, but we haven't even
touched any markup yet. So let's get to it.

There are really only a handful markups available from tome, which is very deliberate (check out the first
part of this document for the motivation and philosophy behind tome). That's means it should be really easy to
learn. And no better way to learn then by doing. Open up your tome document against and add the following
after the end of the last paragraph:

=
=:Chapter: A New Chapter to Learn Markup
=
=Tome markup is really simple: you can do
=*{bold}*, /{italics}/, _{underline}_, and
=generic !{emphasis}!.
=

And that's it. If you want to see what it looks like, use the tome command like we learned to generate an
output document (plaintext output format is not the best to see markup in action, I recommend EPUB, or latex
if you have a latex tool chain).

Notice that all markup is wrapped in curly braces: '{~{}' and '{~}}'. This may seem strange to you at first
(especially if you don't come from a programming background), but the curly braces make the markup
unambiguous, which is a must for uninterrupted writing. the curly braces also help setup marked-up text apart
a little while you're writing. In the future, tome will likely support as optional input syntaxes a subset of
some more familiar markups, like reST, Markdown, and Creole.

The general construction of all markup in tome-flow is an opening character followed by an opening curly
brace, then the content to be marked up, and then a closing brace and the closing character. The opening
character specifies what type of mark up it is, and should be repeated in the closing character. The four
markups shown in the example above are the only "{inline}" markup elements available in tome.


:Chapter: Escaping Character with Tilde

If you need to include an opening or closing curly brace in your actual text, you can escape it by preceeding
it with a tilde character '{~~}'. In fact, a tilde escapes any character that immediately follows it, so that
the following character will always just be treated as text. Thus if you want to put an actual tilde into your
content, you simply enter two tildes into your tome input document: "{~~~~}". You can also use the tilde
escape if you want to start a line of text with a reserved character which would otherwise indicate a special
line (such as a colon character which would normally indicate command lines). To see how to use the tilde, add
the following to your document:

=
=~:This is not a command line, it just starts
=with a colon for some reason. If I want to
=include curly braces in my document, I escape
=them like ~{ and ~}. If I want to include a
=tilde, it looks like ~~.
=


:Chapter: Text Objects

Other than markup, another "{inline}" component of tome-flow is !{text objects}!. There are three text
objects in tome: !{em-dash}!, !{en-dash}!, and !{ellipsis}!. An em-dash is an extra long dash, typically used
to set off parenthetical content or to indicate that dialog has been cutoff or interrupted. An en-dash is
shorter than an em-dash but longer than a standard dash. It is often used to indicate a range of numbers or to
indicate a relationship or connection between two things. An ellipsis is a set of three dots which typically
indicates an omission of a segment of quoted text, a continuation, or an unfinished thought.

Add the following to your tome document to see how text objects are used:
=
=An em-dash is used for parenthetical
=information---extra information that may not be
=strictly neccessary, for isntance. An em-dash is
=written in tome-flow with three consecutive
=dashes.
=
=An en-dash is a bit shorter, it can be used for
=ranges like 1--10, or for relationships or
=connections, as in "{mother--daughter
=relationship}". A en-dash is writte in tome-flow
=with two consecutive dashes.
=
=An ellipsis can be used for...a number of things,
=such as...well, continuation, I guess. An ellipsis
=is written in tome-flow with three consecutive
=dots.


:Chapter: Block Markup

In addition to the inline markup, tome also provides a small set of "{block}" markups. The block
markups include !{quoting}!, !{block quoting}!, and !{notes}!.

Quoting markup includes
both single- and double- quotes and should be used anytime you want to use quotations in your document. There
are several benefits to using the quoting markup instead of just typing a quote character, as described in the
first part of this document. Block quoting is a common markup in many languages, it is generally used to
include large external quotations or excerpts. It is often displayed indented relative to the main text.

Note markup is how you include footnotes or endnotes in your document. Tome doesn't differentiate between the
two, it just depends on how the output writer places them.

To see how to use block markup in tome-flow, add the following to your tome document, and rerun the tome
command to see how it looks in the output:

=
=This new paragraph is all about so-called "{block
=markup}". That, for instance, was a double-quoted
=markup. You would use that for things like
=dialog, for instance: "{When last we met, I first
=saw her eyes through the thick fog and heard her
=call out '{Jeffery! Help me! I've got my hair
=caught in the mechanism again!}'.
=
=I wanted to run to her and help her, only my bus
=was coming and I had already waited so long in
=the cold.}"
=
=Notice we used a '{single-quote}' markup in there as
=well, and that we can include paragraph breaks
=inside quoted content: tome will correctly handle
=inserting the appropriate quotation marks at the
=beginning of each new paragraph.
=
=If I wanted to include a long excerpt from
=another source, I could also use the block quote
=markup which looks like this:
=
=|{Here is a long excerpt from another source that I
=want to include in my document.
=
=It has multiple paragraphs and that's fine.
=
=Tome can handle multiple paragraphs inside block
=quotes, just like it can inside single- and
=double- quotes.}|
=
=Last of all, I learned how to use notes in
=tome^{This is a !{note}!, which will be referenced
=from where it started in the main text. The
=actual "{content}" of the note (what I'm writing
=right now) will show up somewhere else.
=
=Notice that notes can include paragraph breaks
=and any other markup.
=}^.
=

:Chapter: Scene Changes

We already mentioned the hierarchical structure of a tome document (part > book > chapter). There's actually a
neither level below chapter: !{scene}!. Scenes are often used within stories to abruptly switch perspective
or setting within a chapter, or more generally as a generic subchapter construct. You'll often see a scene
change indicates by a short horizontal line, three stars centered in the page, or simply an extra large
vertical space between paragraphs. In tome, scene changes are written by three consecutive stars at the end of
the line.

Add this to your document to see how scenes are separated in tome-flow:

=
=This is the last paragraph of a scene.
=
=***
=
=This is a new scene, because of those three
=stars. In this new scene, the story might be in
=a different location or it might even be a
=different narrator, for instance, but it is still
=in the same chapter.
=


:Chapter: Preformatted Text

The final component to writing tome is "{preformatted text}". Preformatted text is not parsed for any other
markup, so it will appear "{as is}" in the output. This includes whitespace characters like spaces and
linebreaks, so you can use it for things like ASCII art or ASCII tables.

To mark a line of text as preformatted text, the first (non-whitespace) character of the line should be an
equals sign '{=}'. The entire line will then be treated as preformatted text, including the linebreak at the
end. A line of preformatted text following ordinary text causes a paragraph break, but all preformatted lines
that follow it are grouped together into a single preformatted paragraph. Switching back to ordinary text
(including completely blank lines) once again starts a new paragraph.

Be careful with preformatted text since it will not be reflowed in the output. In otherwords, if you have a
relly long line of preformatted text, it might run into your margin, or even right off the page in your output
document. Also bare in mind that things like EPUB don't have a fixed page size so even if it looks ok to you,
it might not to someone with a smaller page size (or larger font).

Add the following to your document and build your output file to see how preformatted text works:

=
==                 .-~~~~~~~~~-._       _.-~~~~~~~~~-.
==             __.'              ~.   .~              `.__
==           .'//                  \./                  \\`.
==         .'//                     |                     \\`.
==       .'// .-~"""""""~~~~-._     |     _,-~~~~"""""""~-. \\`.
==     .'//.-"                 `-.  |  .-'                 "-.\\`.
==   .'//______.============-..   \ | /   ..-============.______\\`.
== .'______________________________\|/______________________________`.
=