X-Git-Url: https://plomlompom.com/repos/%7B%7Bprefix%7D%7D/balance2?a=blobdiff_plain;f=README.md;h=822c08d594be5e0cc29b3e07acc2a3cdba68a2c4;hb=ff5b37d8bc4cfba8f1db69a279da887accaa0296;hp=f036e86f9e6d2a31ecf48ce7866199d40a591c40;hpb=db90b1dd62031a9b1f05d21b73a47335bc35892c;p=redo-blog

diff --git a/README.md b/README.md
index f036e86..822c08d 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 redo-blog
 =========
 
-small blog system using the redo build system
+small blog system using the redo build system, with blog article files written
+in (pandoc) Markdown or ReStructured Text.
 
 dependencies
 ------------
@@ -28,13 +29,16 @@ You can then enter the directory and run redo there. This will generate article
 These files will be linked to symbolically in a directory ./public/.
 
 Some metadata files will also be generated below ./metadata/: For each article,
-there will be generated a .uuid and a .intermediate file; furthermore, files for
-data used in ./feed.xml and ./index.html will be built there and can be edited
-to customize the blog – namely the files url, author, uuid, title, index.tmpl,
-index_snippet.tmpl, article.tmpl.
+there will be generated a .automatic_metadata (to contain an article's UUID,
+checksum, and creation/modification dates) and a .intermediate file (to contain
+pandoc-formatted article content like title and body); furthermore, files for
+data used in ./feed.xml and ./index.html will, if non-existant, be built there
+and can be edited to customize the blog – namely the files url, author, title,
+index.tmpl, index_snippet.tmpl, article.tmpl. A blog-specific UUID and creation
+date is stored in ./metadata/automatic_metadata
 
-recipe to use server-side with git
-----------------------------------
+recipe to remotely manage a redo blog with git
+----------------------------------------------
 
 On your server, install the dependencies listed above. Then set up a repository
 for your blog files. Let's assume we want it to sit in our home directory and be
@@ -46,8 +50,8 @@ called `blog`:
     cat << EOF > blog.git/hooks/post-update
     #!/bin/sh
     BLOGDIR=~/blog
-    GIT_WORK_TREE=$BLOGDIR git checkout -f
-    cd $BLOGDIR
+    GIT_WORK_TREE=\$BLOGDIR git checkout -f
+    cd \$BLOGDIR
     redo
     EOF
     chmod a+x blog.git/hooks/post-update
@@ -62,25 +66,29 @@ Enable management of `~/blog` via redo-blog:
 Link to the `public` subdirectory from wherever your web server expects your
 public web content to sit:
 
-    link -s ~/blog/public /var/www/html/blog
+    ln -s ~/blog/public /var/www/html/blog
 
-Client-side, do this:
+Client-side, do this (you obviously need to customize this code; at least
+replace the username `user` and the server name `example.org`):
 
     cd ~
     git init blog
     cd blog
-    git remote add origin ssh://user@example.org:~/blog.git
+    git remote add origin ssh://user@example.org:/home/user/blog.git
     mkdir metadata
     echo 'https://example.org/blog/' > metadata/url
     git add metadata/url
     git commit -m 'set up blog metadata'
     git push origin master
 
-bugs
-----
+bugs and peculiarities
+----------------------
 
 Don't create a index.rst or index.md in the redo-managed directory, that will
 break things.
 
-Running redo without a single blog entry source file (.md or .rst) in the
-directory will also break things.
+The article title is derived in .md files from a first line prefixed with `%`,
+while all other headings are treated as sub-headings. In .rst files, the title
+is derived from a heading that must be at the top of the document, and be of an
+adornment style (such as underlining with `=`) that must be used only once in
+it.