X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fwebsite-work.itexi;h=774aa4574685314cff40b3949ff875b9ed21c5f5;hb=d7c15e8900cab76cb9b15d03c179507530b42447;hp=3fe7f49f0cfbc51374e2d5e096286e474c898b5f;hpb=3dd2729c9b45d88b531874a342e3b18ef516ded8;p=lilypond.git diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi index 3fe7f49f0c..774aa45746 100644 --- 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 @@ -33,6 +34,11 @@ manual should be not necessary. 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 @@ -42,8 +48,155 @@ 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 / files: + +@verbatim +### check-git.sh +#!/bin/sh +GIT=$HOME/src/lilypond +DEST=$HOME/lilypond/trusted-scripts +diff -u $DEST/website.make $GIT/make/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 +diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py +diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py +diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess +diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess +@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/make/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 +cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py +cp $GIT/scripts/build/website_post.py $DEST/website_post.py +cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess +cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess +@end verbatim + +Build the website: + +@verbatim +### make-website.sh +#!/bin/sh +DEST=$HOME/web/ +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 +cp $HOME/src/build-website/out-website/.htaccess $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}. + +In addition to the normal documentation translation practices, +there are a few additional things to note: + +@itemize + +@item +Build the website with: + +@example +make website +@end example + +@noindent +however, please note that this command is not designed for being +run multiple times. If you see unexpected output (mainly the page +footers getting all messed up), then delete your +@file{out-website} directory and run @code{make website} again. + +@item +Some of the translation infrastructure is defined in python files; +you must look at the @code{### translation data} sections in: + +@example +scripts/build/create-weblinks-itexi.py +scripts/build/website_post.py +@end example + +@item +Translations are not included by default in @code{make website}. +To test your translation, edit the @code{WEB_LANGS} line in +@file{make/website.make}. Do not submit a patch to add your language +to this file unless @code{make website} completes with less than 5 +warnings. + +@item +Links to manuals are done with macros like +@code{@@manualDevelLearningSplit}. To get translated links, you +must change that to @code{@@manualDevelLearningSplit-es} (for +es/Spanish translations, for example). + +@end itemize + + +