Mercurial > web-octave
diff README.md @ 126:d851f4f89fb4
Improve Makefile deployment mechanism.
* Makefile: Introduce checks for required tools and especially the Jekyll
version. Explain the deployment in detail.
* README.md: Remove verbose section about deployment to the Makefile.
Update documentation. Remove advertising section.
author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
---|---|
date | Fri, 09 Dec 2016 15:18:41 +0100 |
parents | 22f0158e5848 |
children | 88b2480e271a |
line wrap: on
line diff
--- a/README.md Wed Dec 07 15:22:11 2016 -0800 +++ b/README.md Fri Dec 09 15:18:41 2016 +0100 @@ -20,37 +20,6 @@ ## Development -### What makes this way of development better, than the prior? - -- **Official RSS feeds** are **easily** maintained now **at a single place**: - the `_posts` subdirectory, later accessible via - `https://www.gnu.org/software/octave/feed.xml` and automatically spread - to an arbitrary amount of readers, including almost all below mentioned. - - The Octave News are currently very widespread - (and **individually maintained!**) at: - - https://www.gnu.org/software/octave/ (excerpt for the start page) - - https://www.gnu.org/software/octave/news.html (some archive) - - https://www.gnu.org/software/octave/community-news.html (excerpt for the - Octave GUI) - - https://www.gnu.org/software/octave/fixes-4.0.x.html (here are many more - to come!) - - http://wiki.octave.org/GNU_Octave_Wiki#News (some excerpt, anyone can edit) - -- **Content is content**: Page content is primary written in [Markdown][5], - a lightweight Markup language, thus no nasty forgotten HTML tags, that - make content look ugly for any author of a HTML page. - [Jekyll][6] makes valid HTML from [Markdown][5] content. - -- **Easy maintenance**: Just a single command (see below), and [Jekyll][6] - builds a consistent, up-to-date static page. The only maintenance burden, - as it is today anyway: The [Savannah CVS][3] repository. - -[5]: https://daringfireball.net/projects/markdown/syntax -[6]: https://jekyllrb.com/ - - - ### Getting the sources Anyone is free to clone this development repository, simply type @@ -75,16 +44,21 @@ gem install jekyll pygments.rb +A small prerequisite check is performed, by Typing + + make check_prerequisites + For the responsive webpages, we internally use the [Foundation 5][8] framework. All necessary files are already included inside the [hg development repository][2]. +[6]: https://jekyllrb.com/ [7]: https://rubygems.org/ [8]: http://foundation.zurb.com/sites/docs/v/5.5.3/ -### Building the static website +### Building the static website locally All relevant information for Jekyll to build the static website is located in the file `_config.yml`. @@ -112,71 +86,25 @@ -### Typical development tasks +### Add a new RSS post -- **Add a new RSS post** +Duplicate another post in the subdirectory `_posts` and adjust the filename, +especially the date. - Duplicate another post in the subdirectory `_posts` and - adjust the filename, especially the date. +**Be sure to choose the correct categories!!** - **Be sure to choose the correct categories!!** - - `categories: news` is reserved for release announcements, that are also - displayed inside the GUI. Consider choosing another category like - `categories: other` or alike for less important news. +`categories: news` is reserved for release announcements, that are also +displayed inside the GUI. Consider choosing another category like +`categories: other` or alike for less important news. -## Deploying - -After building the static website from [web-octave][2] into the -the subdirectory `_site` using Jekyll it can be deployed at the -[Savannah CVS][3] repository to become visible to the world. - -Therefore, checkout the [Savannah CVS][3] repository somewhere -outside the [web-octave][2] directory, typing - - export CVS_RSH=ssh - cvs -z3 -d:ext:<Savannah account>@cvs.savannah.gnu.org:/web/octave checkout -P octave +### Deploying the static website online -Now the following steps are required for deployment -(see [here][9] and [here][10] for some introduction to CVS): - -1. **DO THIS CAREFULLY!!!** If unsure, start with 2. - - Remove all previous files in the target directory, - *but no directories at all or CVS related stuff*! - This is due to a [limitation of CVS][11]. - - find <DIR> -type f -not -path "*/CVS/*" -exec rm -f '{}' \; - -2. Now copy the new content of [web-octave][2] subdirectory `_site` into the - [Savannah CVS][3] repository. +For this step you need to have writing permissions to the [Savannah CVS][3] +repository. Usually, it should suffice to type -3. Then in the [Savannah CVS][3] repository: - - cd octave - - 1. Remove all no longer existent files - - cvs remove - - 2. Add all potential new directories to CVS - - find . -type d -not -name "CVS" -exec cvs add '{}' \; + make deploy - 3. Add all potential new files to CVS (the [following command][12] - proved to me fast) - - find . -type f | grep -v CVS | xargs cvs add - - 4. Commit the chages to get online - - cvs commit - -Now everything should be visible to the world. - -[9]: https://savannah.nongnu.org/projects/cvs -[10]: http://www.cs.umb.edu/~srevilak/cvs.html -[11]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69 -[12]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively +if anything doesn't work as expected, look at the provided `Makefile` and +perform the steps on your own manually, if necessary.