]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/contributor/website-work.itexi
Doc-it: add the chapter "Templates" of LM, plus some updates and fixes
[lilypond.git] / Documentation / contributor / website-work.itexi
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Website work
3 @chapter Website work
4
5 @menu
6 * Introduction to website work::
7 * Uploading and security::
8 * Debugging website and docs locally::
9 * Translating the website::
10 @end menu
11
12
13 @node Introduction to website work
14 @section Introduction to website work
15
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
19
20 @example
21 Documentation/web.texi
22 Documentation/web/*.texi
23 @end example
24
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.
29
30 @subheading Exceptions to the documentation policies
31
32 @itemize
33
34 @item
35 Sectioning: the website only uses chapters and sections; no
36 subsections or subsubsections.
37
38 @item
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.
42
43 @item
44 The bibliography in Community->Publications is generated automatically
45 from @file{.bib} files; formatting is done automatically by
46 @file{texi-web.bst}.
47
48 @item
49 @dots{}
50
51 @item
52 For anything not listed here, just follow the same style as the
53 existing website texinfo files.
54
55 @end itemize
56
57
58 @node Uploading and security
59 @section Uploading and security
60
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/}
66
67 @subheading Initial setup
68
69 You should symlink your own @file{~/lilypond/} to
70 @file{~graham/lilypond/}
71
72 If this directory does not exist, make it.  Git master should go
73 in @file{~/lilypond/lilypond-git/} but make sure you enable:
74
75 @example
76 git config core.filemode false
77 @end example
78
79 If you have created any files in @file{~graham/lilypond/} then
80 please run:
81
82 @example
83 chgrp lilypond ~graham/lilypond/ -R
84 chmod 775 ~graham/lilypond/ -R
85 @end example
86
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.
93
94 Upload latest pictures/ and ly-examples/ (local script):
95
96 @warning{You may need to change a number of items in the below
97 script.}
98
99 @verbatim
100 ### upload-lily-web-media.sh
101 #!/bin/sh
102 BUILD_DIR=$HOME/src/build-lilypond
103
104 PICS=$BUILD_DIR/Documentation/pictures/out-www/
105 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
106
107 cd $BUILD_DIR
108 rsync -a $PICS graham@lilypond.org:lilypond/media/pictures
109 rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples
110 @end verbatim
111
112
113
114 @subheading Normal maintenance
115
116 Get latest source code:
117
118 @verbatim
119 ### update-git.sh
120 #!/bin/sh
121 cd $HOME/lilypond/lilypond-git
122 git fetch origin
123 git merge origin/master
124 @end verbatim
125
126 Check for any updates to trusted scripts / files:
127 @smallexample
128 @verbatim
129 ### check-git.sh
130 #!/bin/sh
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
143 @end verbatim
144
145 If the changes look ok, make them trusted:
146
147 @verbatim
148 ### copy-from-git.sh
149 #!/bin/sh
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
162 @end verbatim
163 @end smallexample
164
165 Build the website:
166
167 @verbatim
168 ### make-website.sh
169 #!/bin/sh
170 DEST=$HOME/web/
171 BUILD=$HOME/lilypond/build-website
172 mkdir -p $BUILD
173 cd $BUILD
174 cp $HOME/lilypond/trusted-scripts/website.make .
175
176 make -f website.make WEBSITE_ONLY_BUILD=1 website
177 rsync -raO $BUILD/out-website/website/ $DEST/website/
178 cp $BUILD/out-website/pictures $DEST
179 cp $BUILD/out-website/.htaccess $DEST
180 @end verbatim
181
182 Cronjob to automate the trusted portions:
183
184 @verbatim
185 # website-rebuild.cron
186 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
187 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
188 @end verbatim
189
190
191 @subsubheading Additional information
192
193 Some information about the website is stored in
194 @file{~graham/lilypond/*.txt}; this information should not be
195 shared with people without trusted access to the server.
196
197
198 @node Debugging website and docs locally
199 @section Debugging website and docs locally
200
201 @itemize
202 @item
203 Install apache2, or any other http server.  These instructions
204 assume that you also enable @code{mod_userdir}, and use
205 @code{$HOME/public_html} as the location.
206
207 @item
208 Build the online docs and website:
209
210 @example
211 make WEB_TARGETS="offline online" doc
212 make website
213 @end example
214
215
216 @item
217 Move the built stuff into those directories.  It's highly
218 recommended to have your build dir and www dir on the same
219 partition.  (make @code{$HOME/public_html/} a symlink if
220 necessary)
221
222 @example
223 mv out-website/website/ $HOME/public_html
224 mv $HOME/public_html/website/pictures $HOME/public_html/
225 mkdir -p $HOME/public_html/doc/v2.13/
226 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
227 @end example
228
229 @end itemize
230
231
232 @node Translating the website
233 @section Translating the website
234
235 As it has much more audience, the website should be translated before
236 the documentation; see @ref{Translating the documentation}.
237
238 In addition to the normal documentation translation practices,
239 there are a few additional things to note:
240
241 @itemize
242
243 @item
244 Build the website with:
245
246 @example
247 make website
248 @end example
249
250 @noindent
251 however, please note that this command is not designed for being
252 run multiple times.  If you see unexpected output (mainly the page
253 footers getting all messed up), then delete your
254 @file{out-website} directory and run @code{make website} again.
255
256 @item
257 Some of the translation infrastructure is defined in python files;
258 you must look at the @code{### translation data} sections in:
259
260 @example
261 scripts/build/create-weblinks-itexi.py
262 scripts/build/website_post.py
263 @end example
264
265 @item
266 Translations are not included by default in @code{make website}.
267 To test your translation, edit the @code{WEB_LANGS} line in
268 @file{make/website.make}.  Do not submit a patch to add your language
269 to this file unless @code{make website} completes with less than 5
270 warnings.
271
272 @item
273 Links to manuals are done with macros like
274 @code{@@manualDevelLearningSplit}.  To get translated links, you
275 must change that to @code{@@manualDevelLearningSplit-es} (for
276 es/Spanish translations, for example).
277
278 @end itemize
279
280
281