topnpynpy # 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 ## table of contents <a href="#simple-sample-side-by-side-setup">simple sample side-by-side setup</a> <a href="#table-of-contents">table of contents</a> <a href="#the-basic-set-up">the basic set-up</a> <a href="#customizing-the-experience">customizing the experience</a> <a href="#where-to-save">where to save</a> <a href="#which-converter-to-use">which converter to use</a> <a href="#when-to-save-and-convert">when to save and convert</a> <a href="#search-functionality">search functionality</a> <a href="#making-the-sides-sync">making the sides sync</a> <a href="#providing-a-table-of-contents">providing a table of contents</a> <a href="#ingestion-of-graphics">ingestion of graphics</a> <a href="#other-statistics-and-options">other statistics and options</a> <a href="#summary">summary</a> ## 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 tandem 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.
fullnpynpy

displaysourcetoggle npynpyfull