Check-in [315d4d02b5]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:update README to be m4-bloggery specific
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:315d4d02b5c6a5e9f2aeda4d0100befc4c56b1f8
User & Date: brandon@invergo.net 2013-02-19 17:46:45
Context
2013-02-19
17:47
fix missing paren in new_post template check-in: feb27ee76d user: brandon@invergo.net tags: trunk
17:46
update README to be m4-bloggery specific check-in: 315d4d02b5 user: brandon@invergo.net tags: trunk
17:05
change atom generator check-in: 3e2ea030d3 user: brandon@invergo.net tags: trunk
Changes

Changes to README.md.

     1         -# GNU Make and M4 Website Bakery
            1  +# m4-bloggery
            2  +
            3  +m4-bloggery is a simple static site generator that depends only on m4,
            4  +Make and a Markdown parser.  It is based on m4-bakery[1] by Datagrok.
            5  +m4-bloggery adds some extra features for a blog-oriented site, namely
            6  +a blog/news index and an Atom XML feed. 
            7  +
            8  +# Requirements
            9  +
           10  +* Make (probably only the GNU variant; I haven't checked if it depends
           11  +  on any GNU extensions)
           12  +* M4 (any version will probably work)
           13  +* Any command-line program to convert Markdown into HTML (optional)
           14  +
           15  +# Usage
           16  +
           17  +## Creating pages
           18  +
           19  +Some example files are provided in the tree.  It is easiest to work
           20  +with Markdown files, so I'll only talk about that here.  To create a
           21  +new page, simply create a file under the `src/` directory with the
           22  +`.md.m4` extension. Inside, you can define several macros:
           23  +
           24  +* TITLE: the title of the page
           25  +* DATE: the date the page was created
           26  +* UPDATE: the date that a page was updated
           27  +* TAGS: a space-separated list of tags for the page (note: I have not
           28  +        implemented a proper tagging system)
           29  +* BODY: the main text of the page
           30  +
           31  +You define a macro by putting some text in between a nested pair of
           32  +parentheses and braces, with the text surrounded by quotes.  So, to
           33  +define the title of the page, you would add:
           34  +
           35  +    TITLE({"This is my site"})
           36  +
           37  +The exception is the BODY macro, which requires an extra nested pair
           38  +of braces and quotes:
           39  +
           40  +    BODY({"{"
           41  +        This is the main text of this page, which is boring.
           42  +    "}"})
           43  +
           44  +Why do you have to do that?  Eh...the vagaries of quoting in m4. 
           45  +
           46  +## Creating blog/news posts
           47  +
           48  +There is a shortcut to creating a new post: the "new-post" Make
           49  +target.  You must supply a value to the TITLE variable on the
           50  +command-line when you use this target:
           51  +
           52  +    $ make new-post TITLE="How amazingly simple"
           53  +
           54  +## Generating the site
           55  +
           56  +Once you have created all of your pages, simply make the `all` target:
           57  +
           58  +    $ make all
           59  +
           60  +This will first run the pages through Markdown to generate the HTML
           61  +and then it runs them through m4 to construct full pages out of the
           62  +layouts.  The generated site will be moved into a directory called
           63  +`dst`.  Whatever directory structure you have under `src` will be
           64  +simply mirrored to `dst`.  In the end, the contents of `dst` are to be
           65  +served.
           66  +
           67  +## Deployment
           68  +
           69  +You can automatically deploy the website to your server via rsync
           70  +using the `deploy` make target:
           71  +
           72  +    $ make deploy
           73  +
           74  +You should modify the file `auth.mk` to include your username
           75  +(user@server) and the document root where things will be uploaded:
           76  +
           77  +    SSH_USER = me@myserver.com
           78  +    DOC_ROOT = ~/public_html
           79  +
           80  +# Customization
           81  +
           82  +You can customize this to your heart's desire.  I hate web design so
           83  +the default design is rather minimalist.  Modify the files in the
           84  +`templates` directory to change the site structure (particularly
           85  +`main.html.m4`).  Notice all of those `m4_divert()` calls?  m4 uses
           86  +those to determine where and how to merge the various templates.  You
           87  +shouldn't need to change those.
           88  +
           89  +You can modify the css under the `src/css` sub-directory.
     2     90   
     3         -One of the first hacks that I was really proud of was this website-baking system I built in late 1999 with some venerable old Unix tools, [GNU Make](http://www.gnu.org/software/make/) and [GNU m4](http://www.gnu.org/software/m4/). The article [Using M4 to write HTML](http://web.archive.org/web/19980529230944/http://www.linuxgazette.com/issue22/using_m4.html) by Bob Hepple was my original inspiration, but I think I was able to surpass the utility of the examples given therein.
           91  +# Example Sites
     4     92   
     5         -**You're currently viewing the 'master' branch of this repository.** I've tried to include here many interesting features and ideas for how this technique might be used, including the use of [Pandoc](http://johnmacfarlane.net/pandoc/) for markdown-format source files. I've tried to include a generous amount of internal documentation and comments as well, but it may yet be a lot to absorb at once. To more easily understand what's going on here, be sure to take a look at the 'simple' branch of the repository: http://github.com/datagrok/m4-bakery/tree/simple
           93  +http://brandon.invergo.net
     6     94   
     7         -## Site Baking
     8         -
     9         -"Website baking" is the pattern of building from templates a mostly- or completely-static website that requires no special software to serve. Baking a website provides huge advantages when it can be employed, because they:
           95  +# Contact
    10     96   
    11         -- have fewer vectors for break-ins, 
    12         -- easily scale to handle massive amounts of traffic, and 
    13         -- may be hosted on commodity hardware or the cheapest of web hosting services.
    14         -
    15         -Of course, with no processing occurring on the server end, it's not possible to host user-interactive features like comments sections, authentication, or e-commerce systems. These days however, many people use third-party tools like [Disqus](http://disqus.com) to implement these features anyway.
    16         -
    17         -In short, if you're not using any of the dynamic features of your web hosting service, you might as well make the whole site static.
           97  +Brandon Invergo <brandon [at] invergo [dot] net
    18     98   
    19         -## GNU Make and GNU M4
    20         -
    21         -That is of course only an argument for building static websites. Doing it in this _particular_ way may be... ill-advised.
    22         -
    23         -Though m4 may be venerable and may come pre-installed on several modern Unix platforms, it brings along a notoriously cumbersome syntax for defining and calling macros, escaping, quoting, and other things. Sendmail's configuration system serves as a cautionary tale, as it was built upon m4 and is legendary for being obtuse. Employing m4 may be an exercise in masochism.
    24         -
    25         -The difficulty in employing m4 may contribute to my pride in having built a useful tool with it a whole decade+ ago. I hope that this repository will yet serve as an instructive example of how to 'bake' a website using ubiquitous Unix tools, even if every single user ends up swapping out m4 for modern template software, e.g. [Jinja](http://jinja.pocoo.org/).
    26         -
    27         -## Features
    28         -
    29         -- The HTML template is wrapped around .html.m4 files automatically; no boilerplate is necessary in the source file.
    30         -- The HTML template is a single file, not a separate header and footer.
    31         -- Files named .m4 don't get the template, but still get interpreted by m4.
    32         -- Any files not named '.m4' don't get interpreted by m4; they are copied verbatim.
    33         -- Macros defined in source .html.m4 files will be expanded in the template. This lets you put complex logic in the template and trigger it from the source file. For example, you could set the page title, toggle a template style, define sidebars, etc.
    34         -- Macros defined in the macros file will be expanded in the source files and the template. You can define macros here that you want to be available everywhere.
           99  +# Footnotes
    35    100   
    36         -## Execution
          101  +[1]  https://github.com/datagrok/m4-bakery
    37    102   
    38         -Beginning with source files like this:
    39         -
    40         -	src/
    41         -	|-- index.html.m4
    42         -	`-- style.css
    43         -
    44         -Along with the Makefile, macros file, and HTML template, running 'make' will
    45         -output:
    46         -
    47         -	install -m 644 -D src/style.css dst/style.css
    48         -	m4 -P macros.m4 src/index.html.m4 template.html.m4 > src/index.html
    49         -	install -m 644 -D src/index.html dst/index.html
    50         -	rm src/index.html
    51         -
    52         -And produce the following structure:
    53         -
    54         -	dst/
    55         -	|-- index.html
    56         -	`-- style.css