# How to ... with SBWG?

## How to install SBWG on a computer or server?

There is no necessary installation routine. You can just unpack the script file, make it executable and run it with Bash. For a more detailed guide see the INSTALL
file.


## How to set up a new website?

SBWG comes with an `examples` directory which contains the source files of a small web site that can be built with SBWG. You can copy this directory and build your
web site according to the example. Please read the INSTALL file for instructions on how to set up a new web site based on the example web site.


## How to post a new blog entry?

Create an entry source file in the `entries` directory. The file should start with tags that provide meta information like the entry's title, creation date,
categories and so on. Everything below that is the content of the entry. There is a more detailed description of the available tags in the "Tags" section in the
README file.

You can create this file from scratch, use the `genentry` script that is included in this package, copy an existing entry file or find your own way of creating new
files locally or on the web server. It's just a text file. There are many possibilities like using templates in your favourite text editor or writing your own
script that generates a new entry.

The next time the web site is generated, the new entry will be included in the weblog view and on the tagpages for the tags that you defined in the entry file.


## How to publish all changes?

After you have created new or changed existing content, you have to re-generate the website. There are different options for (re-)generating only galleries, the
blog, static pages, etc. To re-generate the entire website, use the option `-c` or `--complete`.

`sbwg -c` or `sbwg --complete`

This command will use the current working directory and put the generated output into the default output directory that is specified in the web site's settings file
(`html/` subdirectory inside the input directory by default). You can define the input and output directories with the options `-i` or `--input` and `-o` or
`--output`:

`sbwg -c -i ~/blog -o /var/www/html`

Without the option -v (or --verbose) there will be now output to stdout if sbwg was successful.


## How to find entries on the command line?

You can use all tools you would usually use to search text files on a unix-like system. Here are a few examples that might be useful in certain situations.

0. List all entries with the tag "cat:incomplete".
`grep -l cat:incomplete ../../my_weblog/entries/*`
`grep ^cat:incomplete$ /path/to/website/entries/*`

1. List all entries without a defined creation date.
`grep -L '^created:.*$' entries/*`	
	

2. List all stickied posts.
`grep '^sort:[/(stick|about)/].*$' entries/*`	
`grep -Ei '^(sort|created|edited):[A-Z].*' entries/*`


3. List all entries that are sorted specially (independent of their created and edited dates)
`grep -lEi '^(sort|created|edited):[A-Z].*' entries/*`
`grep -l '^sort:.*$' entries/*`


4. List all entries that have been changed in the last 5 days according to the file information (modification date).
`find entries/ -type f -mtime -7 -print`	


5. List all entries that have been edited according to the `edited:` tags inside them.
(tba)


## How to maintain a development/staging website?

You can make use of the `-o` or `--output` option to place the generated web site in a different directory from what is specified in the web site's settings file. If
both the option and the setting are omitted, the script puts the generated web site in the `html` directory inside the source/input directory. A way to maintain
different output directories without having to type them every time is to use aliases.

Example:

`alias sbwg-live='sbwg -o /var/www/html'

`alias sbwg-dev='sbwg -o "${HOME}/weblog_staging"'


## How to change stylesheets and apply changes or create my own CSS?

Create your own style with the name "mystyle", create a file named `mystyle.css` in the `styles` directory inside your website source directory. Fill it with
whatever styles you would like applied to all of your generated website, then build the website with the option `-s mystyle`.

For example: `sbwg -c -i /path/to/source/dir -s mystyle`

If you want to create a more complex style, you can split the rules into multiple files. Every file with a name starting with the style name followed by a hyphen
and ending in .css will be used as well. So for example you can split your CSS rules into the files `mystyle.css`, `mystyle-colors.css`, `mystyle-galleries.css`,
`mystyle-whatever.css`. All those files will be linked in every generated HTML page.



## How to edit an entry without changing its edited date?

This is entirely useless to current versions of SBWG. It's just not necessary to know or use on SBWG entries anymore. I'm just leaving this here for now because it's
a nice trick in general and I don't know why.

Option 1:
	edit() {> file=$1; mtime=$(stat -c %y "$file"); nano "$file"; touch -d "$mtime" "$file"> }
	edit THE_FILE_YOU_WANT_TO_EDIT
	# Change editor according to your preferance
	# You might want to add this function to your dotfiles ;)

Option 2:
	touch -r ENTRYFILE /tmp/timestamps.tmp
	nano ENTRYFILE
	touch -r /tmp/timestamps.tmp ENTRYFILE
	# Change editor according to your preferances


## How to update the web site after changes without re-generating the entire site?

If you only want to publish the changes in the content of an edited page or entry (no new entry or page needs to be generted and tags have not been changed) then you
can use the options `-p` or `--pages` for pages and `-e` or `--entry` for entries. Using one of these option without an argument will (re-)generate all pages/
entries. Adding the name of an entry/page will only (re-)generate that page/entry.

Examples:

`sbwg -i /path/to/source/dir -e entry_name`
`sbwg -i /path/to/source/dir -e "file name of entry"`
`sbwg -i /path/to/source/dir --entry blog_post_2020-12-24`
`sbwg -i /path/to/source/dir -p "Page Name"`
`sbwg -i /path/to/source/dir --page frontpage`

If other changes have been made to the website source (i.e. changes in tags, new entries or pages), the entire blog needs to be re-generated.

Examples:

`sbwg --complete --input /path/to/source/dir`

or

`sbwg --blog --input /path/to/source/dir`

If you want you could automate this process by regularly executing SBWG so you don't have to run it after every change if it's not important that changes will be
published right away.


## How to make a website that resides in a subdirectory?

This option is not fully implemented, yet. It is not working. Ignore the rest of the answer.

If your web site will not be served from the web server root (i.e. not https://www.example.com/ but https://www.example.com/mywebsite/) then you have to specify its
path when generating the web site using the option `-w` or `--webpath`. The webpath should always be the full path after the domain name to the directory where the
root index.html will be located, including the preceding and trailing slashes.

Examples:

`sbwg -c -i /path/to/source/dir -w /mywebsite/`
`sbwg --complete --input /path/to/source/dir --webpath /mywebsite/`

In this example the website's homepage will be accessible at `https://www.example.com/mywebsite/index.html`.


## How long does it take to generate a website?

The time it takes the script to generate a complete web site depends heavily on the amount of content and number of tags like category and topic tags. The more
entries and tagpages have to be generated, the longer it takes of course. The more authors there are in the entry's headers, the more tagpages and combined tagpages
need to be generated. Generating galleries takes the most time, especially when there are new pictures for which no thumbnails have been generated yet.


## How to share content between otherwise independent web sites?

There are different scenarios how you might want to share content among two web sites.

If you have a weblog with miltiple authors and want to generate a web site that only contains the entries of one of the authors, as an additional web site to the
multi-author site, you can use the `--author` (or `-a`) option.

If you want to share all pages or entries between two web sites you can create a symlink from one `pages/` or `entries/` directory to the other web site's source
directory. Please note that there is no support for sub-directories in pages/ or entries/ yet. So this works only when all pages or entries of both web sites should
always be identical.

If you want to have only some entries or pages form web site mirrored in another web site you can use `ln`, `cp` or `rsync` to link, copy or snyc entries or pages
according to glob patterns. One option to automate this is to save the original files in one web site's source directory and use a hook in the second web site's
settings file to create the copies/links.

Example (use all entries starting with "foo_" from web site also in this web sites):

    hook_entries_start() {
      rm -f "${shellbase}/entries/foo_*"
      cp -s "/path/to/website1/entries/foo_*" "${shellbase}/entries/"
    }

