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 The website is generated hourly by user @code{graham} the host
62 @code{lilypond.org}. For security reasons, we do not use the
63 makefiles and scripts directly from git; copies of the relevant
64 scripts are examined and copied to
65 @code{~graham/lilypond/trusted-scripts/}
67 @subheading Initial setup
69 You should symlink your own @file{~/lilypond/} to
70 @file{~graham/@/lilypond/}
72 If this directory does not exist, make it. Git master should go
73 in @file{~/lilypond/@/lilypond@/-git/} but make sure you enable:
76 git config core.filemode false
79 If you have created any files in @file{~graham/@/lilypond/} then
83 chgrp lilypond ~graham/lilypond/ -R
84 chmod 775 ~graham/lilypond/ -R
87 To reduce the CPU burden on the shared host (as well as some
88 security concerns), the @file{Documentation/@/pictures/} and
89 @file{Documentation/@/web/@/ly-examples/} directories are
90 @strong{not} compiled. You need to upload them, and if they ever
91 change, a user in the @code{lilypond} group must upload them to
92 @file{~graham/@/lilypond@/media} on the host.
94 Upload latest pictures/ and ly-examples/ (local script):
96 @warning{You may need to change a number of items in the below
100 ### upload-lily-web-media.sh
102 BUILD_DIR=$HOME/src/build-lilypond
104 PICS=$BUILD_DIR/Documentation/pictures/out-www/
105 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
108 rsync -a $PICS graham@lilypond.org:lilypond/media/pictures
109 rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples
114 @subheading Normal maintenance
116 Get latest source code:
121 cd $HOME/lilypond/lilypond-git
123 git merge origin/master
126 Check for any updates to trusted scripts / files:
131 GIT=$HOME/lilypond/lilypond-git
132 DEST=$HOME/lilypond/trusted-scripts
133 diff -u $DEST/website.make $GIT/make/website.make
134 diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
135 diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
136 diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
137 diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
138 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
139 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
140 diff -u $DEST/bib2texi.py $GIT/scripts/build/bib2texi.py
141 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
142 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
145 If the changes look ok, make them trusted:
150 GIT=$HOME/lilypond/lilypond-git
151 DEST=$HOME/lilypond/trusted-scripts
152 cp $GIT/make/website.make $DEST/website.make
153 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
154 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
155 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
156 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
157 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
158 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
159 cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
160 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
161 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
170 BUILD=$HOME/lilypond/build-website
173 cp $HOME/lilypond/trusted-scripts/website.make .
175 make -f website.make WEBSITE_ONLY_BUILD=1 website
176 rsync -raO $BUILD/out-website/website/ $DEST/website/
177 cp $BUILD/out-website/pictures $DEST
178 cp $BUILD/out-website/.htaccess $DEST
181 Cronjob to automate the trusted portions:
184 # website-rebuild.cron
185 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
186 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
190 @subsubheading Additional information
192 Some information about the website is stored in
193 @file{~graham/@/lilypond/@/*.txt}; this information should not be
194 shared with people without trusted access to the server.
197 @node Debugging website and docs locally
198 @section Debugging website and docs locally
202 Install apache2, or any other http server. These instructions
203 assume that you also enable @code{mod_userdir}, and use
204 @code{$HOME/public_html} as the location.
207 Build the online docs and website:
210 make WEB_TARGETS="offline online" doc
216 Move the built stuff into those directories. It's highly
217 recommended to have your build dir and www dir on the same
218 partition. (make @code{$HOME/public_html/} a symlink if
222 mv out-website/website/ $HOME/public_html
223 mv $HOME/public_html/website/pictures $HOME/public_html/
224 mkdir -p $HOME/public_html/doc/v2.13/
225 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
231 @node Translating the website
232 @section Translating the website
234 As it has much more audience, the website should be translated before
235 the documentation; see @ref{Translating the documentation}.
237 In addition to the normal documentation translation practices,
238 there are a few additional things to note:
243 Build the website with:
250 however, please note that this command is not designed for being
251 run multiple times. If you see unexpected output (mainly the page
252 footers getting all messed up), then delete your
253 @file{out@/-website} directory and run @code{make website} again.
256 Some of the translation infrastructure is defined in python files;
257 you must look at the @code{### translation data} sections in:
260 scripts/build/create-weblinks-itexi.py
261 scripts/build/website_post.py
265 Translations are not included by default in @code{make website}.
266 To test your translation, edit the @code{WEB_LANGS} line in
267 @file{make/@/website@/.make}. Do not submit a patch to add your language
268 to this file unless @code{make website} completes with less than 5
272 Links to manuals are done with macros like
273 @code{@@manualDevelLearningSplit}. To get translated links, you
274 must change that to @code{@@manualDevelLearningSplit-es} (for
275 es/Spanish translations, for example).