X-Git-Url: https://plomlompom.com/repos/?p=redo-blog;a=blobdiff_plain;f=README.md;h=f16e442ec81aa1475f58fb2bbff1d5356c3e95ad;hp=ac71a90a0a452c511cbf45d61b989324db70021c;hb=4c034ef30bec5f882ef641f06602090aea63408a;hpb=14735771a6f38a0c875cb6908ead5a4d24fbfc48

diff --git a/README.md b/README.md
index ac71a90..f16e442 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,15 @@
 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
 ------------
 
 - redo
 - python3
-- uuidgen
+- uuidgen (Debian package: uuid-runtime)
 - html2text
 - pandoc
 
@@ -25,17 +26,90 @@ run ./add_dir.sh DIRECTORY.
 
 You can then enter the directory and run redo there. This will generate article
 .html files from all .md and .rst files, plus a ./index.html, and a ./feed.xml.
-(Some other metadata files will also be generated: for each article, there will
-also be generated a .uuid and a .intermediate file; furthermore, files with
-metadata used in ./feed.xml and ./index.html will be built and can be edited to
-customize the blog: ./url, ./author, ./uuid, ./title.) 
+These files will be linked to symbolically in a directory ./public/. If you
+provide or edit a file suffixed .links to basename of an article file, these
+links will be added as article-specific linkbacks to the .html file and the feed
+entry.
 
-bugs
-----
+Some metadata files will also be generated below ./metadata/: For each article,
+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, linkback.tmpl. A blog-specific
+UUID and creation date is stored in ./metadata/automatic_metadata
 
-Due to bad shell scripting in ./processor/index.html.do and
-./processor/feed.xml.do (see the FIXME notes there), source files whose names
-contain "$" break the redo processing.
+recipe to remotely manage a redo blog with git
+----------------------------------------------
 
-Oh, and don't create a index.rst oder index.md in the redo-managed directory,
-that will also break things.
+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
+called `blog`:
+
+    cd ~
+    mkdir blog
+    git init --bare blog.git
+    cat << EOF > blog.git/hooks/post-update
+    #!/bin/sh
+    blog_dir=~/blog
+    export GIT_DIR=\$(pwd)
+    export GIT_WORK_TREE="\$blog_dir"
+    git checkout -f
+    cd "\$GIT_WORK_TREE"
+    redo
+    git add metadata/author metadata/url metadata/title metadata/*.tmpl metadata/automatic_metadata
+    count=\$(ls -1 metadata/*.automatic_metadata 2>/dev/null | wc -l)
+    if [ "\$count" != 0 ]; then
+      git add metadata/*.automatic_metadata
+    fi
+    status=\$(git status -s)
+    n_updates=\$(printf "\$status" | grep -vE '^\?\?' | wc -l)
+    if [ "\$n_updates" -gt 0 ]; then
+      git commit -a -m 'Update metadata'
+    fi
+    EOF
+    chmod a+x blog.git/hooks/post-update
+
+Enable management of `~/blog` via redo-blog:
+
+    git clone https://github.com/plomlompom/redo-blog/
+    cd redo-blog/
+    ./add_dir.sh ~/blog
+    mkdir ~/blog/public
+
+Link to the `public` subdirectory from wherever your web server expects your
+public web content to sit:
+
+    ln -s ~/blog/public /var/www/html/blog
+
+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:/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
+
+If successful, the git hook will furthermore commit some ~/blog/metadata/ files
+generated by redo, that can be pulled into the client-side local repository:
+
+    git pull origin master
+
+bugs and peculiarities
+----------------------
+
+Don't create a index.rst or index.md in the redo-managed directory, that will
+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 `=`) used only once in it.
+
+Symbolic links in public/ to removed article pages are currently not removed.