iBetter readme - cl-yag - Common Lisp Yet Another website Generator	Err	bitreich.org	70
hgit clone git://bitreich.org/cl-yag/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/cl-yag/	URL:git://bitreich.org/cl-yag/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/cl-yag/	bitreich.org	70
1Log	/scm/cl-yag/log.gph	bitreich.org	70
1Files	/scm/cl-yag/files.gph	bitreich.org	70
1Refs	/scm/cl-yag/refs.gph	bitreich.org	70
1Tags	/scm/cl-yag/tag	bitreich.org	70
1README	/scm/cl-yag/file/README.md.gph	bitreich.org	70
1LICENSE	/scm/cl-yag/file/LICENSE.gph	bitreich.org	70
i---	Err	bitreich.org	70
1commit d69df0f848a3779e778330fe558bd60abcd832a7	/scm/cl-yag/commit/d69df0f848a3779e778330fe558bd60abcd832a7.gph	bitreich.org	70
1parent 2266a8168f065f2b1311edee3999fcf9373cfaf7	/scm/cl-yag/commit/2266a8168f065f2b1311edee3999fcf9373cfaf7.gph	bitreich.org	70
hAuthor: solene rapenne <solene@dataswamp.org>	URL:mailto:solene@dataswamp.org	bitreich.org	70
iDate:   Fri, 20 May 2016 11:12:14 +0200	Err	bitreich.org	70
i	Err	bitreich.org	70
iBetter readme	Err	bitreich.org	70
i	Err	bitreich.org	70
iDiffstat:	Err	bitreich.org	70
i  M README.md                           |      62 +++++++++++++++++++++----------	Err	bitreich.org	70
i	Err	bitreich.org	70
i1 file changed, 43 insertions(+), 19 deletions(-)	Err	bitreich.org	70
i---	Err	bitreich.org	70
1diff --git a/README.md b/README.md	/scm/cl-yag/file/README.md.gph	bitreich.org	70
i@@ -2,38 +2,56 @@	Err	bitreich.org	70
i 	Err	bitreich.org	70
i cl-yag stands for Common Lisp Yet Another Generator and obviously it's written in Common Lisp.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i-It has only one dependency : a common lisp interpreter, I recommend both sbcl or clisp which are free, open-source and multi-platform.	Err	bitreich.org	70
i+It has only one dependency : a common lisp interpreter. It is regularly tested with sbcl, clisp and ecl which are free, open-source and multi-platform. You don't need quicklisp library manager.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i- 	Err	bitreich.org	70
i-# The hierarchy	Err	bitreich.org	70
i+**This comes with a minimalistic template**, don't expect something good looking without work. You will have to write the CSS entirely and modify the html to fit your need.	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+## The hierarchy	Err	bitreich.org	70
i 	Err	bitreich.org	70
i Here are the files and folder of cl-yag :	Err	bitreich.org	70
i  	Err	bitreich.org	70
i + **Makefile** : exists to simplify your life (updating, cleaning) 	Err	bitreich.org	70
i-+ **generator.lisp** : contains all the code of the generator 	Err	bitreich.org	70
i-+ **templates/** : contains .tpl files which are used as template for the html structure 	Err	bitreich.org	70
i-+ **static/** : contains static files that need to be made public like images, css, js etc...	Err	bitreich.org	70
i-+ **data/** : contains what will make the content of your website different from another website (or not) 	Err	bitreich.org	70
i-  + **articles.lisp** : contains metadata about the website and the list of the articles with their id/title/date/(author/short description) (aren't mandatory) 	Err	bitreich.org	70
i-  + **${id}.txt** : contains the html text of the article ${id} that will be used when displayed 	Err	bitreich.org	70
i-+ **output** : this is where the websites goes when your run *make*, and where it's cleaned when you run *make clean*; You can make it a symbolic link to the web server folder.	Err	bitreich.org	70
i++ **generator.lisp** : contains all the code of the generator	Err	bitreich.org	70
i++ **templates/** : contains .tpl files which are used as template for the html or xml structure 	Err	bitreich.org	70
i++ **static/** : contains the static files like images, css, js etc... that will be published	Err	bitreich.org	70
i++ **data/** : 	Err	bitreich.org	70
i+  + **articles.lisp** : contains metadata about the website and the list of the articles with their id/title/date/tag/*author*/*short description* (fields in *italic* are not mandatory)	Err	bitreich.org	70
i+  + **${id}.txt** : contains the html text of the article ${id} that will be used when displayed	Err	bitreich.org	70
i++ **output** : folder where the website is generated when your run *make*. It is cleaned when you run *make clean*; You can make it a symbolic link to the web server folder.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i+# Usage	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+## How to add an article	Err	bitreich.org	70
i  	Err	bitreich.org	70
i-# How to add an article	Err	bitreich.org	70
i- 	Err	bitreich.org	70
i-Edit data/articles.lisp and add a new line inside the *articles* variable like this	Err	bitreich.org	70
i+Edit data/articles.lisp and add a new line inside the *articles* variable like this (you can do it in one line, as you prefer)	Err	bitreich.org	70
i 	Err	bitreich.org	70
i-    (list :id "2" :date "29 April 2016" :title "How do I use cl-yag" :author "Solène" :short "I will explain how to use the generator" :tag "example help code")	Err	bitreich.org	70
i+    (list :title "How do I use cl-yag" 	Err	bitreich.org	70
i+              :id "2" :date "29 April 2016" 	Err	bitreich.org	70
i+              :author "Solène" 	Err	bitreich.org	70
i+                  :short "I will explain how to use the generator" 	Err	bitreich.org	70
i+                  :tag "example help code")	Err	bitreich.org	70
i 	Err	bitreich.org	70
i The _:short_ field is used on the homepage. It it is defined, this is the text that will be shown on the homepage with all the others articles. If it's not defined, the whole article content will be used on the homepage. Sometimes when you have long articles, you may not want to display it entirely on the index so you can use _:short "view the article for the full text_.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i+The _:id_ field will be part of the filename of the file and it's also the name of the content on the disk. `:id "2"` will load file `data/2.txt`, you can use text instead of numbers if you want.	Err	bitreich.org	70
i+	Err	bitreich.org	70
i The _:author_ field is used to display who wrote the article. You can omitt it, the generator will take the name from the *config* variable	Err	bitreich.org	70
i 	Err	bitreich.org	70
i-The _:tag_ field is used to create a page with all the articles with the same tag. You can omitt it if you don't want it tagged. Tags can't contain spaces.	Err	bitreich.org	70
i+The _:tag_ field is used to create a page with all the articles with the same tag. Tags can't contain spaces.	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+## How to publish	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+There is a makefile, all you need to do is to type "make" in the folder, this will create the files in the **output/** location (which can be a symbolic link to somewhere else). If you want to use a different lisp interpreter (default is **sbcl**), you can set the variable LISP to the name of your binary. 	Err	bitreich.org	70
i 	Err	bitreich.org	70
i-# How to hack it	Err	bitreich.org	70
i+Example with clisp : 	Err	bitreich.org	70
i 	Err	bitreich.org	70
i-I tried to make it "hacking friendly" so it's very extensible. 	Err	bitreich.org	70
i+`make LISP=clisp`	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+This way, you can easily use a git hook to type make after each change in the repo so your website is automatically updated.	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+# Some hacks you can do	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+I tried to make it "hacking friendly", you can extend if easily. If you have any idea, feel free to contact me or to send patches.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i ## Include some file in the template	Err	bitreich.org	70
i 	Err	bitreich.org	70
i@@ -53,7 +71,7 @@ In **generate-site** function we can load a file, apply the template and save it	Err	bitreich.org	70
i 	Err	bitreich.org	70
i     (generate "somepage.html" (load-file "data/mypage.html"))	Err	bitreich.org	70
i   	Err	bitreich.org	70
i-This will produce the file somepage.html in the output folder	Err	bitreich.org	70
i+This will produce the file **somepage.html** in the output folder.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i  	Err	bitreich.org	70
i # How to use markdown for articles	Err	bitreich.org	70
i@@ -68,6 +86,12 @@ Here is a tip to produce html files from markdown using emacs	Err	bitreich.org	70
i 	Err	bitreich.org	70
i The generator don't do it natively because I didn't want it to have dependencies. You can use what you want to produces the html files.	Err	bitreich.org	70
i 	Err	bitreich.org	70
i-# Known limitation	Err	bitreich.org	70
i+# Known limitations	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+## Use of ~ character	Err	bitreich.org	70
i 	Err	bitreich.org	70
i The application will crash if you use a single "**~**" caracter inside one data structure in **articles.lisp** files. This is due to the format function trying to interpret the ~ symbol while we just one a ~ symbol. This symbol in the others files are automatically replaced by ~~ which produce a single ~. So, if you want to have a "~" as a title/url/author/description/short/date you have to double it. It may be interestind to sanitize it in the tool maybe.	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+## Article without tag	Err	bitreich.org	70
i+	Err	bitreich.org	70
i+You can have a page without a tag associated but in the default template you will have a line under the title which will displays "Tags : " and no tags after.	Err	bitreich.org	70
.