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