Doc: CG: fix website script.

[lilypond.git] / Documentation / contributor / website-work.itexi

diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi
index cb4e0aac9a8c50a494d272dfd03d45dcf03a2ce7..2d85714c8b233a38e12955df44e26166d32db29a 100644 (file)
--- a/Documentation/contributor/website-work.itexi
+++ b/Documentation/contributor/website-work.itexi
@@ -1,9 +1,10 @@
-@c -*- coding: us-ascii; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
 @node Website work
 @chapter Website work
 
 @menu
 * Introduction to website work::  
+* Uploading and security::
 * Translating the website::
 @end menu
 
@@ -11,12 +12,137 @@
 @node Introduction to website work
 @section Introduction to website work
 
-Short answer: don't do it yet.  We're completely revamping the
-website.
+The website is @emph{not} written directly in HTML;
+instead, the source is Texinfo, which is then generated into HTML,
+PDF, and Info formats.  The sources are
 
+@verbatim
+Documentation/web.texi
+Documentation/web/*.texi
+@end verbatim
 
-@node Translating the website
-@section Translating the website
+Unless otherwise specified, follow the instructions and policies
+given in @ref{Documentation work}.  That chapter also contains a
+quick introduction to Texinfo; consulting an external Texinfo
+manual should be not necessary.
+
+@subheading Exceptions to the documentation policies
+
+@itemize
+
+@item
+Sectioning: the website only uses chapters and sections; no
+subsections or subsubsections.
+
+@item
+@@ref@{@}s to other manuals (@@ruser, @@rlearning, etc): you can't
+link to any pieces of automatically generated documentation, like
+the IR or certain NR appendices.
+
+@dots{}
+
+@item
+For anything not listed here, just follow the same style as the
+existing texinfo files.
+
+@end itemize
+
+
+@node Uploading and security
+@section Uploading and security
+
+The website is generated hourly by user @code{graham} the host
+@code{lilypond.org}.  For security reasons, we do not use the
+makefiles and scripts directly from git; copies of the relevant
+scripts are examined and copied to
+@code{~graham/lilypond/trusted-scripts/}
+
+Get latest source code:
+
+@verbatim
+### update-git.sh
+#!/bin/sh
+cd $HOME/src/lilypond
+git fetch origin
+git merge origin/master
+@end verbatim
+
+Check for any updates to trusted scripts:
+
+@verbatim
+### check-git.sh
+#!/bin/sh
+GIT=$HOME/src/lilypond
+DEST=$HOME/lilypond/trusted-scripts
+diff -u $DEST/website.make $GIT/website.make
+diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
+diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
+diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
+diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
+@end verbatim
 
+If the changes look ok, make them trusted:
 
+@verbatim
+### copy-from-git.sh
+#!/bin/sh
+GIT=$HOME/src/lilypond
+DEST=$HOME/lilypond/trusted-scripts
+cp $GIT/website.make $DEST/website.make
+cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
+cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
+cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
+cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
+@end verbatim
+
+Build the website:
+
+@verbatim
+### make-website.sh
+#!/bin/sh
+DEST=$HOME/public_html/
+cd $HOME/src/build-website
+cp $HOME/lilypond/trusted-scripts/website.make .
+
+make -f website.make WEBSITE_ONLY_BUILD=1 website
+rsync -ra $HOME/src/build-website/out-website/website/ $DEST/website/
+cp $HOME/src/build-website/out-website/pictures $DEST
+@end verbatim
+
+Cronjob to automate the trusted portions:
+
+@verbatim
+# website-rebuild.cron
+11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
+22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
+@end verbatim
+
+
+To reduce the CPU burden on the shared host (as well as some
+security concerns), the @file{Documentation/pictures/} and
+@file{Documentation/web/ly-examples/} directories are @strong{not}
+compiled.  If you modify any files in those directories, a user in
+the @code{lilypond} group must upload them to @file{~graham/media}
+on the host.
+
+Upload latest pictures/ and ly-examples/ (local script):
+
+@verbatim
+### upload-lily-web-media.sh
+#!/bin/sh
+BUILD_DIR=$HOME/src/build-lilypond
+
+PICS=$BUILD_DIR/Documentation/pictures/out-www/
+EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
+
+cd $BUILD_DIR
+rsync -a $PICS graham@lilypond.org:media/pictures
+rsync -a $EXAMPLES graham@lilypond.org:ly-examples
+@end verbatim
+
+
+@node Translating the website
+@section Translating the website
 
+As it has much more audience, the website should be translated before
+the documentation; see @ref{Translating the documentation}.