X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fwebsite-work.itexi;fp=Documentation%2Fcontributor%2Fwebsite-work.itexi;h=bb8c19fe949fc7d4bc8c4e529eea521b5c553105;hb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;hp=0000000000000000000000000000000000000000;hpb=a8c9e8a7ca320ab0df5fd32e717fd62cd7635ce6;p=lilypond.git

diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi
new file mode 100644
index 0000000000..bb8c19fe94
--- /dev/null
+++ b/Documentation/contributor/website-work.itexi
@@ -0,0 +1,280 @@
+@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
+
+
+