Documentation updated to revision 1.15

ab · 2011-08-10 18:47:10

I redesigned the framework documentation - see http://synopse.info/fossil/wiki?name=Downloads
The general organization of the SAD document (which is the one to be read in all cases) has been refreshed, and is now separated in smaller chapters.

The new official name has been changed into "Synopse SQLite3/mORMot framework"...

Why is this framework named mORMot?
- Because its initial identifier was "Synopse SQLite3 database framework", which may induce a SQLite3-only library, whereas the framework is now able to connect to any database engine;
- Because we like mountains, and those large ground rodents;
- Because marmots do hibernate, just like our precious objects;
- Because even if they eat greens, they use to fight hard;
- Because it may be an acronym for "Manage Object Relational Mapping Over Tables", or whatever you may think of...

I added some general Architecture / Design diagrams, which may help you better understand and use the framework.
All those diagrams were made from plain text, using the GraphViz DOT engine included in SynProject: you write the logic, and the engine draw it for you.

I really like the following picture:

It's clear own the RESTful architecture makes the connection between client and server, and how ORM and SQLite3 are the core of the server side...
And it could help to understand all the Virtual Tables are included in this implementation, and how we now may access any remote database from the application.
"Un dessin vaut mieux qu'un long discours", as we use to say here, in France.

A lot more to discover in this new pdf files!

ab · 2012-02-18 17:26:01

I've updated the documentation to reflect the latest state of the 1.16 framework (not yet released).

I've also added a direct access link to the main useful document of all the pdf set, i.e. the Software Architecture Document (SAD) or mORMot.
You'll find in there general introduction to the framework architecture, tutorials, how-to, and a complete reference of every unit/class/function/method available.
More than 720 pages of pure documentation.

I change our SynProject tool to produce a more modern document layout.
I hope you'll enjoy this new fonts and styles.

Direct download of the SAD pdf:
http://synopse.info/files/pdf/Synopse%2 … 201.16.pdf

Eric · 2014-11-03 08:45:30

Any chance of a web-based, google-searchable HTML documentation?

PDF for technical docs is quite on the impractical side, especially with so many pages, and it's a bit sad to have all that information stay basically unreachable for everyday use.

ab · 2014-11-03 11:25:50

Yes, the first part (i.e. high level concepts and presentation) benefits of the PDF format, but the detailed per-unit documentation is not easy to work with.

I even consider creating a dynamic web site for the doc, using SQLite3 full text engine for the indexation.

That is, allowing to create a small project like our "30 - MVC Server" BLOG sample, but using our textual .pro file - see https://github.com/synopse/mORMot/blob/ … mework.pro - as input, creating a database containing all information, then ready to be explored via a local browser.

ab · 2014-11-05 13:44:29

@Eric
You could take a look at http://synopse.info/files/html/Synopse% … 01.18.html

This is a preliminary version of the HTML output of SynProject.
See http://synopse.info/fossil/info/6026c388a9

Not yet a multi-page web site, perhaps.
But sounds like a first good step, isn't it?

cheemeng · 2014-11-05 14:35:08

Nice! Well done Arnaud!

Eric · 2014-11-06 08:24:20

Well done, this is much more readable than PDF on any screen AFAICT, even for the first part.

PDF is good for displaying on dried-dead-tree-paste, but annoying for any other use

Multi-page HTML would be even better, at least at the top levels. It would be more friendly on mobile, and simpler to navigate, also you would get better search engine indexation & lookups. Ideally if you had a permanent page/url structure that would be even better (i.e not something based on fragile section or chapter numbers), as it could then be linked externally, support 3rd party annotations/comments (using any of the tools that already exist for that).

But don't let the above distract from the fact that it's a *huge* step forward IMHO, there was a lot of doc, but being PDF, it was kind of a "ghetto doc" if you take my meaning. This now looks "pro"

ab · 2014-11-06 08:38:53

Thanks for the feedback!

@Eric
Yes, multi page may be great, but I was a little tied to the current logic of SynProject document generation, for the links.
I may easily put the source code details in a separate set of pages: one page per unit.
I suppose it would let the main SAD be smaller.

Links are already possible: in fact, in the SynProject source file you can put some number in the title, and then link to it using @123@.
When converted to an URL, it will be fixed.
For instance:

:113 Installation

Is linked by /files/html/Synopse%20mORMot%20Framework%20SAD%201.18.html#TITL_113
This is what we used when we changed our main wiki page: now most links target our SAD html page.

About the look, I'm no expert (first time I tune a css), but if it pleases you, I'm happy!
What I like very much with our format is that all vectorial drawings are embedded within the HTML source, as <svg>...</svg>. This won't work on older IE, but reduces a lot the server and client work.
The resulting page is well compressed: our 6.5 MB html file results in a 1.2 MB gzipped content on the wire. To be compared with the already compressed 16.5 MB of pdf!

edwinsn · 2014-11-07 14:06:11

The HTML version of the document is great! Now I can utilize the Google search engine

warleyalex · 2014-11-17 01:07:46

I have created a mORMot WebHelp.
This WebHelp include: the Table of Contents, Keyword Index and Full Text Search sections! This is one is very fast.

https://www.dropbox.com/s/tjpo52ihedybv … t.rar?dl=0

ab · 2014-11-17 09:11:30

Nice!
You did use the Help & Manual tool, with manual edition, right?

Automated generation is IMHO better, since we can re-create the HTML easily from our source.
Some ideas to take for enhancing our SynProject tool.
Any input is welcome!

edwinsn · 2014-11-17 09:58:40

I'm quite satisfied with the PDF version with SumatraPDF.

ab · 2014-11-17 11:44:44

We will continue to publish both formats.

Perhaps the pdf sometimes with a small delay.
It takes 2 seconds to generate the html files directly from SynProject, whereas Word takes at least 3 minutes (!) to generate the pdf (on a Core i7) from the rtf generated by SynProject (also in 2 seconds)!

warleyalex · 2014-11-17 11:49:55

SynProject is sophisticated indeed, it creates a full table of contents, reference tables, keyword Index, etc. It would be nice to see a "Full Text Search sections" (like HelpandAndManual).

It would be nice, if it could generate separate a set of pages: one page per unit (multi-page HTML); easy to generate a CHM file for instance, like you can do on HelpAndManual.

mORMot CHM Help File
https://www.dropbox.com/s/byo0afxl9cjqa … t.rar?dl=0

Last edited by warleyalex (2014-11-17 11:50:20)

ab · 2014-11-17 13:02:37

In the current version, most of the text is in a single page.
So it is easy to use Ctrl + F on the page.
But fulltext search may be handy.

mORMot Open Source

#1 2011-08-10 18:47:10

Documentation updated to revision 1.15

#2 2012-02-18 17:26:01

Re: Documentation updated to revision 1.15

#3 2014-11-03 08:45:30

Re: Documentation updated to revision 1.15

#4 2014-11-03 11:25:50

Re: Documentation updated to revision 1.15

#5 2014-11-05 13:44:29

Re: Documentation updated to revision 1.15

#6 2014-11-05 14:35:08

Re: Documentation updated to revision 1.15

#7 2014-11-06 08:24:20

Re: Documentation updated to revision 1.15

#8 2014-11-06 08:38:53

Re: Documentation updated to revision 1.15

#9 2014-11-07 14:06:11

Re: Documentation updated to revision 1.15

#10 2014-11-17 01:07:46

Re: Documentation updated to revision 1.15

#11 2014-11-17 09:11:30

Re: Documentation updated to revision 1.15

#12 2014-11-17 09:58:40

Re: Documentation updated to revision 1.15

#13 2014-11-17 11:44:44

Re: Documentation updated to revision 1.15

#14 2014-11-17 11:49:55

Re: Documentation updated to revision 1.15

#15 2014-11-17 13:02:37

Re: Documentation updated to revision 1.15

Board footer