@c -*- coding: utf-8; mode: texinfo; -*- @node Website work @chapter Website work @menu * Introduction to website work:: * Uploading and security:: * Debugging website and docs locally:: * Translating the website:: @end menu @node Introduction to website work @section Introduction to website work 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 @example Documentation/web.texi Documentation/web/*.texi @end example 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. @item The bibliography in Community->Publications is generated automatically from @file{.bib} files; formatting is done automatically by @file{texi-web.bst}. @item @dots{} @item For anything not listed here, just follow the same style as the existing website 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/} @subheading Initial setup You should symlink your own @file{~/lilypond/} to @file{~graham/lilypond/} If this directory does not exist, make it. Git master should go in @file{~/lilypond/lilypond-git/} but make sure you enable: @example git config core.filemode false @end example If you have created any files in @file{~graham/lilypond/} then please run: @example chgrp lilypond ~graham/lilypond/ -R chmod 775 ~graham/lilypond/ -R @end example 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. You need to upload them, and if they ever change, a user in the @code{lilypond} group must upload them to @file{~graham/lilypond/media} on the host. Upload latest pictures/ and ly-examples/ (local script): @warning{You may need to change a number of items in the below 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:lilypond/media/pictures rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples @end verbatim @subheading Normal maintenance Get latest source code: @verbatim ### update-git.sh #!/bin/sh cd $HOME/lilypond/lilypond-git 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/lilypond/lilypond-git 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/bib2texi.py $GIT/scripts/build/bib2texi.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/lilypond/lilypond-git 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/scripts/build/bib2texi.py $DEST/bib2texi.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/ BUILD=$HOME/lilypond/build-website mkdir -p $BUILD cd $BUILD cp $HOME/lilypond/trusted-scripts/website.make . make -f website.make WEBSITE_ONLY_BUILD=1 website rsync -raO $BUILD/out-website/website/ $DEST/website/ cp $BUILD/out-website/pictures $DEST cp $BUILD/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 @subsubheading Additional information Some information about the website is stored in @file{~graham/lilypond/*.txt}; this information should not be shared with people without trusted access to the server. @node Debugging website and docs locally @section Debugging website and docs locally @itemize @item Install apache2, or any other http server. These instructions assume that you also enable @code{mod_userdir}, and use @code{$HOME/public_html} as the location. @item Build the online docs and website: @example make WEB_TARGETS="offline online" doc make website @end example @item Move the built stuff into those directories. It's highly recommended to have your build dir and www dir on the same partition. (make @code{$HOME/public_html/} a symlink if necessary) @example mv out-website/website/ $HOME/public_html mv $HOME/public_html/website/pictures $HOME/public_html/ mkdir -p $HOME/public_html/doc/v2.13/ mv out-www/online-root/* $HOME/public_html/doc/v2.13/ @end example @end itemize @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