now let's take another step forward

[bowerbird]

# now let's take another step forward


now that we've got something straightforward
put into place, let's see if we can stretch a bit.

first, though, let's do the error-correction thing.





## table of contents


autotoc





## bowerbird made a mistake, and apologizes


gerald said:

> There's no dependency on Ruby or Ruby on Rails.
> It's a static (server-less) single HTML page (w/ JS and CSS)

thanks for correcting my error in that regard.

***

gerald said:

> I guess it's my error -- will remove the
> real world case study (that mentions Ruby on Rails
> and might, thus, lead you to think you need Ruby

no, it was clearly my error, not yours, and i apologize.

indeed, if i unpack the .zip file containing your project,
and mount the entire thing, it works, as is seen here:

> http://zenmagiclove.com/misc/sssss/markdown-note-folder/note.html

whether you want to change your documentation or not
is a separate matter, and that decision will be up to you.

still, my mistake was my mistake.





## but something still misses the mark


however, something still misses the mark here, at least
in terms of my overall goal, so let's see if i can explain it.

the first thing i did was to summon up your demo page,
which, as you just announced, has now moved to here:

> http://writekit.github.io/markdown.note/note.html

then i saved the "page source" -- i.e., just the .html file.

but when i then loaded that saved file into the browser,
it didn't run. i had seen something about ruby-on-rails,
so i assumed -- incorrectly -- that that was the reason.
and i apologize for jumping to that incorrect conclusion.

but once you told me my error, i went back and looked,
and the .html file (which i'd saved) failed for me because
links pointing to the .css and .javascript files are relative.
so it wasn't ruby/rails that was absent, it was those files.

once i changed those links, it did work. you can now find
a version of the file as i have reworked it at this location:

> http://zenmagiclove.com/misc/sssss/MarkdownNoteNot-v3.html

i have copied this post into that file, as another example.

the file validates, but the browser says this file is missing:

> http://writekit.github.io/markdown.note/js/lib3rd/jquery-2.0.1.min.map

that's also a message the browser gives on your example.
something to do with the minimized jquery file, but it seems
to have no real effect on the successful running of the code,
so we can just ignore that. as long as it works, we're good.

i also do not grok textarea-in-a-table markup, so i wrote
a javascript routine that resizes the textareas and display.
(it uses a timer because it was quick-and-dirty, but that
is an operation that should be cued to open and resizing.)

so this file now works in a fashion near _what_ _i_ _want._
(and i hasten to add that i am not necessarily advocating
other people should want what i want; decide for yourself,
and decide differently for different needs at different times.)

that is, if i download this .html file -- solely by itself -- and
load it back in the browser, it runs and works successfully.
so that's very good, and gives me part of what i'm seeking.

however, it is still loading a bunch of files from the internet.
and it won't work correctly without downloading those files.
meaing an offline-only work-flow will neither work nor flow.

if i were to copy those .css and .js files to my own machine,
and were to restore the pointers so they were again relative,
i could run my .html file without having any internet access.
so that's even better. but now we are asking for a bit more,
compared to the simple saving of an .html file in the browser.

what i really want the most is to download just the .html file,
and have it work correctly, without requiring any other files.
which means bundling all those other files into the .html file.
that is certainly do-able, but it weighs in at 190k with jquery.
in an age of 1meg webpages, that's relatively lean, yes, but
it would be even better if we can take it down in size a little.

it is, however, a very cool feature that you have brought to
the table, with this ability to easily toggle many converters.
i can see that being extremely useful when one is trying to
track the nature of inconsistencies between different flavors.

(i did get "uri too big" error-messages from heroku when i
tried to use some of the ruby converters, i don't know why.)

finally, and i'm willing to concede that this might just be me,
but i don't like having to live in somebody else's .css world.
so when we are customizing and personalizing an interface,
the less .css a project brings as baggage, the better i like it,
and i'm never really happy until all of that baggage is gone.
not that you used a lot of .css, gerald, but there was some,
and even that wee bit was enough to make customizing hard,
even when all i wanted was to make the textarea full-screen.

at any rate, i hope you feel i have given your project its due.
and though i'm sure it'll serve the interests of many people,
it still comes up a tad short in terms of what i'm looking for.

your set-up _is_ simple. and i'm sure it will be useful to many.

but for me, it's just not quite simple enough.

(but i look forward to your future efforts in that direction.)





## i have a slightly different objective


in regard to what i'm looking for, my objective is one that's
much closer to that of strapdown, where light-markup text
can be placed in an .html file which is then mounted _as-is_
and gets converted just-in-time client-side for display there.

this kind of set-up is _simple_ in the sense that it requires
absolutely zero expertise, with no external dependencies.

(strapdown, of course, is -- in and of itself -- a dependency.
and yes, you can bundle strapdown.js into your .html file,
but strapdown has bootstrap dependencies of some type,
so once again you are living inside somebody else's .css.)

but an .html file which bundles its own .css, and .js inside,
with light-markup text that's converted on the client-side,
is the kind of file that truly has no external dependencies,

moreover, this kind of tech has a _huge_ virality potential.

what i mean by that is this: if person "a" mounts such an
independent light-markup file, person "b" who receives it
now has everything s/he needs to propagate it downline.
"b" simply edits the light-markup text inside the .html file,
and mounts the new file. now we have two exemplars of
the tech out doing work. and all it took to spread this thing
was the dirt-simple action of downloading an .html file, or,
in other words, clicking a link.

and yeah, i introduced this thread as "side-by-side" code,
but that's just the first of several wrinkles in these sheets.

this primitive stuff i showed is what i was doing years ago.
but i have recently become displeased with the difficulty of
the underlying code in most side-by-side set-ups which
causes undue difficulties in repurposing and customizing,
so i wanted to make sure that average developers realize
it's possible for them to code that without any externalities.
you don't need anything but a few buttons and a few fields.

but there's been lots more on my research bench since then.
i'll show a little bit of that next, and then step back and see
whether people here are interested. if not, i will step away.





## more choices and different objectives


gerald said:

> Keep it up. Always good to have more choices. Cheers.

you too. different choices and different objectives are good.





## now for those additional steps


now let's consider the additional steps i mentioned up top,
in view of the wider perspective which i have just shared.





### we'll wanna start with the preview-mode


we're writing an editing interface, to be sure, but often
we'll want to start with the preview-mode, and only when
we are sufficiently motivated will we switch to edit-mode.

also, in terms of the tactic i was talking about just now,
where we want our .html file to be free of dependencies,
so it can become viral whenever somebody surfs to it,
we'll want the initial presentation to be "display" mode.

so we'll change the default starting-mode to "preview."





### ditch the "display" and "source" buttons


the toggle button serves us adequately, so we can probably
dispense with the dedicated "display" and "source" buttons.
and, to clear the clutter, we'll eliminate the "npy" ones too.

later we're gonna wanna spruce up the remaining buttons
as well, but for now we'll just leave them the way they are.
well, maybe make 'em a wee bit smaller.





### auto-generating the table of contents


we don't want to have to hard-code the table of contents,
in the way that i was doing it for the previous examples.
we want one to be automatically generated for us, so we
don't have to specify links manually (which invites error).

that's easy enough. we'll just write javascript code to do it.

so i did that.

put "autotoc" as the only text under the "table of contents"
header, and everything will be done for you automagically.

also, now that we know the table of contents is going to be
linked automatically, and that section-headers link back to it,
we can turn off that pesky-and-ugly underlining on the links.





## in summary

i've copied this post as an example in the newest demo:

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

first, note that we started with the display-side in full-screen.

also notice that we've cleared away the unnecessary buttons.

click the "f/p" button at lower-right to expose the editing side.

note that the second section -- the table of contents -- has
only "autotoc", but a fully-linked table of contents is shown.
this is in the spirit of light-markup, where work that can be
done automatically by the machine is offloaded from humans,
because helping us is something computers are very good at.