changeset 91:3269c95e98d9 kai

Some more website development documentation.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Mon, 17 Oct 2016 21:08:49 +0200
parents fbd5bca94df2
children 6f92b43549a4
files README.md
diffstat 1 files changed, 57 insertions(+), 11 deletions(-) [+]
line wrap: on
line diff
--- a/README.md	Mon Oct 17 21:08:23 2016 +0200
+++ b/README.md	Mon Oct 17 21:08:49 2016 +0200
@@ -20,6 +20,37 @@
 
 ## 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
@@ -39,13 +70,12 @@
 
 ### Building requisites
 
-To build the static website, you need to install [Jekyll][5] and a few more
-tools from [Rubygems][6].  Just type
+To build the static website, you need to install [Jekyll][6] and a few more
+tools from [Rubygems][7].  Just type
 
     gem install jekyll jekyll-octicons pygments.rb
 
-[5]: https://jekyllrb.com/
-[6]: https://rubygems.org/
+[7]: https://rubygems.org/
 
 
 
@@ -70,6 +100,22 @@
 and rebuilds the whole static website automatically, as it monitors any
 file changes.
 
+To build the test page, that can be deployed at some subdirectory, e.g.
+`http://www.octave.org/new`, use
+
+    jekyll build --config _config.yml,_config_test.yml
+
+
+
+### Typical development tasks
+
+- **Add a new RSS post**
+
+  Duplicate another post in the subdirectory `_posts` and
+  adjust the filename, especially the date
+
+
+
 
 
 ## Deploying
@@ -85,11 +131,11 @@
     cvs -z3 -d:ext:<Savannah account>@cvs.savannah.gnu.org:/web/octave checkout -P octave
 
 Now the following steps are required for deployment
-(see [here][7] and [here][8] for some introduction to CVS):
+(see [here][8] and [here][9] for some introduction to CVS):
 
 1. 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][9].
+   This is due to a [limitation of CVS][10].
 
        find octave -type f -not -path "*/CVS/*" -exec rm -f '{}' \;
 
@@ -111,7 +157,7 @@
 
           find . -type d -not -name "CVS" -exec cvs add '{}' \;
 
-   3. Add all potential new files to CVS (the [following command][10]
+   3. Add all potential new files to CVS (the [following command][11]
       proved to me fast)
 
           find . -type f | grep -v CVS | xargs cvs add
@@ -122,7 +168,7 @@
 
 Now everything should be visible to the world.
 
-[7]: https://savannah.nongnu.org/projects/cvs
-[8]: http://www.cs.umb.edu/~srevilak/cvs.html
-[9]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69
-[10]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively
+[8]: https://savannah.nongnu.org/projects/cvs
+[9]: http://www.cs.umb.edu/~srevilak/cvs.html
+[10]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69
+[11]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively