simple sample side-by-side setup

[bowerbird]

# simple sample side-by-side setup

there are so many light-markup editing environments
out there these days that it takes a good deal of time
to evaluate which one might be right for you.
and even after you've done that, you might
wish some of its features were slightly different.

the good news is that it's relatively easy to set up
a side-by-side .html page. from there, you can
customize the environment to your own preferences.

here's some sample code that creates such a split-screen set-up:

> http://zenmagiclove.com/misc/sssss/side-by-side.html

## the basic set-up

the left side is for editing the text,
and the right side is for displaying the .html.
as you would expect, as you edit,
the display on the right-side gets updated.

this is a simple javascript setup. it uses jquery at present;
you could make it independent, but the pageload burden
posed by jquery isn't really all that significant.

you'll notice that there are buttons along the top and bottom
of the page, which you can use for any functionality you might
want to incorporate. some of them are currently just
placeholders, labelled "npy", short for "not programmed yet".

at the top left is a button labeled "top". clicking this button
causes both the edit and display fields to scroll to the top.
you might or might not think that's handy enough that
you want to keep it.

on the right side, the "preview" side, the 3 buttons at the top
are labeled "display", "source", and "toggle".

* the "display" button shows the .html as it would appear on the page.

* the "source" button shows the .html in its "view source" mode.
(note that i have hacked the source a bit to make it more readable.)

* the "toggle" button toggles between the "display" and "source" views.

at the bottom left, on the text-editing side, is a button labeled 
"full";
clicking it will cause the edit-field to grow to full-screen; at that 
time,
the button's caption will change to "split". clicking it then will cause
the split-screen view to return.

at the bottom right is another button labeled "full",
which causes the .html side to go to full-screen,
when it too has a corresponding "split" mode.

this code creates a design that works well on an ipad,
and as good as could be expected even on an iphone.
but i claim absolutely no expertise at .html or .css, so i
would not be surprised in the slightest if it can be improved,
and i welcome all suggestions.

## customizing the experience

there are a myriad of features that you can add to such
an "editor", of course. and that's why we're doing this.
so let's explore some of the possibilities.

### where to save

the first necessity is the ability to save your updated text.
in various iterations of this model, i have saved text to a website
using a helper-app on the server (which is quite simple), and i have
saved to dropbox using their canned routines (which is not difficult).
if there is interest, i'd be willing to share those routines.

you can also save to local storage, just as long as you understand
the ramifications of doing that, the main one being that your text
is then available solely to that browser on that machine.

javascript will sooner or later be able to save to the file-system
proper, but don't hold your breath for that.

### which converter to use

another big question is which conversion routine you want to use.
a javascript routine, sitting right in the webpage, is going to be
the fastest solution. that's what i'm using here.

you can also send your input-text to an online converter,
and then display the resultant-html when you get it back.
not quite so fast, but not intolerably slow either, especially
if your text isn't huge and your connection is fast enough.
but not nearly as snappy as the javascript route.

the main advantages of a javascript routine is that it can be
bundled right inside the page, it's fast, and -- moreover --
it's customizable. just as you are customizing your "editor",
you can also customize your converter, so it does whatever you
want it to do. no need for pre-processing, or post-processing,
or living with somebody else's notion of "good markup".
when if you have a project which has some "special needs",
you can rewrite the converter to accomodate them. in the end,
you might well find this is the very best reason for choosing a
javascript converter. i know i won't use anything else these days.
i don't want to be stuck inside somebody else's box.

you'll find that that sample set-up actually bundles in two converters.
the first is the "marked" converter from chjj, the premiere javascript
conversion routine. the second is the javascript routine john macfarlane
just released. the "gwhichconverter" global controls which routine is 
used.

> http://github.com/chjj/marked
> http://github.com/jgm/stmd

this demonstrates another benefit of javascript converters, that you can
bundle in several of them, and switch between them on-the-fly if you 
like.

### when to save and convert

the next questions involve when to save and convert. obviously,
the answer to these questions depend on where you are saving,
and how you are doing your conversions.

also at issue here is personal choice. perhaps you're the kind of person
who likes to have stuff saved automatically. or maybe instead you prefer
to specify your saves manually. or maybe you want everything "backed up"
automatically, so you can retrieve it in case of failure, but you want 
the
"official" saves to be triggered only when you explicitly specify.
whatever your choice, the choice is yours.

likewise with conversions. some people want to have the text
re-converted on every keypress, even if that means that the system
is slow to accept their keystrokes because it's busy converting.
other people want a more placid display that only updates
a few seconds after they've stopped typing that run-on sentence.
and sometimes you want it one way for one document, and
another way for another. i have routines that can accomodate all
of these choices, if people are interested. (but, just so you know, the
"every keypress" choice is not a good one, because many keypresses
-- such as cursor-keys -- don't actually change the text. instead,
use an event that fires only when the text changes.)

### search functionality

although you can always use the browser's "find" functionality,
sometimes you want something more sophisticated,
or controlled, or powerful, or extensive. that's something
you can code to your own preferences.

one thing i can tell you is that you should be aware that this
split-screen set-up gives a lot of power to your search routines,
because you can pull the text _either_ from the edit-field
_or_ from the .html "preview" side. sometimes something that
would be problematic if you were only able to search one of
those sources can be solved quite easily by using the other source.
just so you know.

### making the sides sync

one functionality that a lot of side-by-side editors don't do
quite so well is to sync the two sides.

this is a rather complicated matter, which i won't bother to
discuss unless other people want to, but i will say that there
_are_ times where you do not _want_ the sides to sync, but
rather want to allow them to float independently. so the
complicated matter becomes even more complicated.

before i leave this sub-topic, though, i must say that
if a system's converter returns the "preview" to the top
of the document instead of returning it to where it was
when the conversion was called, that system is broken.
likewise, the edit-field must be returned to the cursor-location.
do not tolerate shoddy systems in this regard.

### providing a table of contents

one handy feature is to offer an automatically-generated
table of contents so you can automatically jump to various sections.
it's not hard to do, and it is surprisingly useful, especially with
long-form documents, more than you might imagine.

indeed, my systems also link section-headers _back_ to
the table of contents, and offer previous-section and next-section
links on every header. navigation is one of the most important
features of long-form electronic-documents.

note that the table of contents at the top of this document was
_not_ generated automatically. it was specified, as .html code,
using knowledge of the way the chjj converter auto-generates
the id for a header. note that if you switch to the jgm converter,
the default setting does not auto-generate any header id, so
the table of contents as it exists now will not link automatically.
one more wrinkle: if you use some other converter, you must
ensure that it generates header ids the same way, or -- again --
the table of contents .html code will have to be edited slightly.

### ingestion of graphics

one of the best reasons -- and often overlooked -- for the display-side
in the side-by-side set-up is that it shows you the graphics, which can
be tremendously informative while you are in the process of writing.

to this end, if your editor can ingest graphics, storing them in their
proper place so that it can pull them into the document, you will soon
find that that is extremely nifty.

### other statistics and options

there are a number of other statistics that can be offered, such as
word-count, character-count, readability-scores, and lots of others.
whatever you can code, you can have, if you want it or need it.

in addition, there are plenty of other options that you can specify.
some of them will be included in the converter-routine you choose.
others you might have to code yourself. to get a truckload of ideas
about the things you can include, look at brett terpstra's "marked"
-- a previewer that works in tandom with your current text-editor --
and fletcher penny's "multimarkdown composer". the range of options
is remarkable considering that light-markup is supposed to be "simple".

> http://marked2app.com
> http://multimarkdown.com

### summary

i started off by saying that it's "easy" to set up your own system.
and then i threw a bag full of decision-forks at you, so at this point
in time, it might not seem that "easy" after all. but believe me, all
those decisions will be easy for you to make (because you know
how you like to work), and coding them won't be that hard either
if you have even the most rudimentary javascript skills. (mine are
quite crude, and i manage.) so take a shot at it. you will be
rewarded when you find yourself using an editor that works exactly
like you want it to work, so your writing starts to flow as a result.

if you have any questions or feedback, feel free to fire them at me.