parts reorganization + add part03 (how pagedjs works) and part03 (interface) +...

parts reorganization + add part03 (how pagedjs works) and part03 (interface) + modify quick presentation in part01

Part01_Getting-Started-with-paged.md

@@ -4,9 +4,19 @@
 
 ## A quick presentation of paged.js
 
-Paged.js is an open-source javascript library to display paginated content in the browser and to generate print books using web technology.
 
-It's composed of a *Chuncker* and a *Polisher*. The Chunker chunks up a document into paged media flows and applies print classes. The Polisher converts @page css to classes, and applies counters and content.
+
+Paged.js is a free and open-source library to paginate content in the browser to create PDF outputs from any HTML content based on the W3C specifications.
+
+With Paged.js you can do automated typesetting adaptable to any workflows. It will fragment your content, read and apply your print declarations and present a paginated rendering of the HTML document. 
+
+
+
+### Visual preview and command line version
+
+With paginated content in the browser, Paged.js makes it possible to have a visual preview of the printed rendering directly in web browsers with a graphical interface. This allows designers to access development tools to make changes on the fly and control the rendering of the composition (easy debugging). It's also possible to insert Paged.js into other tools and to propose to users to configure their graphical rendering by adding functionalities.
+
+Paged.js can easily be inserted into automated workflows thanks to the command line interface version (using an headless browser) that can generate a PDF from scriptable and automated commands. 
 
 
 
@@ -24,6 +34,10 @@ W3C CSS modules implemented by paged.js :
 
 
 
+
+
+
+
 ### A community
 
 The code of paged.js is open-source with a MIT license and the development is community-driven. Everyone is invited to join us!
@@ -46,9 +60,9 @@ How to start with paged.js?  The first thing is to make the script work on your
 * a (local) server,
 * a web browser.
 
+https://www.startpage.com/fr/
 
-
-### Access to paged.js script
+### Access to paged.polyfill.js script
 
 **Option 1: CDN version**
 
@@ -58,7 +72,7 @@ You can use the hosted version of the script, just copy this in the `head` of yo
 <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
 ```
 
-If you want to specify the release number of the script you are using, the different releases of the script will be available here: https://gitlab.pagedmedia.org/tools/pagedjs/releases
+If you want to specify the release number of the script you are using, the different releases of the script will be available here: https://gitlab.pagedmedia.org/tools/pagedjs/releases. By default, the link bellow go to the latest release.
 
 To use the script locally, without an internet connection, just copy the script into a file and change the link to your script, something like:
 
@@ -66,7 +80,7 @@ To use the script locally, without an internet connection, just copy the script
 <script src="js/paged.polyfill.js"></script>
 ```
 
-The script will start automatically when you go to your document from the browser.  It will apply to all your content and fragment it into different pages. If you need to run other scripts before paged.js starts, if you want to integrate it into a tool or simply if you want delay its launch, we will see that in another part.
+The script will start automatically when you go to your document from the browser. It will apply to all your content and fragment it into different pages. If you need to run other scripts before paged.js starts, if you want to integrate it into a tool or simply if you want delay its launch, we will see that in another part.
 
 
 
@@ -84,21 +98,24 @@ $ npm start
 Link the script with your document:
 
 <script src="http://localhost:9090/dist/paged.polyfill.js"></script>
-
 All you need to know about setup, development and testing with the local dev-server is available in the README.md of the repo. 
 
 
 
 ### Use a local server
 
-Paged.js need to access your files via a local server to read the css properties you write. There is a lot of way to create and lunch a local server.  The easiest way is to use ready-to-use local web development solution like [WAMP](http://www.wampserver.com/) (for window) or [WAMP](https://www.mamp.info/en/) (for Mac).
+Paged.js need to access your files via a local server to read the css properties you write. There is a lot of way to create and lunch a local server.  If you're not familiar to Linux, the easiest way is to use ready-to-use local web development solution like [WAMP](http://www.wampserver.com/) (for window) or [WAMP](https://www.mamp.info/en/) (for Mac).
 
 You can find all the documentation on their respective websites, globally:
 
 1. download the package and follow the step of your usual system installation manager.
 2. add the folder of your project in the folder automatically create by the application, typically in `c:\wamp\www` for WAMP or in `/Applications/MAMP/htdocs/`
 3. Start the local server
-4. In your favorite browser, go to the local address provided by your application `http://localhost:8888`
+4. In your favorite browser, go to the local address provided by your application (like`http://localhost:8888` for example)
+
+
+
+Note: With some browsers and some OS, you may not need a local server for paged.js to work. To find out, simply open your HTML page (linked to the polyfill).  If the paginated content appears, you don't need a local server.
 
 
 
@@ -164,6 +181,8 @@ The way paged.js work, it doesn't use the print engine from the browser to defin
 
 ### Option 2: with pagedjs-cli
 
+The command line version of paged.js uses a headless browser to generate a PDF (chromium). So you can use paged.js in fully automated workflows. With the command line version, you don't need to call the paged.js script in your document, it will be done automatically.
+
 First, download and install pagedjs-cli with your terminal (you need to have git and npm installed):
 
 ```

Part02_how-pagedjs-works.md

+# How paged.js works
+
+
+
+If you have ever tried to lay out a website for printing or to publish a book in HTML, you’ll have experienced the limitations of styling meant for displaying scrolling text on screens. Paged.js helps make it possible to produce paginated material from your browser.
+
+
+
+![](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/flux-page.png)
+
+
+
+## W3C CSS modules
+
+For printing pages you need very different rules from those used to  display content in the browser. For example, you’ll want to declare fixed sized pages rather than lay out a continuous flow of text. Books  also need many specific elements for the printed layout: margins, running headers, page numbers, a table of contents, and so on.
+
+Fortunately the work on CSS at the W3C has resulted in special modules of the CSS standard for managing the layout of a HTML document during printing. These modules can be used in a print stylesheet with the media query `@media print{}`  and will only be applied when 
+the web page is printed from the browser print dialog to create a PDF.
+
+- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css3-page/)  “describes the page model that partitions a flow into pages. (…) It  adds functionality for pagination, page margins, page size and  orientation, headers and footers, widows and orphans, and image  orientation.”
+- [CSS Generated Content for Paged Media Module](https://www.w3.org/TR/css-gcpm-3/)  defines many special requirements for the display of printed document  content: running headers and footers, footnotes, generated text for  cross-references or table of contents, PDF bookmarks, etc.
+- [CSS Fragmentation Module Level 3](https://www.w3.org/TR/css-break-3/) defines how and where CSS boxes can be fragmented, including across page breaks. (This module is not specific for print.)
+- [ CSS page floats](https://www.w3.org/TR/css-page-floats-3/) defines how an element is to be removed from the normal flow and instead be placed into a different place depends on page. ([see the article “Page Media approaches: page floats”](https://www.pagedmedia.org/page-floats/))
+
+
+
+
+
+## Support of W3C specifications in browsers
+
+
+
+The previous CSS standard modules were written by the World Wide Web  Consortium (W3C). W3C publishes documents that define Web technologies  (including CSS) which are considered Web Standards. W3C modules are  published publicly throughout the process of their development until  they are finally released as a [W3C Recommendation](https://www.w3.org/2018/Process-20180201/#rec-publication). The modules we need for pagined media are at various stages of the process, but most are still in the [Working Draft](https://www.w3.org/2018/Process-20180201/#revised-wd) stage.
+
+Browser developers can start implementing these recommendations at  any point, knowing they may change later, but the developers are not  obliged to implement all the CSS specifications until they become W3C  Recommendations.
+
+Thankfully, browser developers have already taken some interest in  implementing parts of the Paged Media Working Draft standards and [@page rules have partial support](https://caniuse.com/#search=%40page) in Chrome, Firefox and IE. But it’s still difficult to use these browsers effectively for the output of paginated content.
+
+So when it comes to producing paginated content from the browser,  this is where we are today: the rules for printing web pages from a  browser are written, and even standardised, but we can’t as yet use them  effectively.
+
+
+
+## The paged.js library
+
+The Paged.js library can be considered as a polyfill or previous CSS modules  - i.e., a code that implements a feature on web browsers that do not support the feature. But note that this is also our own interpretation of the implementation of this modules. 
+
+We try to respect the specifications as much as possible, but they can be unclear and leave a certain degree of indeterminacy. In this case, we develop our own rules that seem to us to be the most technically appropriate and best meet the expectations of typographers and designers.
+
+In your side, you just have to write the standardiezd CSS declarations and paged.js does its kind of magic. The library interprets the declarations and transforms them to other declarations that your browser understand by updating them with supported styles or replacing them with JavaScript implementations.
+
+
+
+The library is build in differents javascript parts that work together: 
+
+- the **chuncker** fragment the content into discrete pages, 
+- the **polisher** transforms the CSS declarations,
+- and the **previewer** call the preview of your book in the browser.
+
+
+
+## The chunker
+
+The chuncker part of paged.js getting your stylized content split into your page chunks. 
+
+It take all your rendered document content - this means your content with all the design rules applied to it. It put this content in a box that have the size of your content area  (page size minus margins size). It try to fit all into this container and looks for the overflowing content.
+
+![The chunker put all your rendered content in a box and check the overflow](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/chuncker-1.png)
+
+After, the script create a new box and puts the overflow content in it. And look for the next overflowing content. 
+
+Paged.js do it all over again until the book is done. Once you’ve got your content chunked, you’ll need to repeat the process anytime something changes. 
+
+
+
+![The chuncker create a new box an put the overflow content in it](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/chuncker-2.png)
+
+We will see that it is possible to control page breaks and change the size of the content area by changing the margins from one page to another according to a page master layout.
+
+
+
+**Using CSS column**
+
+Each content area is a CSS column independant from the other area. Using columns allows to have easier access to the linked properties already implemented in browsers like breaks elements properties or widows and orphans.
+This doesn't prevent you from using the CSS column property in your content
+
+
+
+
+
+## The polysher: polyfill the print declarations
+
+
+
+With the polysher part, Paged.js also build new boxes to create layout pages and and place your content boxes on this pages. 
+
+![](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/div-pages.png)
+
+
+
+In parallel, the script reads your CSS file to have the information about the print style and transform your `@page` rules into classes that your browser understand today. We uses the CSS tree library to parse the CSS from text and replace `@page` rules with classes. The polisher also replaces calls like running headers or counter pages to CSS generated content functions with variable from the DOM.
+
+Paged.js include support for a lot of things from the CSS (generated content for) paged media specifications, so that you can write CSS that conforms to that specifications. Paged.js do the work for apply it on the transformed DOM. 
+
+Let's take the following CSS as an example:
+
+```CSS
+@page { 
+  size: 148mm 210mm;
+  margin-top: 10mm;
+  margin-right: 20mm;
+  margin-bottom: 25mm;
+  margin-left: 15mm;
+  
+  @bottom-left {
+    content: counter(page);
+  }
+  
+  @bottom-center {
+    content: string(title);
+    text-transform: uppercase;
+  }
+  
+}
+
+h1#title {
+  <!-- "Moby Dick" -->
+  string-set: title content(text);
+}
+```
+
+
+
+Paged.js transforms this into a CSS that is understandable to the browser:
+
+```CSS
+.pagedjs_page {	
+	--pagedjs-string-title: "Moby Dick";
+	margin-top: 10mm;
+	margin-right: 20mm;
+	margin-bottom: 25mm;
+	margin-left: 15mm;
+}
+
+.pagedjs_page .pagedjs_margin-bottom-left::after {
+	content: string(title); 
+}
+
+.pagedjs_page .pagedjs_margin-bottom-center::after {
+	content: var(--pagedjs-string-title);  
+	text-transform: uppercase;
+}
+```
+
+
+
+This will apply to the transformed DOM (here simplified):
+
+```html
+<div id="page-1" class="pagedjs_page">
+	<div class="pagedjs_pagebox">
+    	<div class="pagedjs_margin pagedjs_margin-bottom-left hasContent">
+				<div class="pagedjs_margin-content">
+          <!-- ::after -->
+        </div>
+			</div>
+      <div class="pagedjs_margin pagedjs_margin-bottom-center hasContent">
+				<div class="pagedjs_margin-content">
+          <!-- ::after -->
+        </div>
+			</div>
+    </div>
+		<div class="pagedjs_area">
+			<!-- content of the page -->
+		</div>
+	</div>
+</div>
+```
+
+
+
+Across this documentation, we will specify the CSS properties we implement and the one we use instead so that they can be interpreted by the browser.
+
+
+
+## Previewer / Pagined rendering
+
+
+
+The preview module of paged.js is specially dedicated to browsers. The previewer loads the modules, and uses the polisher and chunker to parse and layout the content. It build the preview of your document in the browser, so you can see exactly how things are going to look, and adjust your content accordingly.
+
+With the script `paged.polyfill.js`, the previewer module is launched automatically and immediately (as soon as the page with the script is called). It will by default apply to all your HTML content. 
+
+Using es6 modules you can add the previewer to your own scripts. You can also decide the delay to launch the paged.js script. We will see this in another part. Undertand that paged.js is just a script like others scripts. So, you can use it like you want.
+
+
+
+## DOM modification
+
+
+
+Paged.js modifies the DOM structure by adding some HTML elements to build and render your layout. This modification is only made during rendering, so there is no modification in your original HTML document.
+
+It also adds references to every node (for example, classes to differentiate right or left pages). This gives us complete control over the page layout without any hacks. 
+
+This documentation will provide more precisely for each CSS property the node references that are added to build and render the layout. You can access these elements in javascript directly with their classes if you want to go further with paged.js and add your own functions.
+
+
+
+
+
+
+
+
+
+
+
+
+

Part03_Interface.md

+# Paged.js Interface
+
+
+
+It is certainly easier to use paged.js with a rendering where you *actually* see the pages of your book side by side. For this, you can directly style the `div` pages using there classes.
+
+We provide you an exemple of CSS to do this in an easy way.
+
+Download this CSS file: [interface-01.1](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/ressources/interface-0.1.css)
+
+Link the CSS file to your document:
+
+```HTML
+<link href="paht/to/file/interface-0.1.css" rel="stylesheet" type="text/css">
+```
+
+
+
+You can uncomment and modify part of the CSS file:
+
+In the CSS file you can uncomment and modify parts: 
+
+- for recto/verso book
+- to see and set the baseline 
+
+
+
+
+

Part03_Global-Layout.md → Part04_Global-Layout.md

@@ -34,7 +34,7 @@ The first thing to do in your style sheet is to specify this request:
 
 
 
-
+The styles declared in this media query will only be applied when the web page is printed from the browser print dialog to create a PDF. For  example, the size of the typography for print is declared differently  than that for screen display so it is more suitable for printing, or images are removed (with `display:none`) to save ink. Paged.js provides you a preview in the browser of the comportement of your styles when printing.