From f61405b72f33c52acd297fa1ad6d8cd09b2a1baa Mon Sep 17 00:00:00 2001
From: vincent-peugnet <vincent-peugnet@riseup.net>
Date: Tue, 14 Jan 2025 13:25:07 +0100
Subject: [PATCH] manual: add hints about how to use internal links

---
 MANUAL.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 62 insertions(+), 10 deletions(-)

diff --git a/MANUAL.md b/MANUAL.md
index 6035943..c6c77fb 100644
--- a/MANUAL.md
+++ b/MANUAL.md
@@ -3,7 +3,7 @@ USER MANUAL
 
 Welcome to W's manual !
 
-See an introduction on [W's website](https://w.club1.fr/usage.html).
+To understand the key concepts of W, you should check the introduction on [W's website](https://w.club1.fr/usage.html).
 
 
 
@@ -117,18 +117,40 @@ It's important to notice that you can mix  Markdown and HTML. But beware, as HTM
 - [Markdown Guide](https://www.markdownguide.org/) Markdown Syntax guide
 - [Michel Fortin's Markdown extra](https://michelf.ca/projects/php-markdown/extra/) The library used in W.
 
+#### Internal links
 
-#### W specific syntax
+Internal links are links that point to the pages that are managed by this instance of W. As those pages are all under the same domain and path, you don't need to use the full `https://...` adress to create internal links.
+You just need to use the [page identifier](#page-id).
 
-This is not part of the markdown syntax.
+Here are some examples
 
-##### Wiki links
+Using __Markdown__:
 
-Wiki links can be used both in [content elements](#content-elements) and in the [BODY](#body).
+    [a link to my nice page](PAGE_ID)
 
-Wiki style links are __only for internal links__. Their main interest compared to markdon links is that the clickable part of the link will be replaced by page's [title](#page-title) if it exist.
+With __HTML__:
 
-    [[<page_id>]]
+    <a href="PAGE_ID">link to my page</a>
+
+As you can see, you always need to setup the text of the link. But what if we could just have [page's title](#page-title) instead ? [Wiki links are here for that purpose](#wiki-links).
+
+##### Combine with commands
+
+Internal links can be combined with the [URL commands](#url-based-command-interface) to achieve diabolic means.
+
+For example, you can create a link to directly edit a page using like this:
+
+    [edit the page](PAGE_ID/edit)
+
+
+
+#### Wiki links
+
+Wiki links can be used both in [content](#content-elements) and in the [BODY](#body).
+
+Wiki style links are __only for internal links__. Their main interest compared to markdon links is that the clickable part of the link will be replaced by [page's title](#page-title) if it exist.
+
+    [[PAGE_ID]]
 
 Will generate :
 
@@ -146,8 +168,6 @@ Note that the `.internal` class have been added to the `a` html link, allowing y
 
 
 
-
-
 ### Styling links
 
 During the render process, some semantic datas are added to the __HTML classes of links__. It's intended to help editor style their Webpages.
@@ -214,7 +234,7 @@ Inclusion is an advanced feature of W that allow editors to insert metadatas, ge
 
 #### Basic inclusions
 
-Those codes are mainly used to print page's [metadatas](#metadatas).
+Those codes are mainly used to print page's [metadatas](#metadatas). They are very usefull combined with [BODY templating](#body-template)
 
 ##### Title inclusion
 
@@ -273,6 +293,17 @@ This will print a HTML list of every [authors](#authors) of the page. If they ha
 
 You have two options to print the page ID.
 
+This is powerfull when combined with [URL commands](#url-based-command-interface) and [BODY templating](#body-template).
+
+For instance, use this in a BODY template to create an edition link for the current page:
+
+    <a href="%PAGEID%/edit">edit me !</a>
+
+Or to add a manual render button:
+
+    <a href="%PAGEID%/render">refresh me !</a>
+
+
 ##### path inclusion
 
     %PATH%
@@ -672,6 +703,27 @@ This will call the BODY of another page instead of current page's BODY.
 
 If they are sets, BODY template also provide a page [thumbnail](#thumbnail) and [favicon](#favicon).
 
+You can use [inclusions](#inclusions) to take advantage of BODY templating.
+
+Example of a basic but efficient BODY template, basic inclusions and some [URL commands](#url-based-command-interface).
+
+```
+<header>
+    <h1>%TITLE%</h1>
+    <p>%DESCRIPTION%</p>
+</header>
+<main>
+    %CONTENT%
+</main>
+<footer>
+    <a href="%PAGEID%/edit">edit page</a>
+    <a href="%PAGEID%/delete">delete page</a>
+</footer>
+```
+
+
+
+
 #### CSS template
 
 CSS template allow you to link another page's stylesheet to your page.