From c47b78e13afb092aa1a30296b885b2911444fe3c Mon Sep 17 00:00:00 2001 From: vincent-peugnet Date: Tue, 21 Jan 2020 01:28:04 +0100 Subject: new user manual in markdown --- MANUAL.md | 116 ++++++++++++++++ app/class/Controllerinfo.php | 16 ++- app/class/Model.php | 3 +- app/class/Modelrender.php | 46 +++++-- app/view/templates/info.php | 48 +++---- app/view/templates/man.php | 320 ------------------------------------------- assets/css/home.css | 13 +- old_manual.html | 299 ++++++++++++++++++++++++++++++++++++++++ 8 files changed, 501 insertions(+), 360 deletions(-) create mode 100644 MANUAL.md delete mode 100644 app/view/templates/man.php create mode 100644 old_manual.html diff --git a/MANUAL.md b/MANUAL.md new file mode 100644 index 0000000..a689802 --- /dev/null +++ b/MANUAL.md @@ -0,0 +1,116 @@ +USER MANUAL +=========== + +Introduction +------------ + +Welcome to __W__, this manual is here to help you get the best of this tool. + + + +Startup +------- + +Welcome to __W__ + +- des infos +- les composants de W + + +- des infos +- les composants de W + + +- des infos +- les composants de W + + +- des infos +- les composants de W + + +- des infos +- les composants de W + + +- des infos +- les composants de W + + +- des infos +- les composants de W + + +Structure +--------- + +W use Markdown +W use Markdown + +W use Markdown +W use Markdown + +### Pays + +#### France + +Le pays de la France +Le pays de la France +Le pays de la France +Le pays de la France +Le pays de la France + + +Le pays de la France +Le pays de la France + +#### USA + +##### BELGIQUE + +LA BIERE + + + + +W use Markdown + + +Editor +------ + +W use Markdown +W use Markdown + + +### Ideas + +W use Markdown + +W use Markdown +W use Markdown +W use Markdown + + +W use Markdown +W use Markdown + + +The editor is fine + +### New ideas + +- get adress +- edit + +W use Markdown +W use Markdown +W use Markdown +W use Markdown + + +W use Markdown + + + +It's OK \ No newline at end of file diff --git a/app/class/Controllerinfo.php b/app/class/Controllerinfo.php index af81caf..856d065 100644 --- a/app/class/Controllerinfo.php +++ b/app/class/Controllerinfo.php @@ -1,6 +1,7 @@ user->iseditor()) { - $this->showtemplate('info', ['version' => getversion()]); + + if(file_exists(Model::MAN_FILE)) { + + $render = new Modelrender($this->router); + $htmlman = file_get_contents(Model::MAN_FILE); + $htmlman = $render->rendermanual($htmlman); + + $summary = $render->sumparser($htmlman, 3); + + + $this->showtemplate('info', ['version' => getversion(), 'manual' => $htmlman, 'summary' => $summary]); + + } + } } diff --git a/app/class/Model.php b/app/class/Model.php index bb07fea..913dc34 100644 --- a/app/class/Model.php +++ b/app/class/Model.php @@ -5,7 +5,8 @@ namespace Wcms; abstract class Model { - const CONFIG_FILE = 'config.json'; + const CONFIG_FILE = 'config.json'; + const MAN_FILE = 'MANUAL.md'; const CSS_DIR = 'assets' . DIRECTORY_SEPARATOR .'css' . DIRECTORY_SEPARATOR; const JS_DIR = 'assets' . DIRECTORY_SEPARATOR .'js' . DIRECTORY_SEPARATOR; const ICONS_DIR = 'assets' . DIRECTORY_SEPARATOR .'icons' . DIRECTORY_SEPARATOR; diff --git a/app/class/Modelrender.php b/app/class/Modelrender.php index 593a420..fe491f1 100644 --- a/app/class/Modelrender.php +++ b/app/class/Modelrender.php @@ -36,6 +36,21 @@ class Modelrender extends Modelpage } } + /** + * Used to convert the markdown user manual to html document + * + * @param string $text Input text in markdown + * @return string html formated text + */ + public function rendermanual(string $text) : string + { + $text = $this->markdown($text); + $text = $this->headerid($text, 3); + return $text; + + } + + public function upage($id) { return $this->router->generate('pageread/', ['page' => $id]); @@ -384,11 +399,25 @@ class Modelrender extends Modelpage return $text; } - public function headerid($text) + /** + * Add Id to hrml header elements and store the titles in the `sum` parameter + * + * @param string $text Input html document to scan + * @param int $maxdeepness Maximum header deepness to look for. Min = 1 Max = 6 Default = 6 + * + * @return string text with id in header + */ + + public function headerid($text, int $maxdeepness = 6) { + if($maxdeepness > 6 || $maxdeepness < 1) { + $maxdeepness = 6; + } + + $sum = []; $text = preg_replace_callback( - '/(.+)<\/h[1-6]>/mU', + '/(.+)<\/h[1-' . $maxdeepness . ']>/mU', function ($matches) use (&$sum) { $cleanid = idclean($matches[4]); $sum[$cleanid][$matches[1]] = $matches[4]; @@ -453,16 +482,15 @@ class Modelrender extends Modelpage return $text; } - - function sumparser($text) + /** + * Generate a Summary based on header ids. Need to use `$this->headerid` before to scan text + * + * @return string html list with anchor link + */ + function sumparser() : string { - preg_match_all('#(.+)#iU', $text, $out); - - $sum = $this->sum; - - $sumstring = ''; $last = 0; foreach ($sum as $title => $list) { diff --git a/app/view/templates/info.php b/app/view/templates/info.php index 8f6377b..bcfc2c8 100644 --- a/app/view/templates/info.php +++ b/app/view/templates/info.php @@ -12,25 +12,24 @@ @@ -38,22 +37,12 @@
+

Info

- insert('man') ?> +
+ +
+
diff --git a/app/view/templates/man.php b/app/view/templates/man.php deleted file mode 100644 index deb81ee..0000000 --- a/app/view/templates/man.php +++ /dev/null @@ -1,320 +0,0 @@ - - - - - - -
- -

Manual

- -

Startup

- -

There is'nt a real start of anything when you're using W.

- -

Just type an adress in your web browser, after your W folder. You should see an empty page, not existing yet. You can login to create one at this adress. If you are already logged in, you can juste type page_id/add, this will directly create a page at this adress.

- -

This page_id is the identifier of each page, you cant change it later, this is like a real solid adress, it cant move. It can only contain lowercase letters, numbers, hyphens or underscore charachters.

- -

No visitor can see the full list of pages you've created. The only way to see the whole map of your project, is to be conected at least as an editor, and go to the "homepage", the root adress where W is instaled.

- -

Structure

- -

Pages and IDs

- -

The structure of website is very simple as there is no structure. It's you to link the pages together or not.

- -

A page is defined by a unique id. As it's created, you can access it typing .../your_page_id/ or without slash .../your_page_id

- -

An ID can only contain lowercase letters, numbers, underscore and "-"

- - -

Page attributes

- -
Id
- -

Unique identifier, this is the url that point to your page

- -
title
- -

Page title, can use more complex characters than the ID element. It's printed in the explorer tab name. It's the official name of your page.

- -
Description
- -

The description attribute is a short informations about your page. It's used to create tooltip, when the mouse hover internal links.

- -
Tag(s)
- -

tags are used to create selections of pages. tags are one word only, sepparated by commas and whitespace.

- -
Privacy level
- -

Set the level of privacy of your page. -
0 -> public -
1 -> private reserved to private readers -
2 -> not published Nobody but editors can see it.

- - -
Date & time
- -

You can manualy set a date and time for each pages.

- -

Database

- -

All this pages are stored in your database, as a file by page. You can access them in the .../database/name_of_your_store/

- - - - - - - - - - - -

Editor

- -

W use the fives basics html elements to store your content

- -
    -
  • header
    • -
  • nav
    • -
  • aside
    • -
  • main
    • -
  • footer
    • -
- -

You can use any of them, only one or all at the same time, as you prefer.

- -

Element syntax

- -

In any of the five html element you can use to store content, you can use the following syntax, that is specific to W, extending the Markdown syntax :

- -
quick internal link
- -

You can create internal link very quickly, only by using the id of your page. The link text will be remplaced by the title associated with this page.

- -
- [page_id] -
- -

This will output :

- -
-<a href="page->url" class="internal" title="page->description">page->title</a> -
- -
Title shortcut
- -
- %TITLE% -
- -

Will output the page title attribute. This can be usefull when templating, or including differents page element.

- - -
Description shortcut
- -
- %DESCRIPTION% -
- -

As for the title, this will output the description attribute of the page

- -
Date shortcut
- -
- %DATE% %DATECREATION% %DATEMODIF% -
- -

There are tree dates attributes that can be printed. The date attribute, will return the date that can be manualy set in the editor. datecreation will return the date of the page creation. datemodif will output the last editing date.

- - -
Automatic summary
- -

You can automatically generate summary, based on the page <h*> elements

- -
- %SUMMARY% -
- -

This will generate a classic <ul> html list.

- -
Automatic list by tag
- -

You can create a html list of links pointing to all the pages using this tag.

- -
- %TAG:__tag__% -
- -

Let's suppose we are in page3 and we have page2, page3, page5, using this tag, this will output :

- -
-<ul id="tag"> -
-<li> -
-<a href="2->url" class="internal" title="2->description">2->title</a> -
-</li> -
-<li> -
-<a href="3->url" class="internal actualpage" title="3->description">3->title</a> -
-</li> -
-<li> -
-<a href="5->url" class="internal" title="5->description">5->title</a> -
-</li> -
-</ul> -
- -

The list is ordered by the date attribute, that you can set manualy for each page. You may have noticed that the actual page (page 3), has been specified using .actualpage class. This can be usefull to create a menu and highlight the current page.

- - -
Article separator
- -

You can use the article html element, by separating text using at least ====. It is of course possible to use Markdown synthax inside those articles separators

- -
-====

-some text

-======important

-this is a longer text

-======

-
- -

This will ouptut :

- -
-<article>
-some text
-</article>
-<article id="important">
-this is a longer textt
-</article>
-
- - -

As you may have noticed, there is also the possibility to add a custom id to any of the articles created that way

- - -
Media list
- -

As it is too long adding all media of a folder one by one, you can just print the content of an entire folder using this method.

- -
-%MEDIA:__directory__ -
- -

Just point to the good directory inside the media folder. This will output html list, creating image elements, audio players, video players, or just basic link, depending on the media type.

- - - - - - -

Body syntax

- - - - -
Basic including
- -
%HTML_ELEMENT%
- - -

This will include the matching html element from your page's content in your page body. If there is nothing in the corresponding element, it won't print anything. The name of the html element as to be UPPERCASE.

- -

For example :

- -
-%ASIDE% -
-
-%MAIN% -
- -

Will output :

- -
-<aside class="page_id"> -
-__the content of your aside__ -
- -</aside> -
-
-<main class="page_id"> -
-__the content of your main__ -
- -</main> - - -
- -

You can also use one element multiple times.

- -
Advanced includings
- -
- %HTML_ELEMENT:page_id% -
- -

By doing this, you can include the HTML_ELEMENT of the page using this page_id id. You can even nest differents pages source by adding page_id separated by a dot, this would be like :

- -
- %HTML_ELEMENT:page1_id+page2_id% -
- -

And you can mix it with the original page content using ! identifier

- -
- %HTML_ELEMENT:page3_id+!% -
- -

This will output :

- -
- -<html_element class="page3_id page_id"> -
-__content of page1's html element__ -
-__content of this page html element__ -
-</html_element> - - - -
- -
diff --git a/assets/css/home.css b/assets/css/home.css index f23affc..b3edc49 100644 --- a/assets/css/home.css +++ b/assets/css/home.css @@ -273,8 +273,19 @@ main.info blockquote i { color: #7b97b9; } +main.info article#manual h1 { + text-align: center; + font-size: 50px; + color: black; + background-color: transparent; + font-weight: lighter; + margin: 6%; + border-top: solid; + border-bottom: solid; +} + -main.info article h2#manual { +main.info article#manual h2 { text-align: center; font-size: 40px; } diff --git a/old_manual.html b/old_manual.html new file mode 100644 index 0000000..215326c --- /dev/null +++ b/old_manual.html @@ -0,0 +1,299 @@ + + + + +
+ +

Manual

+ +

Startup

+ +

There is'nt a real start of anything when you're using W.

+ +

Just type an adress in your web browser, after your W folder. You should see an empty page, not existing yet. You can login to create one at this adress. If you are already logged in, you can juste type page_id/add, this will directly create a page at this adress.

+ +

This page_id is the identifier of each page, you cant change it later, this is like a real solid adress, it cant move. It can only contain lowercase letters, numbers, hyphens or underscore charachters.

+ +

No visitor can see the full list of pages you've created. The only way to see the whole map of your project, is to be conected at least as an editor, and go to the "homepage", the root adress where W is instaled.

+ +

Structure

+ +

Pages and IDs

+ +

The structure of website is very simple as there is no structure. It's you to link the pages together or not.

+ +

A page is defined by a unique id. As it's created, you can access it typing .../your_page_id/ or without slash .../your_page_id

+ +

An ID can only contain lowercase letters, numbers, underscore and "-"

+ + +

Page attributes

+ +
Id
+ +

Unique identifier, this is the url that point to your page

+ +
title
+ +

Page title, can use more complex characters than the ID element. It's printed in the explorer tab name. It's the official name of your page.

+ +
Description
+ +

The description attribute is a short informations about your page. It's used to create tooltip, when the mouse hover internal links.

+ +
Tag(s)
+ +

tags are used to create selections of pages. tags are one word only, sepparated by commas and whitespace.

+ +
Privacy level
+ +

Set the level of privacy of your page. +
0 -> public +
1 -> private reserved to private readers +
2 -> not published Nobody but editors can see it.

+ + +
Date & time
+ +

You can manualy set a date and time for each pages.

+ +

Database

+ +

All this pages are stored in your database, as a file by page. You can access them in the .../database/name_of_your_store/

+ + + + + + + + + + + +

Editor

+ +

W use the fives basics html elements to store your content

+ +
    +
  • header
    • +
  • nav
    • +
  • aside
    • +
  • main
    • +
  • footer
    • +
+ +

You can use any of them, only one or all at the same time, as you prefer.

+ +

Element syntax

+ +

In any of the five html element you can use to store content, you can use the following syntax, that is specific to W, extending the Markdown syntax :

+ +
quick internal link
+ +

You can create internal link very quickly, only by using the id of your page. The link text will be remplaced by the title associated with this page.

+ +
+ [page_id] +
+ +

This will output :

+ +
+<a href="page->url" class="internal" title="page->description">page->title</a> +
+ +
Title shortcut
+ +
+ %TITLE% +
+ +

Will output the page title attribute. This can be usefull when templating, or including differents page element.

+ + +
Description shortcut
+ +
+ %DESCRIPTION% +
+ +

As for the title, this will output the description attribute of the page

+ +
Date shortcut
+ +
+ %DATE% %DATECREATION% %DATEMODIF% +
+ +

There are tree dates attributes that can be printed. The date attribute, will return the date that can be manualy set in the editor. datecreation will return the date of the page creation. datemodif will output the last editing date.

+ + +
Automatic summary
+ +

You can automatically generate summary, based on the page <h*> elements

+ +
+ %SUMMARY% +
+ +

This will generate a classic <ul> html list.

+ +
Automatic list by tag
+ +

You can create a html list of links pointing to all the pages using this tag.

+ +
+ %TAG:__tag__% +
+ +

Let's suppose we are in page3 and we have page2, page3, page5, using this tag, this will output :

+ +
+<ul id="tag"> +
+<li> +
+<a href="2->url" class="internal" title="2->description">2->title</a> +
+</li> +
+<li> +
+<a href="3->url" class="internal actualpage" title="3->description">3->title</a> +
+</li> +
+<li> +
+<a href="5->url" class="internal" title="5->description">5->title</a> +
+</li> +
+</ul> +
+ +

The list is ordered by the date attribute, that you can set manualy for each page. You may have noticed that the actual page (page 3), has been specified using .actualpage class. This can be usefull to create a menu and highlight the current page.

+ + +
Article separator
+ +

You can use the article html element, by separating text using at least ====. It is of course possible to use Markdown synthax inside those articles separators

+ +
+====

+some text

+======important

+this is a longer text

+======

+
+ +

This will ouptut :

+ +
+<article>
+some text
+</article>
+<article id="important">
+this is a longer textt
+</article>
+
+ + +

As you may have noticed, there is also the possibility to add a custom id to any of the articles created that way

+ + +
Media list
+ +

As it is too long adding all media of a folder one by one, you can just print the content of an entire folder using this method.

+ +
+%MEDIA:__directory__ +
+ +

Just point to the good directory inside the media folder. This will output html list, creating image elements, audio players, video players, or just basic link, depending on the media type.

+ + + + + + +

Body syntax

+ + + + +
Basic including
+ +
%HTML_ELEMENT%
+ + +

This will include the matching html element from your page's content in your page body. If there is nothing in the corresponding element, it won't print anything. The name of the html element as to be UPPERCASE.

+ +

For example :

+ +
+%ASIDE% +
+
+%MAIN% +
+ +

Will output :

+ +
+<aside class="page_id"> +
+__the content of your aside__ +
+ +</aside> +
+
+<main class="page_id"> +
+__the content of your main__ +
+ +</main> + + +
+ +

You can also use one element multiple times.

+ +
Advanced includings
+ +
+ %HTML_ELEMENT:page_id% +
+ +

By doing this, you can include the HTML_ELEMENT of the page using this page_id id. You can even nest differents pages source by adding page_id separated by a dot, this would be like :

+ +
+ %HTML_ELEMENT:page1_id+page2_id% +
+ +

And you can mix it with the original page content using ! identifier

+ +
+ %HTML_ELEMENT:page3_id+!% +
+ +

This will output :

+ +
+ +<html_element class="page3_id page_id"> +
+__content of page1's html element__ +
+__content of this page html element__ +
+</html_element> + + + +
+ +
-- cgit v1.2.3