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 @subheading Building the website from scratch for local checking
  62
  63 Initial setup:
  64
  65 Create directories:
  66
  67 @example
  68 $HOME/lilypond/
  69 $HOME/lilypond/media/
  70 $HOME/lilypond/trusted-scripts/
  71 @end example
  72
  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.
  77
  78 Go to your lilypond build directory.  make doc.
  79
  80 Set up some variables (you'll only do this once:)
  81
  82 @example
  83 BUILD_DIR=$HOME/lilypond-git
  84 PICS=$BUILD_DIR/Documentation/pictures/
  85 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/
  86 @end example
  87
  88 Copy files over:
  89
  90 @example
  91 cp -r $PICS $HOME/lilypond/media/pictures
  92 cp -r $EXAMPLES $HOME/lilypond/media/ly-examples
  93 @end example
  94
  95 Get the scripts you need.  First define these variables:
  96
  97 @example
  98 GIT=$HOME/lilypond-git
  99 DEST=$HOME/lilypond/trusted-scripts
 100 @end example
 101
 102 Then do the copying:
 103
 104 @smallexample
 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
 115 @end smallexample
 116
 117 Delete your build directory (or maybe just rename your build
 118 directory to build-old).
 119
 120 @example
 121 cd $HOME/lilypond
 122 @end example
 123
 124 Run
 125
 126 @example
 127 make -f ../lilypond-git/make/website.make WEBSITE_ONLY_BUILD=1 \
 128   TOP_SRC_DIR=$HOME/lilypond-git/ \
 129   TEXI2HTML_PROGRAM=texi2html \
 130   website
 131 @end example
 132
 133 The website should be at:
 134
 135 @example
 136 $HOME/lilypond/out-website/website/index.html
 137 @end example
 138
 139 @subheading Building the online website
 140
 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/}
 146
 147 @subheading Initial setup
 148
 149 You should symlink your own @file{~/lilypond/} to
 150 @file{~graham/lilypond/}
 151
 152 If this directory does not exist, make it.  Git master should go
 153 in @file{~/lilypond/lilypond-git/} but make sure you enable:
 154
 155 @example
 156 git config core.filemode false
 157 @end example
 158
 159 If you have created any files in @file{~graham/lilypond/} then
 160 please run:
 161
 162 @example
 163 chgrp lilypond ~graham/lilypond/ -R
 164 chmod 775 ~graham/lilypond/ -R
 165 @end example
 166
 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.
 173
 174 Upload latest pictures/ and ly-examples/ (local script):
 175
 176 @warning{You may need to change a number of items in the below
 177 script.}
 178
 179 @verbatim
 180 ### upload-lily-web-media.sh
 181 #!/bin/sh
 182 BUILD_DIR=$HOME/src/build-lilypond
 183
 184 PICS=$BUILD_DIR/Documentation/pictures/out-www/
 185 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
 186
 187 cd $BUILD_DIR
 188 rsync -a $PICS graham@lilypond.org:lilypond/media/pictures
 189 rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples
 190 @end verbatim
 191
 192
 193
 194 @subheading Normal maintenance
 195
 196 Get latest source code:
 197
 198 @verbatim
 199 ### update-git.sh
 200 #!/bin/sh
 201 cd $HOME/lilypond/lilypond-git
 202 git fetch origin
 203 git merge origin/master
 204 @end verbatim
 205
 206 Check for any updates to trusted scripts / files:
 207 @smallexample
 208 @verbatim
 209 ### check-git.sh
 210 #!/bin/sh
 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
 223 @end verbatim
 224
 225 If the changes look ok, make them trusted:
 226
 227 @verbatim
 228 ### copy-from-git.sh
 229 #!/bin/sh
 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
 242 @end verbatim
 243 @end smallexample
 244
 245 Build the website:
 246
 247 @verbatim
 248 ### make-website.sh
 249 #!/bin/sh
 250 DEST=$HOME/web/
 251 BUILD=$HOME/lilypond/build-website
 252 mkdir -p $BUILD
 253 cd $BUILD
 254 cp $HOME/lilypond/trusted-scripts/website.make .
 255
 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
 260 @end verbatim
 261
 262 Cronjob to automate the trusted portions:
 263
 264 @verbatim
 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
 268 @end verbatim
 269
 270
 271 @subsubheading Additional information
 272
 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.
 276
 277
 278 @node Debugging website and docs locally
 279 @section Debugging website and docs locally
 280
 281 @itemize
 282 @item
 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.
 286
 287 @item
 288 Build the online docs and website:
 289
 290 @example
 291 make WEB_TARGETS="offline online" doc
 292 make website
 293 @end example
 294
 295
 296 @item
 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
 300 necessary)
 301
 302 @example
 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/
 307 @end example
 308
 309 @end itemize
 310
 311
 312 @node Translating the website
 313 @section Translating the website
 314
 315 As it has much more audience, the website should be translated before
 316 the documentation; see @ref{Translating the documentation}.
 317
 318 In addition to the normal documentation translation practices,
 319 there are a few additional things to note:
 320
 321 @itemize
 322
 323 @item
 324 Build the website with:
 325
 326 @example
 327 make website
 328 @end example
 329
 330 @noindent
 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.
 335
 336 @item
 337 Some of the translation infrastructure is defined in python files;
 338 you must look at the @code{### translation data} sections in:
 339
 340 @example
 341 scripts/build/create-weblinks-itexi.py
 342 scripts/build/website_post.py
 343 @end example
 344
 345 @item
 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
 350 warnings.
 351
 352 @item
 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).
 357
 358 @end itemize
 359
 360
 361