1 @c -*- coding: utf-8; mode: texinfo; -*-
6 * Introduction to website work::
7 * Uploading and security::
8 * Debugging website and docs locally::
9 * Translating the website::
13 @node Introduction to website work
14 @section Introduction to website work
16 The website is @emph{not} written directly in HTML;
17 instead, the source is Texinfo, which is then generated into HTML,
18 PDF, and Info formats. The sources are
21 Documentation/web.texi
22 Documentation/web/*.texi
25 Unless otherwise specified, follow the instructions and policies
26 given in @ref{Documentation work}. That chapter also contains a
27 quick introduction to Texinfo; consulting an external Texinfo
28 manual should be not necessary.
30 @subheading Exceptions to the documentation policies
35 Sectioning: the website only uses chapters and sections; no
36 subsections or subsubsections.
39 @@ref@{@}s to other manuals (@@ruser, @@rlearning, etc): you can't
40 link to any pieces of automatically generated documentation, like
41 the IR or certain NR appendices.
44 The bibliography in Community->Publications is generated automatically
45 from @file{.bib} files; formatting is done automatically by
52 For anything not listed here, just follow the same style as the
53 existing website texinfo files.
58 @node Uploading and security
59 @section Uploading and security
61 @subheading Overall idea
63 To reduce the CPU burden on the shared host (as well as some
64 security concerns), we do not compile all of LilyPond. The
65 website build process runs @code{texi2html}, but all media files
66 (be they graphical @code{lilypond} output, photos of people, or
67 pdfs) are copied from the @code{$LILYPOND_WEB_MEDIA_GIT}
70 All scripts and makefiles used for the website build are run from
71 a @qq{trusted} copy. Any modification to those files in git needs
72 a human to review the changes (after they have been made in git)
73 before they are used on the server.
76 @subheading Building the website (quick local)
78 Initial setup: make sure that you have the environment variables
79 @code{$LILYPOND_GIT}, @code{$LILYPOND_BUILD_DIR} and
80 @code{$LILYPOND_WEB_MEDIA_GIT} set up correctly. For more
81 information, see @ref{Environment variables}.
86 cd $LILYPOND_BUILD_DIR
90 The website is in @file{out-website/website/index.html}.
93 @subheading Building the website (exactly as on the server)
95 @subsubheading Setting up (exactly as on the server)
97 Initial setup: you still need @code{$LILYPOND_GIT} and
98 @code{$LILYPOND_WEB_MEDIA_GIT}.
100 Once that's done, create:
103 mkdir -p $HOME/lilypond/
104 mkdir -p $HOME/lilypond/bin/
105 mkdir -p $HOME/lilypond/cron/
106 mkdir -p $HOME/lilypond/trusted-scripts/
109 The add these files to @file{$HOME/lilypond/bin/}:
111 Update git repositories:
119 git merge origin/master
120 cd $LILYPOND_WEB_MEDIA_GIT
122 git merge origin/master
126 Check for any updates to trusted scripts / files:
132 DEST=$HOME/lilypond/trusted-scripts
133 diff -u $DEST/website.make \
134 $LILYPOND_GIT/make/website.make
135 diff -u $DEST/lilypond-texi2html.init \
136 $LILYPOND_GIT/Documentation/lilypond-texi2html.init
137 diff -u $DEST/extract_texi_filenames.py \
138 $LILYPOND_GIT/scripts/build/extract_texi_filenames.py
139 diff -u $DEST/create-version-itexi.py \
140 $LILYPOND_GIT/scripts/build/create-version-itexi.py
141 diff -u $DEST/create-weblinks-itexi.py \
142 $LILYPOND_GIT/scripts/build/create-weblinks-itexi.py
143 diff -u $DEST/mass-link.py \
144 $LILYPOND_GIT/scripts/build/mass-link.py
145 diff -u $DEST/website_post.py \
146 $LILYPOND_GIT/scripts/build/website_post.py
147 diff -u $DEST/bib2texi.py \
148 $LILYPOND_GIT/scripts/build/bib2texi.py
149 diff -u $DEST/langdefs.py \
150 $LILYPOND_GIT/python/langdefs.py
151 diff -u $DEST/lilypond.org.htaccess \
152 $LILYPOND_GIT/Documentation/web/server/lilypond.org.htaccess
153 diff -u $DEST/website-dir.htaccess \
154 $LILYPOND_GIT/Documentation/web/server/website-dir.htaccess
158 If the changes look ok, make them trusted:
164 DEST=$HOME/lilypond/trusted-scripts
165 cp $LILYPOND_GIT/make/website.make \
167 cp $LILYPOND_GIT/Documentation/lilypond-texi2html.init \
168 $DEST/lilypond-texi2html.init
169 cp $LILYPOND_GIT/scripts/build/extract_texi_filenames.py \
170 $DEST/extract_texi_filenames.py
171 cp $LILYPOND_GIT/scripts/build/create-version-itexi.py \
172 $DEST/create-version-itexi.py
173 cp $LILYPOND_GIT/scripts/build/create-weblinks-itexi.py \
174 $DEST/create-weblinks-itexi.py
175 cp $LILYPOND_GIT/scripts/build/mass-link.py \
177 cp $LILYPOND_GIT/scripts/build/website_post.py \
178 $DEST/website_post.py
179 cp $LILYPOND_GIT/scripts/build/bib2texi.py \
181 cp $LILYPOND_GIT/python/langdefs.py \
183 cp $LILYPOND_GIT/Documentation/web/server/lilypond.org.htaccess \
184 $DEST/lilypond.org.htaccess
185 cp $LILYPOND_GIT/Documentation/web/server/website-dir.htaccess \
186 $DEST/website-dir.htaccess
197 BUILD=$HOME/lilypond/build-website
200 cp $HOME/lilypond/trusted-scripts/website.make .
202 make -f website.make WEBSITE_ONLY_BUILD=1 website
203 rsync -raO $BUILD/out-website/website/ $DEST/website/
204 cp $BUILD/out-website/pictures $DEST
205 cp $BUILD/out-website/.htaccess $DEST
209 Then in the @file{cronjob/} directory, put the cronjob to automate
210 the trusted portions:
212 @warning{@code{cron} will not inherit environment variables from
213 your main setup, so you must re-define any variables inside your
218 # website-rebuild.cron
219 LILYPOND_GIT= ... fill this in
220 LILYPOND_WEB_MEDIA_GIT= ... fill this in
222 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
223 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
227 As the final stage of the setup, run your @code{copy-from-git.sh}
228 script, assuming that you trust the current state of scripts in
231 @subsubheading Normal maintenance
233 When there is a change to the build scripts and/or website
234 makefile, log in to the server (or your own home machine if you're
235 testing this there), and do
242 After reviewing the changes carefully, you can update the trusted
243 scripts with @code{copy-from-git.sh}.
246 @subsubheading Building the website (exactly as on the server)
248 Run @code{make-website.sh}; the final version ends up in
251 On the actual server, the website is generated hourly by user
252 @code{graham} the host @code{lilypond.org}. You can set up the
256 crontab $HOME/lilypond/website-rebuild.cron
260 @subheading Initial setup for new users on actual serve
262 You should symlink your own @file{~/lilypond/} to
263 @file{~graham/lilypond/}
265 If this directory does not exist, make it. Git master should go
266 in @file{~/lilypond/lilypond-git/} but make sure you enable:
269 git config core.filemode false
272 If you have created any files in @file{~graham/lilypond/} then
276 chgrp lilypond ~graham/lilypond/ -R
277 chmod 775 ~graham/lilypond/ -R
282 @subsubheading Additional information
284 Some information about the website is stored in
285 @file{~graham/lilypond/*.txt}; this information should not be
286 shared with people without trusted access to the server.
289 @node Debugging website and docs locally
290 @section Debugging website and docs locally
294 Install Apache (you can use version 2, but keep in mind that the server
295 hosting lilypond.org runs version 1.3). These instructions
296 assume that you also enable @code{mod_userdir}, and use
297 @code{$HOME/public_html} as DocumentRoot (i.e. the root directory of
301 Build the online docs and website:
304 make WEB_TARGETS="offline online" doc
308 This will make all the language variants of the website. To save
309 a little time, just the English version can be made with the
310 command @code{make WEB_LANGS='' website} or the English and (for
311 example) the French with @code{make WEB_LANGS='fr' website}.
314 Choose the web directory where to copy the built stuff.
315 If you already have other web projects in your DocumentRoot and don't
316 need to test the @file{.htaccess} file, you can copy to
317 @code{~/public_html/lilypond.org}. Otherwise you'd better copy
318 to @code{~/public_html}.
319 It's highly recommended to have your build dir and web dir on the
323 Add the directory for the online documentation:
326 mkdir -p ~/public_html/doc/v2.19/
329 You may want to add also the stable documentation in
330 @code{~/public_html/doc/v2.18/}, extracting the contents of the html
331 directory present in the tarball available in @rweb{All}. Just in case
332 you want to test the redirects to the stable documentation.
335 Copy the files with rsync:
338 rsync -av --delete out-website/website ~/public_html/
339 cp out-website/.htaccess ~/public_html
340 rsync -av --delete out-www/online-root/ ~/public_html/doc/v2.19/
346 @node Translating the website
347 @section Translating the website
349 As it has much more audience, the website should be translated before
350 the documentation; see @ref{Translating the documentation}.
352 In addition to the normal documentation translation practices,
353 there are a few additional things to note:
358 Build the website with:
365 however, please note that this command is not designed for being
366 run multiple times. If you see unexpected output (mainly the page
367 footers getting all messed up), then delete your
368 @file{out-website} directory and run @code{make website} again.
371 Some of the translation infrastructure is defined in python files;
372 you must look at the @code{### translation data} sections in:
375 scripts/build/create-weblinks-itexi.py
376 scripts/build/website_post.py
380 Translations are not included by default in @code{make website}.
381 To test your translation, edit the @code{WEB_LANGUAGES =} line in
382 @file{python/langdefs.py}. You will need to copy this updated
383 script to @code{$LILYPOND_BUILD_DIR/python/out}.
385 Do not submit a patch to add your language to this file unless
386 @code{make website} completes with fewer than 5 warnings.
389 Links to manuals are done with macros like
390 @code{@@manualDevelLearningSplit}. To get translated links, you
391 must change that to @code{@@manualDevelLearningSplit-es} (for
392 es/Spanish translations, for example).