1 @c -*- coding: utf-8; mode: texinfo; -*-
6 * Introduction to website work::
7 * Uploading and security::
8 * Translating the website::
12 @node Introduction to website work
13 @section Introduction to website work
15 The website is @emph{not} written directly in HTML;
16 instead, the source is Texinfo, which is then generated into HTML,
17 PDF, and Info formats. The sources are
20 Documentation/web.texi
21 Documentation/web/*.texi
24 Unless otherwise specified, follow the instructions and policies
25 given in @ref{Documentation work}. That chapter also contains a
26 quick introduction to Texinfo; consulting an external Texinfo
27 manual should be not necessary.
29 @subheading Exceptions to the documentation policies
34 Sectioning: the website only uses chapters and sections; no
35 subsections or subsubsections.
38 @@ref@{@}s to other manuals (@@ruser, @@rlearning, etc): you can't
39 link to any pieces of automatically generated documentation, like
40 the IR or certain NR appendices.
43 The bibliography in Community->Publications is generated automatically
44 from @file{.bib} files; formatting is done automatically by
51 For anything not listed here, just follow the same style as the
52 existing website texinfo files.
57 @node Uploading and security
58 @section Uploading and security
60 The website is generated hourly by user @code{graham} the host
61 @code{lilypond.org}. For security reasons, we do not use the
62 makefiles and scripts directly from git; copies of the relevant
63 scripts are examined and copied to
64 @code{~graham/lilypond/trusted-scripts/}
66 @subheading Initial setup
68 You should symlink your own @file{~/lilypond/} to
69 @file{~graham/@/lilypond/}
71 If this directory does not exist, make it. Git master should go
72 in @file{~/lilypond/@/lilypond@/-git/} but make sure you enable:
75 git config core.filemode false
78 If you have created any files in @file{~graham/@/lilypond/} then
82 chgrp lilypond ~graham/lilypond/ -R
83 chmod 775 ~graham/lilypond/ -R
86 To reduce the CPU burden on the shared host (as well as some
87 security concerns), the @file{Documentation/@/pictures/} and
88 @file{Documentation/@/web/@/ly-examples/} directories are
89 @strong{not} compiled. You need to upload them, and if they ever
90 change, a user in the @code{lilypond} group must upload them to
91 @file{~graham/@/media} on the host.
93 Upload latest pictures/ and ly-examples/ (local script):
95 @warning{You may need to change a number of items in the below
99 ### upload-lily-web-media.sh
101 BUILD_DIR=$HOME/src/build-lilypond
103 PICS=$BUILD_DIR/Documentation/pictures/out-www/
104 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
107 rsync -a $PICS graham@lilypond.org:media/pictures
108 rsync -a $EXAMPLES graham@lilypond.org:ly-examples
113 @subheading Normal maintenance
115 Get latest source code:
120 cd $HOME/lilypond/lilypond-git
122 git merge origin/master
125 Check for any updates to trusted scripts / files:
130 GIT=$HOME/lilypond/lilypond-git
131 DEST=$HOME/lilypond/trusted-scripts
132 diff -u $DEST/website.make $GIT/make/website.make
133 diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
134 diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
135 diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
136 diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
137 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
138 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
139 diff -u $DEST/bib2texi.py $GIT/scripts/build/bib2texi.py
140 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
141 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
144 If the changes look ok, make them trusted:
149 GIT=$HOME/lilypond/lilypond-git
150 DEST=$HOME/lilypond/trusted-scripts
151 cp $GIT/make/website.make $DEST/website.make
152 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
153 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
154 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
155 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
156 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
157 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
158 cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
159 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
160 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
169 BUILD=$HOME/lilypond/build-website
172 cp $HOME/lilypond/trusted-scripts/website.make .
174 make -f website.make WEBSITE_ONLY_BUILD=1 website
175 rsync -raO $BUILD/out-website/website/ $DEST/website/
176 cp $BUILD/out-website/pictures $DEST
177 cp $BUILD/out-website/.htaccess $DEST
180 Cronjob to automate the trusted portions:
183 # website-rebuild.cron
184 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
185 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
189 @subsubheading Additional information
191 Some information about the website is stored in
192 @file{~graham/@/lilypond/@/*.txt}; this information should not be
193 shared with people without trusted access to the server.
196 @node Translating the website
197 @section Translating the website
199 As it has much more audience, the website should be translated before
200 the documentation; see @ref{Translating the documentation}.
202 In addition to the normal documentation translation practices,
203 there are a few additional things to note:
208 Build the website with:
215 however, please note that this command is not designed for being
216 run multiple times. If you see unexpected output (mainly the page
217 footers getting all messed up), then delete your
218 @file{out@/-website} directory and run @code{make website} again.
221 Some of the translation infrastructure is defined in python files;
222 you must look at the @code{### translation data} sections in:
225 scripts/build/create-weblinks-itexi.py
226 scripts/build/website_post.py
230 Translations are not included by default in @code{make website}.
231 To test your translation, edit the @code{WEB_LANGS} line in
232 @file{make/@/website@/.make}. Do not submit a patch to add your language
233 to this file unless @code{make website} completes with less than 5
237 Links to manuals are done with macros like
238 @code{@@manualDevelLearningSplit}. To get translated links, you
239 must change that to @code{@@manualDevelLearningSplit-es} (for
240 es/Spanish translations, for example).