Improve docs for section element (implicit path) and more info on src…

…Dir -> homeDir logic (#72)

* fix mention section implictly adds relative path

* fix typos

* add src to out path logic

* adding owlkettle use case

book/configuration.nim

@@ -72,10 +72,29 @@ nb.blk.code = block:
 nbText: """
 ## Folder structure
 By default the nimibook folder structure is to put all sources in a `book` folder
-and to put the book built output in a `docs` folder (so that it is straightforward to publish the book wit github pages).
+and to put the book built output in a `docs` folder (so that it is straightforward to publish the book with github pages).
 
 These folders can be customized since they are taken from [nimib] section of `nimib.toml`
-as `srcDir` and `outDir`.
+as `srcDir` and `homeDir`.
+
+### where does nimibook puts the output html?
+
+The logic of nimibook is that for every source, the **relative path** with respect to `srcDir` is applied as relative path to `homeDir` and this will give the html output path.
+For example, if we have default values `srcDir="book";homeDir="docs"`:
+  - a source in `book\example.md` will generate `docs\example.html`
+  - a source in `book\folder\subfolder\example.nim` will generate `docs\folder\subfolder\example.html`
+
+Note in particular that if you have this structure in root folder:
+```
+README.md
+img.png
+book/
+  example.nim
+docs/
+  ...
+```
+and you add `..\README.md` as source, the generated `README.html` will NOT be in `docs` folder and it will be next to `README.md` (since `docs` is a folder inside root folder, at the same level as `book`).
+You can override this behaviour in `nbook.nim` but if the README.md references an image (say `img.png`) you will also need to make a copy of `img.png` in the docs folder. 
 
 ## Additional remarks
 * for consistency with template values, we use snake case for fields of this object.

book/toc.nim

@@ -18,6 +18,8 @@ From the above example you can see that:
   - source path is relative to book source folder
   - source extension defaults to `.nim`, to use a markdown source you need to explict mark it as `.md`
   - chapters that start a section are created with `section` and start a new block
+    - **note** that the path of section folder is added implicitly to all childrens (entries or sections)
+      of a section (e.g. `nested.md` is inside `tocexample` folder)
   - draft chapters (placeholders in the ToC without source) are created with `draft` 
 
 In the future nimibook will support the same `SUMMARY.md` mechanism as in mdbook.