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 apache2, or any other http server. These instructions
295 assume that you also enable @code{mod_userdir}, and use
296 @code{$HOME/public_html} as the location.
299 Build the online docs and website:
302 make WEB_TARGETS="offline online" doc
306 This will make all the language variants of the website. To save
307 a little time, just the English version can be made with the
308 command @code{make WEB_LANGS='' website} or the English and (for
309 example) the French with @code{make WEB_LANGS='fr' website}.
312 Move the built stuff into those directories. It's highly
313 recommended to have your build dir and www dir on the same
314 partition. (make @code{$HOME/public_html/} a symlink if
318 mv out-website/website/ $HOME/public_html
319 mv $HOME/public_html/website/pictures $HOME/public_html/
320 mkdir -p $HOME/public_html/doc/v2.13/
321 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
327 @node Translating the website
328 @section Translating the website
330 As it has much more audience, the website should be translated before
331 the documentation; see @ref{Translating the documentation}.
333 In addition to the normal documentation translation practices,
334 there are a few additional things to note:
339 Build the website with:
346 however, please note that this command is not designed for being
347 run multiple times. If you see unexpected output (mainly the page
348 footers getting all messed up), then delete your
349 @file{out-website} directory and run @code{make website} again.
352 Some of the translation infrastructure is defined in python files;
353 you must look at the @code{### translation data} sections in:
356 scripts/build/create-weblinks-itexi.py
357 scripts/build/website_post.py
361 Translations are not included by default in @code{make website}.
362 To test your translation, edit the @code{WEB_LANGUAGES =} line in
363 @file{python/langdefs.py}. You will need to copy this updated
364 script to @code{$LILYPOND_BUILD_DIR/python/out}.
366 Do not submit a patch to add your language to this file unless
367 @code{make website} completes with fewer than 5 warnings.
370 Links to manuals are done with macros like
371 @code{@@manualDevelLearningSplit}. To get translated links, you
372 must change that to @code{@@manualDevelLearningSplit-es} (for
373 es/Spanish translations, for example).