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} and @code{$LILYPOND_WEB_MEDIA_GIT} set up
80 correctly. For more information, see @ref{Other repositories}.
85 cd $LILYPOND_GIT/build/
89 The website is in @file{out-website/website/index.html}.
92 @subheading Building the website (exactly as on the server)
94 @subsubheading Setting up (exactly as on the server)
96 Initial setup: you still need @code{$LILYPOND_GIT} and
97 @code{$LILYPOND_WEB_MEDIA_GIT}.
99 Once that's done, create:
102 mkdir -p $HOME/lilypond/
103 mkdir -p $HOME/lilypond/bin/
104 mkdir -p $HOME/lilypond/cron/
105 mkdir -p $HOME/lilypond/trusted-scripts/
108 The add these files to @file{$HOME/lilypond/bin/}:
110 Update git repositories:
118 git merge origin/master
119 cd $LILYPOND_WEB_MEDIA_GIT
121 git merge origin/master
125 Check for any updates to trusted scripts / files:
131 DEST=$HOME/lilypond/trusted-scripts
132 diff -u $DEST/website.make \
133 $LILYPOND_GIT/make/website.make
134 diff -u $DEST/lilypond-texi2html.init \
135 $LILYPOND_GIT/Documentation/lilypond-texi2html.init
136 diff -u $DEST/extract_texi_filenames.py \
137 $LILYPOND_GIT/scripts/build/extract_texi_filenames.py
138 diff -u $DEST/create-version-itexi.py \
139 $LILYPOND_GIT/scripts/build/create-version-itexi.py
140 diff -u $DEST/create-weblinks-itexi.py \
141 $LILYPOND_GIT/scripts/build/create-weblinks-itexi.py
142 diff -u $DEST/mass-link.py \
143 $LILYPOND_GIT/scripts/build/mass-link.py
144 diff -u $DEST/website_post.py \
145 $LILYPOND_GIT/scripts/build/website_post.py
146 diff -u $DEST/bib2texi.py \
147 $LILYPOND_GIT/scripts/build/bib2texi.py
148 diff -u $DEST/langdefs.py \
149 $LILYPOND_GIT/python/langdefs.py
150 diff -u $DEST/lilypond.org.htaccess \
151 $LILYPOND_GIT/Documentation/web/server/lilypond.org.htaccess
152 diff -u $DEST/website-dir.htaccess \
153 $LILYPOND_GIT/Documentation/web/server/website-dir.htaccess
157 If the changes look ok, make them trusted:
163 DEST=$HOME/lilypond/trusted-scripts
164 cp $LILYPOND_GIT/make/website.make \
166 cp $LILYPOND_GIT/Documentation/lilypond-texi2html.init \
167 $DEST/lilypond-texi2html.init
168 cp $LILYPOND_GIT/scripts/build/extract_texi_filenames.py \
169 $DEST/extract_texi_filenames.py
170 cp $LILYPOND_GIT/scripts/build/create-version-itexi.py \
171 $DEST/create-version-itexi.py
172 cp $LILYPOND_GIT/scripts/build/create-weblinks-itexi.py \
173 $DEST/create-weblinks-itexi.py
174 cp $LILYPOND_GIT/scripts/build/mass-link.py \
176 cp $LILYPOND_GIT/scripts/build/website_post.py \
177 $DEST/website_post.py
178 cp $LILYPOND_GIT/scripts/build/bib2texi.py \
180 cp $LILYPOND_GIT/python/langdefs.py \
182 cp $LILYPOND_GIT/Documentation/web/server/lilypond.org.htaccess \
183 $DEST/lilypond.org.htaccess
184 cp $LILYPOND_GIT/Documentation/web/server/website-dir.htaccess \
185 $DEST/website-dir.htaccess
196 BUILD=$HOME/lilypond/build-website
199 cp $HOME/lilypond/trusted-scripts/website.make .
201 make -f website.make WEBSITE_ONLY_BUILD=1 website
202 rsync -raO $BUILD/out-website/website/ $DEST/website/
203 cp $BUILD/out-website/pictures $DEST
204 cp $BUILD/out-website/.htaccess $DEST
208 Then in the @file{cronjob/} directory, put the cronjob to automate
209 the trusted portions:
211 @warning{@code{cron} will not inherit environment variables from
212 your main setup, so you must re-define any variables inside your
217 # website-rebuild.cron
218 LILYPOND_GIT= ... fill this in
219 LILYPOND_WEB_MEDIA_GIT= ... fill this in
221 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
222 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
226 As the final stage of the setup, run your @code{copy-from-git.sh}
227 script, assuming that you trust the current state of scripts in
230 @subsubheading Normal maintenance
232 When there is a change to the build scripts and/or website
233 makefile, log in to the server (or your own home machine if you're
234 testing this there), and do
241 After reviewing the changes carefully, you can update the trusted
242 scripts with @code{copy-from-git.sh}.
245 @subsubheading Building the website (exactly as on the server)
247 Run @code{make-website.sh}; the final version ends up in
250 On the actual server, the website is generated hourly by user
251 @code{graham} the host @code{lilypond.org}. You can set up the
255 crontab $HOME/lilypond/website-rebuild.cron
259 @subheading Initial setup for new users on actual serve
261 You should symlink your own @file{~/lilypond/} to
262 @file{~graham/lilypond/}
264 If this directory does not exist, make it. Git master should go
265 in @file{~/lilypond/lilypond-git/} but make sure you enable:
268 git config core.filemode false
271 If you have created any files in @file{~graham/lilypond/} then
275 chgrp lilypond ~graham/lilypond/ -R
276 chmod 775 ~graham/lilypond/ -R
281 @subsubheading Additional information
283 Some information about the website is stored in
284 @file{~graham/lilypond/*.txt}; this information should not be
285 shared with people without trusted access to the server.
288 @node Debugging website and docs locally
289 @section Debugging website and docs locally
293 Install apache2, or any other http server. These instructions
294 assume that you also enable @code{mod_userdir}, and use
295 @code{$HOME/public_html} as the location.
298 Build the online docs and website:
301 make WEB_TARGETS="offline online" doc
305 This will make all the language variants of the website. To save
306 a little time, just the English version can be made with the
307 command @code{make WEB_LANGS='' website} or the English and (for
308 example) the French with @code{make WEB_LANGS='fr' website}.
311 Move the built stuff into those directories. It's highly
312 recommended to have your build dir and www dir on the same
313 partition. (make @code{$HOME/public_html/} a symlink if
317 mv out-website/website/ $HOME/public_html
318 mv $HOME/public_html/website/pictures $HOME/public_html/
319 mkdir -p $HOME/public_html/doc/v2.13/
320 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
326 @node Translating the website
327 @section Translating the website
329 As it has much more audience, the website should be translated before
330 the documentation; see @ref{Translating the documentation}.
332 In addition to the normal documentation translation practices,
333 there are a few additional things to note:
338 Build the website with:
345 however, please note that this command is not designed for being
346 run multiple times. If you see unexpected output (mainly the page
347 footers getting all messed up), then delete your
348 @file{out-website} directory and run @code{make website} again.
351 Some of the translation infrastructure is defined in python files;
352 you must look at the @code{### translation data} sections in:
355 scripts/build/create-weblinks-itexi.py
356 scripts/build/website_post.py
360 Translations are not included by default in @code{make website}.
361 To test your translation, edit the @code{WEB_LANGUAGES =} line in
362 @file{python/langdefs.py}. You will need to copy this updated
363 script to @code{build/python/out}.
365 Do not submit a patch to add your language to this file unless
366 @code{make website} completes with fewer than 5 warnings.
369 Links to manuals are done with macros like
370 @code{@@manualDevelLearningSplit}. To get translated links, you
371 must change that to @code{@@manualDevelLearningSplit-es} (for
372 es/Spanish translations, for example).