Doc: CG: update git-cl location

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

diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi
index 7e570aca85896bb7f1d3486c118601a5a4d813ba..5842493d8d06ecf0f41f947096fc2fc7f4469331 100644 (file)
--- a/Documentation/contributor/website-work.itexi
+++ b/Documentation/contributor/website-work.itexi
@@ -3,8 +3,9 @@
 @chapter Website work
 
 @menu
 @chapter Website work
 
 @menu

-* Introduction to website work::  
+* Introduction to website work::

 * Uploading and security::
 * Uploading and security::

+* Debugging website and docs locally::

 * Translating the website::
 @end menu
 
 * Translating the website::
 @end menu
 


@@ -16,10 +17,10 @@ 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
 
 instead, the source is Texinfo, which is then generated into HTML,
 PDF, and Info formats.  The sources are
 

-@verbatim
+@example

 Documentation/web.texi
 Documentation/web/*.texi
 Documentation/web.texi
 Documentation/web/*.texi

-@end verbatim
+@end example

 
 Unless otherwise specified, follow the instructions and policies
 given in @ref{Documentation work}.  That chapter also contains a
 
 Unless otherwise specified, follow the instructions and policies
 given in @ref{Documentation work}.  That chapter also contains a


@@ -39,11 +40,17 @@ subsections or subsubsections.
 link to any pieces of automatically generated documentation, like
 the IR or certain NR appendices.
 
 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
 @dots{}
 
 @item
 For anything not listed here, just follow the same style as the

-existing texinfo files.
+existing website texinfo files.

 
 @end itemize
 
 
 @end itemize
 


@@ -51,36 +58,168 @@ existing texinfo files.
 @node Uploading and security
 @section Uploading and security
 
 @node Uploading and security
 @section Uploading and security
 

+@subheading Building the website from scratch for local checking
+
+Initial setup:
+
+Create directories:
+
+@example
+$HOME/lilypond/
+$HOME/lilypond/media/
+$HOME/lilypond/trusted-scripts/
+@end example
+
+To reduce the CPU burden on the shared host (as well as some
+security concerns), the 'Documentation/pictures/' and
+'Documentation/web/ly-examples/' directories are **not** compiled.
+We will do this ourselves right now.
+
+Go to your lilypond build directory.  make doc.
+
+Set up some variables (you'll only do this once:)
+
+@example
+BUILD_DIR=$HOME/lilypond-git
+PICS=$BUILD_DIR/Documentation/pictures/
+EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/
+@end example
+
+Copy files over:
+
+@example
+cp -r $PICS $HOME/lilypond/media/pictures
+cp -r $EXAMPLES $HOME/lilypond/media/ly-examples
+@end example
+
+Get the scripts you need.  First define these variables:
+
+@example
+GIT=$HOME/lilypond-git
+DEST=$HOME/lilypond/trusted-scripts
+@end example
+
+Then do the copying:
+
+@smallexample
+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 smallexample
+
+Delete your build directory (or maybe just rename your build
+directory to build-old).
+
+@example
+cd $HOME/lilypond
+@end example
+
+Run
+
+@example
+make -f ../lilypond-git/make/website.make WEBSITE_ONLY_BUILD=1 \
+  TOP_SRC_DIR=$HOME/lilypond-git/ \
+  PYTHONPATH=$HOME/lilypond-git/python \
+  TEXI2HTML_PROGRAM=texi2html \
+  website
+@end example
+
+The website should be at:
+
+@example
+$HOME/lilypond/out-website/website/index.html
+@end example
+
+@subheading Building the online website
+

 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/}
 
 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
 Get latest source code:
 
 @verbatim
 ### update-git.sh
 #!/bin/sh

-cd $HOME/src/lilypond
+cd $HOME/lilypond/lilypond-git

 git fetch origin
 git merge origin/master
 @end verbatim
 
 Check for any updates to trusted scripts / files:
 git fetch origin
 git merge origin/master
 @end verbatim
 
 Check for any updates to trusted scripts / files:

-
+@smallexample

 @verbatim
 ### check-git.sh
 #!/bin/sh
 @verbatim
 ### check-git.sh
 #!/bin/sh

-GIT=$HOME/src/lilypond
+GIT=$HOME/lilypond/lilypond-git

 DEST=$HOME/lilypond/trusted-scripts
 DEST=$HOME/lilypond/trusted-scripts

-diff -u $DEST/website.make $GIT/website.make
+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-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/langdefs.py $GIT/python/langdefs.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
 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


@@ -90,18 +229,21 @@ If the changes look ok, make them trusted:
 @verbatim
 ### copy-from-git.sh
 #!/bin/sh
 @verbatim
 ### copy-from-git.sh
 #!/bin/sh

-GIT=$HOME/src/lilypond
+GIT=$HOME/lilypond/lilypond-git

 DEST=$HOME/lilypond/trusted-scripts
 DEST=$HOME/lilypond/trusted-scripts

-cp $GIT/website.make $DEST/website.make
+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/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/python/langdefs.py $DEST/langdefs.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
 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

+@end smallexample

 
 Build the website:
 
 
 Build the website:
 


@@ -109,13 +251,15 @@ Build the website:
 ### make-website.sh
 #!/bin/sh
 DEST=$HOME/web/
 ### make-website.sh
 #!/bin/sh
 DEST=$HOME/web/

-cd $HOME/src/build-website
+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
 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
+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:
 @end verbatim
 
 Cronjob to automate the trusted portions:


@@ -127,27 +271,49 @@ Cronjob to automate the trusted portions:
 @end verbatim
 
 
 @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.
+@subsubheading Additional information

 
 

-Upload latest pictures/ and ly-examples/ (local script):
+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.

 
 

-@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/
+@node Debugging website and docs locally
+@section Debugging website and docs locally

 
 

-cd $BUILD_DIR
-rsync -a $PICS graham@lilypond.org:media/pictures
-rsync -a $EXAMPLES graham@lilypond.org:ly-examples
-@end verbatim
+@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
+
+This will make all the language variants of the website.  To save
+a little time, just the English version can be made with the
+command @code{make WEB_LANGS='' website} or the English and (for
+example) the French with @code{make WEB_LANGS='fr' website}.
+
+@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
 
 
 @node Translating the website


@@ -155,3 +321,50 @@ rsync -a $EXAMPLES graham@lilypond.org:ly-examples
 
 As it has much more audience, the website should be translated before
 the documentation; see @ref{Translating the documentation}.
 
 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_LANGUAGES =} line in
+@file{python/langdefs.py}.  You will need to copy this updated
+script to @code{build/python/out}.
+
+Do not submit a patch to add your language to this file unless
+@code{make website} completes with fewer 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
+
+
+