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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Documentation updated to revision 1.15

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:
mORMotClientServerArchi.png
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. wink

A lot more to discover in this new pdf files!

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

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

Offline

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

Eric
Member
Registered: 2012-11-26
Posts: 129
Website

Re: Documentation updated to revision 1.15

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. smile

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

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.

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

@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?
smile

Offline

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

cheemeng
Member
From: Malaysia
Registered: 2011-08-09
Posts: 61

Re: Documentation updated to revision 1.15

Nice! Well done Arnaud! smile

Offline

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

Eric
Member
Registered: 2012-11-26
Posts: 129
Website

Re: Documentation updated to revision 1.15

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 smile

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" smile

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

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!

Offline

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

edwinsn
Member
Registered: 2010-07-02
Posts: 1,215

Re: Documentation updated to revision 1.15

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


Delphi XE4 Pro on Windows 7 64bit.
Lazarus trunk built with fpcupdelux on Windows with cross-compile for Linux 64bit.

Offline

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

warleyalex
Member
From: Sete Lagoas-MG, Brasil
Registered: 2013-01-20
Posts: 250

Re: Documentation updated to revision 1.15

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

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

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!

Offline

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

edwinsn
Member
Registered: 2010-07-02
Posts: 1,215

Re: Documentation updated to revision 1.15

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


Delphi XE4 Pro on Windows 7 64bit.
Lazarus trunk built with fpcupdelux on Windows with cross-compile for Linux 64bit.

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

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)!
smile

Offline

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

warleyalex
Member
From: Sete Lagoas-MG, Brasil
Registered: 2013-01-20
Posts: 250

Re: Documentation updated to revision 1.15

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)

Offline

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

ab
Administrator
From: France
Registered: 2010-06-21
Posts: 14,182
Website

Re: Documentation updated to revision 1.15

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

Offline

Board footer

Powered by FluxBB