i~data/articles.lisp Improve readability. - 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 1c586b79e894959621e9c618a18974c2f34fa5d5 /scm/cl-yag/commit/1c586b79e894959621e9c618a18974c2f34fa5d5.gph bitreich.org 70
1parent e2d4f830fa5c7fa15180caa3f3bd58ed8c4c9dfc /scm/cl-yag/commit/e2d4f830fa5c7fa15180caa3f3bd58ed8c4c9dfc.gph bitreich.org 70
hAuthor: lambda <lambda@fnord.one> URL:mailto:lambda@fnord.one bitreich.org 70
iDate: Wed, 22 Nov 2017 16:26:49 +0100 Err bitreich.org 70
i Err bitreich.org 70
i~data/articles.lisp Improve readability. Err bitreich.org 70
i Err bitreich.org 70
i+data/README.md Err bitreich.org 70
i Cover the old lisp-application tradition and make cl-yag Err bitreich.org 70
i self-documenting in another way: By displaying it's own README as a post. :-) Err bitreich.org 70
i Err bitreich.org 70
i-data/2.md Err bitreich.org 70
i Remove data/2.md Err bitreich.org 70
i Use README as another example-entry: Err bitreich.org 70
i Err bitreich.org 70
iStatus of this commit: Suggestion Err bitreich.org 70
i Err bitreich.org 70
iDiffstat: Err bitreich.org 70
i D data/2.md | 1 - Err bitreich.org 70
i A data/README.md | 108 +++++++++++++++++++++++++++++++ Err bitreich.org 70
i M data/articles.lisp | 49 ++++++++++++++++++------------- Err bitreich.org 70
i Err bitreich.org 70
i3 files changed, 137 insertions(+), 21 deletions(-) Err bitreich.org 70
i--- Err bitreich.org 70
1diff --git a/data/2.md b/data/2.md /scm/cl-yag/file/data/2.md.gph bitreich.org 70
i@@ -1 +0,0 @@ Err bitreich.org 70
i-**hello in bold** Err bitreich.org 70
1diff --git a/data/README.md b/data/README.md /scm/cl-yag/file/data/README.md.gph bitreich.org 70
i@@ -0,0 +1,108 @@ Err bitreich.org 70
i+# Introduction 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. Currently, cl-yag can generate **gopher** and **html** website. Err bitreich.org 70
i+ Err bitreich.org 70
i+**It needs a Common Lisp interpreter and a markdown-to-html export tool (like multimarkdown).** Err bitreich.org 70
i+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+**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+As a "demo", there is [my website](https://dataswamp.org/~solene/) using cl-yag for html version, and [my gopher](gopher://perso.pw) for gopher version. 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 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}.md** : contains the article using markdown syntax that will be used when exported Err bitreich.org 70
i++ **output/** : Err bitreich.org 70
i+ + **gopher/** : contains the exported website for gopher Err bitreich.org 70
i+ + **html/** : contains the exported website in html Err bitreich.org 70
i+ Err bitreich.org 70
i+# Usage Err bitreich.org 70
i+ Err bitreich.org 70
i+## Configuration Err bitreich.org 70
i+ Err bitreich.org 70
i+In data/articles.lisp there is a ***config*** variable with the following fields : Err bitreich.org 70
i+ Err bitreich.org 70
i++ **:webmaster** : The name of the default author, this is the name used when **:author** is omitted Err bitreich.org 70
i++ **:title** : The title of the webpage Err bitreich.org 70
i++ **:description** : This text is used in the *description* field of the Atom RSS Err bitreich.org 70
i++ **:url** : This is the full url of the blog with the final slash. If the url contains a ~ it should be doubled (e.g. : https://mydomain/~~user/ is a valid url) Err bitreich.org 70
i++ **:rss-item-number** : This is the number of RSS items you want to published when you generate the files, it will publish the last N articles Err bitreich.org 70
i++ **html** : t to export html website / nil to disable Err bitreich.org 70
i++ **gopher** : t to export gopher website / nil to disable Err bitreich.org 70
i++ **gopher-path** : this is the full path of the directory to access your gopher hole Err bitreich.org 70
i++ **gopher-server**: hostname of the gopher server because gopher doesn't have relative links like html, so you need to know where you put your files Err bitreich.org 70
i++ **gopher-port** : tcp port of the gopher server, 70 is the default port, it's included in every link as explained in gopher-server 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 (you can do it in one line, as you prefer) Err bitreich.org 70
i+ 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. 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). The Gopher website will be generated inside **output/gopher** and the html will be generated in **output/html**. Err bitreich.org 70
i+ Err bitreich.org 70
i+**/!\ Linux users /!\ ** you should use **bmake** (bsd make) because the Makefile isn't compatible with gmake (gnu make) which is the default in Linux. Err bitreich.org 70
i+ Err bitreich.org 70
i+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+Example with clisp : Err bitreich.org 70
i+ 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+Here is an example code if you want to include a page in the template Err bitreich.org 70
i+ Err bitreich.org 70
i++ Add a string for the replacement to occure, like %%Panel%% in **template/layout.tpl** (because we want the panel on every page) Err bitreich.org 70
i++ In **generator.lisp** modify the function *generate-layout* to add "**(template "%%Panel%%" (load-file "template/panel.tpl"))**" after one template function call Err bitreich.org 70
i++ Create **template/panel.tpl** with the html Err bitreich.org 70
i+ Err bitreich.org 70
i+(note : you can also directly add your text inside the layout template file instead of including another file) Err bitreich.org 70
i+ Err bitreich.org 70
i+## Add a new specific page Err bitreich.org 70
i+ Err bitreich.org 70
i+You may want to have some dedicated page for some reason, reusing the website layout, which is not the index nor an article. Err bitreich.org 70
i+ Err bitreich.org 70
i+In **generate-site** function we can load a file, apply the template and save it in the output. It may look like this 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+ 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
1diff --git a/data/articles.lisp b/data/articles.lisp /scm/cl-yag/file/data/articles.lisp.gph bitreich.org 70
i@@ -1,30 +1,39 @@ Err bitreich.org 70
i-;; WARNING caracter "~" must be escaped when used in this file Err bitreich.org 70
i-;; you have to type ~~ for one ~ to escape it Err bitreich.org 70
i+;; MIND: The tilde character "~" must be escaped like this '~~' to use it as a literal. Err bitreich.org 70
i Err bitreich.org 70
i Err bitreich.org 70
i-;; define informations about your blog Err bitreich.org 70
i-;; used for the RSS generation and some variables replacements in the layout Err bitreich.org 70
i+;; Define Your Webpage Err bitreich.org 70
i+ Err bitreich.org 70
i (defvar *config* Err bitreich.org 70
i (list Err bitreich.org 70
i- :webmaster "Your author name here" Err bitreich.org 70
i- :title "Your blog title here" Err bitreich.org 70
i- :description "Yet another website on the net" Err bitreich.org 70
i- :url "https://my.website/~~user/"; ;; the trailing slash is mandatory, rss links will fails without it Err bitreich.org 70
i- :rss-item-number 10 ;; we want 10 items in our RSS feed Err bitreich.org 70
i- :html t ;; t to export html website / nil to disable Err bitreich.org 70
i- :gopher t ;; t to export gopher website / nil to disable Err bitreich.org 70
i- :gopher-path "/user" ;; the absolute path of your gopher directory Err bitreich.org 70
i- :gopher-server "my.website" ;; hostname of the gopher server Err bitreich.org 70
i- :gopher-port "70" ;; tcp port of the gopher server, 70 usually Err bitreich.org 70
i+ :webmaster "Your autor name here" Err bitreich.org 70
i+ :title "Put youre website's title here." Err bitreich.org 70
i+ :description "Yet another website on the net" Err bitreich.org 70
i+ :url "https://my.website/~~user/"; ;; the trailing slash is mandatory! RSS links will fail without it. Notice the '~~' to produce a literal '~' Err bitreich.org 70
i+ :rss-item-number 10 ;; limit total amount of items in RSS feed to 10 Err bitreich.org 70
i+ :html t ;; 't' to enable export to a html website / 'nil' to disable Err bitreich.org 70
i+ :gopher t ;; 't' to enable export to a gopher website / 'nil' to disable Err bitreich.org 70
i+ :gopher-path "/user" ;; absolute path of your gopher directory Err bitreich.org 70
i+ :gopher-server "my.website" ;; hostname of the gopher server Err bitreich.org 70
i+ :gopher-port "70" ;; tcp port of the gopher server, 70 usually Err bitreich.org 70
i )) Err bitreich.org 70
i Err bitreich.org 70
i-;; describes articles (ordered on the website as they are displayed here, the first in list is the top of the website) Err bitreich.org 70
i-;; exemple => (list :id "4" :date "2015-05-04" :title "The article title" :author "Me" :tiny "Short description for home page") Err bitreich.org 70
i-;; :author can be omitted and will be replaced by webmaster value Err bitreich.org 70
i-;; :tiny can be omitted and will be replaced by the full article text Err bitreich.org 70
i+ Err bitreich.org 70
i+ Err bitreich.org 70
i+ Err bitreich.org 70
i+ Err bitreich.org 70
i+;; Define your articles and their display-order on the website in *articles* below. Err bitreich.org 70
i+;; Display Order is 'lifo', i.e. the top entry in this list gets displayed as the topmost entry. Err bitreich.org 70
i+;; Err bitreich.org 70
i+;; An Example Of A Minimal Definition: Err bitreich.org 70
i+;; (list :id "4" :date "2015-05-04" :title "The article title" :author "Me" :tiny "Short description for home page") Err bitreich.org 70
i+;; Err bitreich.org 70
i+;; A Note On Keywords: Err bitreich.org 70
i+;; :author can be omitted. If so, it's value gets replaced by the value of :webmaster. Err bitreich.org 70
i+;; :tiny can be omitted. If so, the article's full text gets displayed on the all-articles view. (most people don't want this.) Err bitreich.org 70
i+ Err bitreich.org 70
i (defvar *articles* Err bitreich.org 70
i (list Err bitreich.org 70
i- (list :id "2" :date "30 April 2016" :tag "lisp" :title "Another message" :short "New version available") Err bitreich.org 70
i- (list :id "1" :date "29 April 2016":tag "pony code" :title "My first message" :short "This is my first message" :author "Solène") Err bitreich.org 70
i+ (list :id "README" :date "20 May 2016" :tag "cl-yag" :title "README" :author "Solène" :short "cl-yag is documenting itself." :tiny "cl-yag's README") Err bitreich.org 70
i+ (list :id "1" :date "29 April 2016":tag "pony code" :title "My first message" :short "This is my first message" :author "Solène" :tiny "Read more") Err bitreich.org 70
i )) Err bitreich.org 70
i Err bitreich.org 70
.
Response:
text/plain