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 Building the website from scratch for local checking
70 $HOME/lilypond/trusted-scripts/
73 To reduce the CPU burden on the shared host (as well as some
74 security concerns), the 'Documentation/pictures/' and
75 'Documentation/web/ly-examples/' directories are **not** compiled.
76 We will do this ourselves right now.
78 Go to your lilypond build directory. make doc.
80 Set up some variables (you'll only do this once:)
83 BUILD_DIR=$HOME/lilypond-git
84 PICS=$BUILD_DIR/Documentation/pictures/
85 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/
91 cp -r $PICS $HOME/lilypond/media/pictures
92 cp -r $EXAMPLES $HOME/lilypond/media/ly-examples
95 Get the scripts you need. First define these variables:
98 GIT=$HOME/lilypond-git
99 DEST=$HOME/lilypond/trusted-scripts
105 cp $GIT/make/website.make $DEST/website.make
106 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
107 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
108 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
109 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
110 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
111 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
112 cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
113 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
114 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
117 Delete your build directory (or maybe just rename your build
118 directory to build-old).
127 make -f ../lilypond-git/make/website.make WEBSITE_ONLY_BUILD=1 \
128 TOP_SRC_DIR=$HOME/lilypond-git/ \
129 TEXI2HTML_PROGRAM=texi2html \
133 The website should be at:
136 $HOME/lilypond/out-website/website/index.html
139 @subheading Building the online website
141 The website is generated hourly by user @code{graham} the host
142 @code{lilypond.org}. For security reasons, we do not use the
143 makefiles and scripts directly from git; copies of the relevant
144 scripts are examined and copied to
145 @code{~graham/lilypond/trusted-scripts/}
147 @subheading Initial setup
149 You should symlink your own @file{~/lilypond/} to
150 @file{~graham/lilypond/}
152 If this directory does not exist, make it. Git master should go
153 in @file{~/lilypond/lilypond-git/} but make sure you enable:
156 git config core.filemode false
159 If you have created any files in @file{~graham/lilypond/} then
163 chgrp lilypond ~graham/lilypond/ -R
164 chmod 775 ~graham/lilypond/ -R
167 To reduce the CPU burden on the shared host (as well as some
168 security concerns), the @file{Documentation/pictures/} and
169 @file{Documentation/web/ly-examples/} directories are
170 @strong{not} compiled. You need to upload them, and if they ever
171 change, a user in the @code{lilypond} group must upload them to
172 @file{~graham/lilypond/media} on the host.
174 Upload latest pictures/ and ly-examples/ (local script):
176 @warning{You may need to change a number of items in the below
180 ### upload-lily-web-media.sh
182 BUILD_DIR=$HOME/src/build-lilypond
184 PICS=$BUILD_DIR/Documentation/pictures/out-www/
185 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
188 rsync -a $PICS graham@lilypond.org:lilypond/media/pictures
189 rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples
194 @subheading Normal maintenance
196 Get latest source code:
201 cd $HOME/lilypond/lilypond-git
203 git merge origin/master
206 Check for any updates to trusted scripts / files:
211 GIT=$HOME/lilypond/lilypond-git
212 DEST=$HOME/lilypond/trusted-scripts
213 diff -u $DEST/website.make $GIT/make/website.make
214 diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
215 diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
216 diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
217 diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
218 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
219 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
220 diff -u $DEST/bib2texi.py $GIT/scripts/build/bib2texi.py
221 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
222 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
225 If the changes look ok, make them trusted:
230 GIT=$HOME/lilypond/lilypond-git
231 DEST=$HOME/lilypond/trusted-scripts
232 cp $GIT/make/website.make $DEST/website.make
233 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
234 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
235 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
236 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
237 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
238 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
239 cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
240 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
241 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
251 BUILD=$HOME/lilypond/build-website
254 cp $HOME/lilypond/trusted-scripts/website.make .
256 make -f website.make WEBSITE_ONLY_BUILD=1 website
257 rsync -raO $BUILD/out-website/website/ $DEST/website/
258 cp $BUILD/out-website/pictures $DEST
259 cp $BUILD/out-website/.htaccess $DEST
262 Cronjob to automate the trusted portions:
265 # website-rebuild.cron
266 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
267 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
271 @subsubheading Additional information
273 Some information about the website is stored in
274 @file{~graham/lilypond/*.txt}; this information should not be
275 shared with people without trusted access to the server.
278 @node Debugging website and docs locally
279 @section Debugging website and docs locally
283 Install apache2, or any other http server. These instructions
284 assume that you also enable @code{mod_userdir}, and use
285 @code{$HOME/public_html} as the location.
288 Build the online docs and website:
291 make WEB_TARGETS="offline online" doc
297 Move the built stuff into those directories. It's highly
298 recommended to have your build dir and www dir on the same
299 partition. (make @code{$HOME/public_html/} a symlink if
303 mv out-website/website/ $HOME/public_html
304 mv $HOME/public_html/website/pictures $HOME/public_html/
305 mkdir -p $HOME/public_html/doc/v2.13/
306 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
312 @node Translating the website
313 @section Translating the website
315 As it has much more audience, the website should be translated before
316 the documentation; see @ref{Translating the documentation}.
318 In addition to the normal documentation translation practices,
319 there are a few additional things to note:
324 Build the website with:
331 however, please note that this command is not designed for being
332 run multiple times. If you see unexpected output (mainly the page
333 footers getting all messed up), then delete your
334 @file{out-website} directory and run @code{make website} again.
337 Some of the translation infrastructure is defined in python files;
338 you must look at the @code{### translation data} sections in:
341 scripts/build/create-weblinks-itexi.py
342 scripts/build/website_post.py
346 Translations are not included by default in @code{make website}.
347 To test your translation, edit the @code{WEB_LANGS} line in
348 @file{make/website.make}. Do not submit a patch to add your language
349 to this file unless @code{make website} completes with less than 5
353 Links to manuals are done with macros like
354 @code{@@manualDevelLearningSplit}. To get translated links, you
355 must change that to @code{@@manualDevelLearningSplit-es} (for
356 es/Spanish translations, for example).